Stripe Connect Payouts: A Production Checklist for When Sellers Aren't Getting Paid

When a seller on your marketplace emails "where's my money?", the answer is almost never "Stripe is down." It's usually one of a handful of states your platform didn't model: a balance that is still pending, a payout schedule you never set, a failed bank account that silently disabled payouts, or a refund that took money from the wrong balance.

This is the checklist I run before touching code. It assumes Stripe Connect with Express or Custom accounts, where your platform controls payouts. Every behavior below is from Stripe's current docs, linked at the end.

First, know which balance the money is in

Your platform and every connected account are separate Stripe accounts, each with its own pending and available balance. Where a payment lands depends on the charge type:

• Direct charges land on the connected account.
• Destination charges and separate charges and transfers land on your platform first, then move to the seller by transfer.

If you're not sure which one you built, start with direct vs destination vs separate charges. Half of payout confusion is looking at the wrong balance.

To see what a seller actually has, retrieve the balance *as the connected account* (send the Stripe-Account header). That one call answers "is it pending, available, or already paid out?"

The 9 checks

1. Is the account actually allowed to receive payouts?

Before anything else, check payouts_enabled and the requirements hash on the account. A seller who never finished onboarding, or who has a new currently_due requirement, can't be paid no matter what the balance says. Listen for account.updated and surface missing requirements in your seller dashboard instead of waiting for support tickets. I cover the full status machine in Stripe Connect KYC and Express onboarding.

2. Is the money still pending?

New funds sit in pending before they become available. For a standard Stripe account that's a rolling window (Stripe's docs use 2 days as the example, and it varies by country and account). Sellers read "payment succeeded" as "money is mine now." Your UI should show pending and available separately, with an expected date.

3. What payout schedule is the account on?

By default, funds on a connected account are paid out on a daily rolling basis. If your platform owns fraud and dispute liability (or has platform controls), you can change the interval to manual, daily, weekly (with weekly_payout_days), or monthly (with monthly_payout_days).

The trap: someone sets manual for testing, or to enable Instant Payouts, and nobody builds the job that actually creates payouts. On manual, nothing leaves the balance until you call the Payouts API as the connected account.

4. Did someone change delay_days?

delay_days controls how long charges take to become available for payout. On accounts where you own liability you can set delay_days_override up to 31. That's useful for marketplaces that pay out after a service is completed, but it is also an easy way to make every seller wait a month without meaning to. Note that Stripe counts business days or calendar days depending on the account's country.

5. Did a transfer fail because your platform balance was short?

With separate charges and transfers, a transfer pulls from your platform's available balance by default. If that balance is too low, the transfer fails with an error, and Stripe does not retry it later when funds arrive. You have to try again yourself.

The fix is to pass the charge ID as source_transaction when creating the transfer. The transfer then succeeds even if the charge hasn't settled, and the funds become available to the seller when the original charge does. Use transfer_group to tie every transfer for an order together so reconciliation is one query, not a spreadsheet.

6. Did a payout fail and disable the bank account?

When a payout fails, its status becomes failed and failure_code says why. Stripe also disables that external account, and no automatic or manual payouts go out until the bank details are updated. You get payout.failed and account.external_account.updated.

If you don't listen for those, the seller just stops getting paid and nobody on your side knows. Handle payout.failed by flagging the seller, emailing them a link to update their bank account, and showing a banner in their dashboard.

7. Is the connected account's balance negative?

Refunds and chargebacks create negative transactions. Stripe first takes them from the account the charge was made on, then tries to offset them against future payments. But a connected balance can still go negative, and while it is, you can't pay out to that account. Payouts resume once the balance is positive again.

Two things to know:

• Who pays for that negative balance is on the account: controller.losses.payments (Accounts v1) is stripe or application. If it's application, it's you. See marketplace fraud and risk for why that matters.
• When your platform is liable, Stripe holds a reserve on your platform balance to cover it. If a connected account stays negative for 180 days, Stripe moves that reserve over to zero it out (a "Connect collection transfer"). You can let Stripe debit the seller's bank to recover it with debit_negative_balances in supported countries.

8. Did a refund take money from the wrong place?

This is one of the easiest ways for a marketplace to lose money without noticing.

• With separate charges and transfers, refunding the charge has no effect on the transfer. The seller keeps the money and your platform eats the refund, unless you reverse the transfer or net it out of a later payout.
• With destination charges, the refund API has reverse_transfer (pull back from the seller proportionally) and refund_application_fee (give back your fee proportionally). Both default to off.

Transfer reversals only work if the seller's available balance covers the amount (or connected reserves are enabled). So reverse early, ideally in the same job that issues the refund, before the funds are paid out. Decide the refund policy per order type and write it down; "who pays for a refund?" is a product decision, not a code detail.

9. Are you actually receiving Connect webhooks?

Connect events come in two scopes, and they need separate endpoints: one for "your account" and one for "connected accounts" (connect: true when created by API). account.updated, payout.failed, and direct-charge events for your sellers come through the connected-accounts endpoint, with a top-level account field telling you which seller. If you only registered one endpoint, you're blind to half your payout events.

Then make the handler production-safe:

• Verify the signature on the raw request body and return 2xx before slow work.
• Stripe retries failed deliveries for up to three days in live mode and doesn't guarantee order. Store processed event.ids and skip duplicates. Don't use created to order events.
• Check livemode: a production Connect endpoint receives both live and test events.
• Use idempotency keys on the transfers and refunds your handler creates, so a retry never pays a seller twice.

I go deeper on the handler itself in Stripe webhooks in Next.js, production edition.

A quick triage order

When a seller reports a missing payout:

1. Retrieve the account: payouts_enabled, requirements.
2. Retrieve the balance as that account: pending, available, negative?
3. List recent payouts for the account: any failed, and what failure_code?
4. Check the payout schedule and delay_days.
5. For platform-first charges, find the transfer for the order (transfer_group) and check it exists and wasn't reversed.
6. Check your webhook endpoint's delivery log for errors.

Most of the time you have the answer by step 3.

When to bring in help

If you're seeing the same payout bug more than once, the issue usually isn't one handler. It's that money state lives in Stripe while your app has its own idea of what each seller is owed. That's the work I do on Stripe Connect integration projects: map the fund flow, make webhooks the source of truth, and add the reconciliation that makes "where's my money?" a lookup instead of an investigation. For a whole platform, see full marketplace builds.

A money-flow check starts at $800, and adding payouts to an app you already have starts at $2,500. Those are starting points that flex with what's already built; we agree scope on a free call. Book a 30-minute call or send a brief.

Sources

Stripe docs, checked November 2026: Manage connected account payouts · Connect account balances · Manage payout schedule · Separate charges and transfers · Create a refund · Create a transfer · Connect webhooks · Webhooks