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.Rejectedwith 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
:connectcapability. Stripe has it. PayPal ignoresaccount_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:
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
endThe 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:
{: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: :v1in the platform's keys, orapi: :v1on 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. configurationsleft out is[:merchant, :recipient]. A merchant takes card payments. A recipient takes transfers into its balance.dashboardis:express(the default),:fullor:none.- The
referencemakes 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.
{: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:
{: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. Addapplication_fee(money, one-time checkouts) orapplication_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 withon_behalf_of:. The payment lives on the platform and Stripe moves it on.
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
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/1needs areference, which makes it once.source_charge_idmakes the transfer wait for that sale's money.- Payout calls act on the account the keys act for. With a site's
account_idthat is the seller's. Only a:pendingpayout 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
- Receive and verify webhooks: the endpoint, thin events and replay.
- Keys and options:
account_id,connect_apiand the other key fields. - Keep payments in Ash resources and Mishka CMS: one row per site for the same Stripe object.