billingHelp

Paying payees with Stripe

Turning on Connect for your own Stripe account so it can pay your payees, how payees set up their accounts, Transfers from your balance, webhooks, sandbox testing and common errors.

To pay payees through Stripe, your own Stripe account becomes a Connect platform for them. Payees get accounts connected to your account, and their shares move from your Stripe balance to theirs as Stripe Transfers. Stripe then pays them to their bank. The billing platform is not involved in the money and charges nothing.

1. Turn on Connect#

  1. In the Stripe Dashboard of the account your customers pay (the one in your Stripe credential set), open Connect and choose Get started.
  2. Complete Stripe's platform profile. Choose that you will onboard accounts with Stripe-hosted onboarding and that you pay out (payees receive transfers; they do not take payments).
  3. Do the same in test mode first if you want to rehearse.

Payees get Express accounts. With Express accounts Stripe holds the platform — you — responsible for a payee account's negative balance; since payees only receive transfers, that happens only if you reverse a transfer that they have already paid out to their bank.

2. Choose the account in Payouts → Settings#

Under Stripe account, choose that Stripe credential set (it must use your own keys). Payouts in Live batches need a Live set; Test batches a Test set.

Add transfer.reversed to the set's webhook (Stripe → Developers → Webhooks → your endpoint → add event), so a transfer you reverse in the Dashboard puts the money back on the payee's balance here.

3. Payees set up their accounts#

Add the payee with Paid by: Stripe transfer and send the invitation. In their earnings page the payee presses Set up payouts with Stripe; Stripe asks for their details and bank account on its own pages and brings them back. When Stripe enables transfers for the account, the payee becomes Active. You can press Check status now on the payee's page; otherwise the system asks Stripe every 15 minutes while the payee is onboarding.

4. Payouts#

Each payout in a batch is one Transfer (POST /v1/transfers) from your balance, with the payout's id as Idempotency-Key, so a retry after a timeout never pays twice. A transfer needs that much available balance in your Stripe account; card payments become available on Stripe's own schedule. If it is not enough, the payout fails and the money returns to the payee's balance for the next batch.

If you reverse a transfer in Stripe (all or part), the reversal comes back through the transfer.reversed webhook: a full reversal makes the payout Returned, a partial one adds one adjustment to the payee's ledger. As a safety net the system also reads each paid transfer (GET /v1/transfers/{id}) once a day for 30 days after it was paid, so a missed webhook still gets booked; each reversal is booked once.

Sandbox test#

  1. Test-mode Stripe set chosen in Settings; a test product with a revenue share.
  2. Add a payee (Stripe), invite, complete Stripe's test onboarding with Stripe's test data.
  3. Pay with a test card that adds to your available balance immediately (Stripe's 4000 0000 0000 0077).
  4. Payouts → Test mode → Build a test batch → Send. The payout shows Paid with a tr_… reference; the transfer appears in Stripe → Connect → the payee's account.

Common errors#

MessageFix
Only Stripe Connect platforms can work with other accountsConnect is not turned on for this Stripe account (step 1).
Your destination account needs … transfersStripe has not enabled transfers to the payee yet; they must finish onboarding.
You have insufficient available fundsYour Stripe balance is not available yet; wait or add funds, then build the next batch.
No such destinationThe payee's account was rejected or removed in Stripe; ask the payee to set up again.