Run many sites on one Stripe platform

v0.0.1

A platform that hosts many sites, such as a multi-site Mishka CMS install or a marketplace, can keep one Stripe secret key and give each site its own Stripe connected account. The payments, customers and refunds of a site then live on that site's account. This guide creates a connected account, onboards its owner, points the site's keys at it, takes the platform's cut and moves money to a seller.

Before you begin

  • A Stripe platform account that has signed up for Connect. Without it, account calls answer Errors.Rejected with code "connect_not_set_up".
  • A Stripe sandbox for development. Some flows, such as v2 onboarding for a seller that takes transfers, only run in a sandbox. In an account's plain test mode they answer "connect_needs_sandbox".
  • A keys plugin that can answer different keys per site. See Keys and options.
  • The provider needs the :connect capability. Stripe has it. PayPal ignores account_id.

Keep the platform's keys apart from the sites'

Keys without account_id are the platform itself. Keys with account_id make every Stripe request for that site carry the connected account:

elixir
def credentials("stripe", "platform"),
  do: %{
    secret_key: System.fetch_env!("STRIPE_SECRET_KEY"),
    mode: :test,
    webhook_secret:
      System.fetch_env!("STRIPE_CONNECT_WEBHOOK_SECRET")
  }

def credentials("stripe", site_id) do
  case MyApp.Sites.payment_settings(site_id) do
    %{stripe_account_id: "acct_" <> _ = account} ->
      %{
        secret_key: System.fetch_env!("STRIPE_SECRET_KEY"),
        account_id: account,
        mode: :test
      }

    _no_account ->
      nil
  end
end

The account header comes only from the keys. No call, request option or raw request can set it, so one site's code cannot act on another's account. An account_id that does not start with acct_ is Errors.Invalid on :account_id before any request.

Create a connected account

Use the platform's keys, so call it with the platform tenant:

elixir
{:ok, account} =
  MishkaPay.create_connected_account(%{
    provider: "stripe",
    tenant: "platform",
    configurations: [:merchant, :recipient],
    dashboard: :express,
    country: "NL",
    email: site.owner_email,
    business_name: site.name,
    reference: "site-" <> site.id
  })
  • Stripe's Accounts v2 is the default. Set connect_api: :v1 in the platform's keys, or api: :v1 on a call, for Accounts v1, which you still need for OAuth connections, Treasury and card issuing. A platform that turned Connect on lately can make accounts only on v2.
  • configurations left out is [:merchant, :recipient]. A merchant takes card payments. A recipient takes transfers into its balance.
  • dashboard is :express (the default), :full or :none.
  • The reference makes the idempotency key, so a retry never makes a second account.

Store account.id (an acct_... id) with the site and answer it as account_id from the site's keys.

Onboard the seller

Make an onboarding link for each click and redirect at once. It works once and runs out in minutes.

elixir
{:ok, link} =
  MishkaPay.account_link(%{
    provider: "stripe",
    tenant: "platform",
    account_id: account.id,
    type: :onboarding,
    refresh_url: url(~p"/admin/payments/retry"),
    return_url: url(~p"/admin/payments/done")
  })

redirect(conn, external: link.url)

Coming back to return_url does not mean the account is ready. Read it and look at :charges_enabled, :payouts_enabled, :transfers_enabled and :requirements_due:

elixir
{:ok, account} =
  MishkaPay.fetch_connected_account(
    "stripe",
    account.id,
    "platform"
  )

:requirements_due lists what Stripe still waits for from the seller. login_link/3 opens the Express dashboard for an account that finished onboarding. close_connected_account/4 is for good.

Sell for a site or a seller

There are two ways.

  • Direct charge. The site's keys name its account_id, so the checkout is made on the seller's own account. Add application_fee (money, one-time checkouts) or application_fee_percent (subscriptions, above 0 up to 100) for the platform's cut.
  • Destination charge. The platform's keys make the checkout with destination: "acct_...", usually with on_behalf_of:. The payment lives on the platform and Stripe moves it on.
elixir
MishkaPay.checkout(%{
  provider: "stripe",
  tenant: "platform",
  items: [
    %{
      name: "Print",
      amount: %{amount: "40", currency: "USD"}
    }
  ],
  success_url:
    url(~p"/thanks") <> "?session_id={CHECKOUT_SESSION_ID}",
  cancel_url: url(~p"/cart"),
  reference: order.id,
  destination: seller.stripe_account_id,
  on_behalf_of: seller.stripe_account_id,
  application_fee: %{amount: "4", currency: "USD"}
})

None of these options goes with mode: :setup. Money reaches a v2 account only once its recipient transfers are active (:transfers_enabled). Before that, Stripe answers code "insufficient_capabilities_for_transfer".

Move money between accounts

elixir
MishkaPay.create_transfer(%{
  provider: "stripe",
  tenant: "platform",
  amount: %{amount: "30", currency: "USD"},
  destination: "acct_...",
  reference: "payout-order-9"
})

MishkaPay.reverse_transfer(
  "stripe",
  "tr_...",
  "platform",
  amount: %{amount: "5", currency: "USD"},
  reference: "rev-1"
)

MishkaPay.refund_application_fee(
  "stripe",
  "fee_...",
  "platform",
  reference: "fee-refund-1"
)

MishkaPay.list_payouts("stripe", site.id, status: :paid)
  • create_transfer/1 needs a reference, which makes it once. source_charge_id makes the transfer wait for that sale's money.
  • Payout calls act on the account the keys act for. With a site's account_id that is the seller's. Only a :pending payout can be canceled.
  • Ids are checked by prefix before any request: tr_ transfers, po_ payouts, fee_ application fees, acct_ accounts.

Receive Connect webhooks

A tenant whose keys name an account_id takes only events that name that account. An event for the platform or for another connected account is refused with 400. Mishka Pay never routes an event to another site, because a message checked with one site's secret must never act on another site's data.

So subscribe one Connect endpoint ("Events from: Connected accounts") to the platform's own tenant URL, such as /pay/webhooks/stripe/platform. Each event there carries event.account, and your listener finds the site from it. With the Mix task, add --connected-accounts. Never point a Connect endpoint at a site's URL when the platform has more than one connected account.

Next steps