Skip to content

Marketplaces and seller splits

A marketplace sells for other businesses. A buyer pays once, the marketplace is the merchant of record, and each seller gets its share. In Flint, that share is a split: a fixed part of one payment that moves into a seller's own Flint balance after the payment's funds are available. The seller's normal payouts carry it to the seller's bank account.

For example, Craftly runs a handmade goods marketplace. A buyer orders a $70.00 mug set from Mugworks and a $30.00 scarf from Loom & Co. Craftly creates one $100.00 payment with two splits: $60.00 to Mugworks and $25.00 to Loom & Co. Flint's card fee on the payment is $4.14 at the published rate of 3.79% + 35¢, so Craftly keeps $10.86.

Warning: Live splits need Flint's approval

Test mode works now, with no review. Live splits are switched off by default. They're available after Flint approves your platform for splits, and Flint publishes the rules for sending, reversing, and recovering split funds in the Flint Platform Agreement before it accepts them. Until then, a live request with splits returns 409 MERCHANT_NOT_READY with reason payment_splits_unavailable.

Splits, split tender, and transfers#

Three Flint features use the word "split" or "transfer" for different things.

What it dividesWho is involvedWhere to read it
SplitsOne payment's funds, between the marketplace and its sellersMerchantsChoose how to take money
Split tenderHow a buyer pays one order, with several payment methods or gift cardsOne merchant and one buyerGift cards and Pay in more than one leg
Inventory transfersStock, between a merchant's locationsOne merchantTrack inventory

A payment with splits can still be one leg of a split tender order. The two divide different things.

Choose how to take money#

You areUseWho is merchant of record
A marketplace that collects one buyer payment covering several sellersSplitsYou
A marketplace whose sellers each take their own payment, such as one checkout per sellerPayments created for each seller, with a platform feeEach seller
A software platform whose merchants sell to their own customersA platform fee on each paymentEach merchant

As merchant of record for a split payment, you answer for its refunds and disputes in full, including the part you sent to a seller. Sellers don't see the buyer, and a seller's balance only ever pays back its own share.

What you need#

  • Your own merchant account, with accept_card_payments and receive_payouts ready. It collects every split payment, and you create the payment with its API key.
  • A partner app that declares payment_splits. It names your terms for sellers. See Declare payment splits.
  • Sellers that installed your app and approved receiving splits. Each seller is a Flint merchant with receive_payouts ready in the payment's mode.
  • In live mode, Flint's approval of your platform for splits. Declaring payment_splits requests it. Test mode never checks it.

Onboard sellers#

A seller is a verified Flint merchant that installed your partner app. Flint has no lighter recipient type: a seller has its own balance, payouts, ledger, and dashboard.

  1. Set payment_splits.seller_terms_url on your app. In the dashboard, open Developers > Partner apps, choose your app, open the Platform tab, and add the address in Seller terms. Setting it needs no review. If your platform is already approved, adding the declaration moves it to limited until Flint approves payment_splits; platform fees and onboarding keep working.
  2. Send each seller through your authorize URL. The consent screen links your seller terms and says what the seller agrees to: you take its share back when you refund a sale, lose a dispute, or a payment fails. Merchant signups are not available yet. Have new sellers create a Flint account through onboarding or flint signup, then use the consent-screen install.
  3. Store the partner_app_install_id from the code exchange, or read it from your app's installs.
  4. Check that the seller can receive. Each active grant that holds a profile scope shows merchant_readiness; payouts.status must be ready. See See which merchants can take payments.

The seller approves in test and live separately. Its approval shows as payment_splits on the environment grant, with seller_terms_url and approved_at. In the seller's dashboard, Settings > Connected apps shows the approval date, a link to the terms it approved, and a plain statement of what you can take back.

If you change seller_terms_url, sellers that already approved keep the terms they approved. If you remove payment_splits, every approval ends at once, and a seller must authorize again after you declare it again. A seller that disconnects stops new splits, but refunds and disputes on earlier sales still take its share back.

Create a payment with splits#

Send splits with the request that creates the payment, using your own API key. A partner app token can't.

cURL
curl -X POST https://api.withflintpay.com/v1/payment-intents \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Flint-Version: 2026-09-07" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: craftly-order-1042" \
  -d '{
    "amount_money": {"amount": 10000, "currency": "USD"},
    "payment_options": ["card"],
    "splits": [
      {
        "partner_app_install_id": "pinst_01KF3A8C2D4E6F8G0H2J4K6M8N",
        "amount_money": {"amount": 6000, "currency": "USD"},
        "description": "Order 1042: 2 stoneware mugs",
        "external_reference_id": "1042-mugworks"
      },
      {
        "partner_app_install_id": "pinst_01KF3A9N4P6Q8R0S2T4V6W8X0Y",
        "amount_money": {"amount": 2500, "currency": "USD"},
        "external_reference_id": "1042-loom"
      }
    ]
  }'

Send 1 to 25 splits, at most one per seller install, each above zero in the payment's currency. description and external_reference_id are yours, and the seller sees both. splits is part of the idempotency fingerprint.

The payment intent comes back with each split and what you keep:

Response
{
  "payment_intent_id": "pi_01KF4B1Z3X5C7V9B1N3M5Q7W9E",
  "amount_money": {"amount": 10000, "currency": "USD"},
  "splits": [
    {
      "payment_split_id": "psplit_01KF4B2C4D6E8F0G2H4J6K8M0N",
      "partner_app_install_id": "pinst_01KF3A8C2D4E6F8G0H2J4K6M8N",
      "seller_merchant_id": "mer_01KF3A7B1C3D5E7F9G1H3J5K7M",
      "status": "pending",
      "pending_reason": "awaiting_payment",
      "amount_money": {"amount": 6000, "currency": "USD"},
      "reversed_money": {"amount": 0, "currency": "USD"},
      "shortfall_money": {"amount": 0, "currency": "USD"},
      "funds_available_at": null,
      "reversals": []
    }
  ]
}

Once the payment succeeds and Flint has verified the fees, merchant_net_money is the captured amount minus the processing fee, add-on fees, and each split: $10.86 on Craftly's payment. Refunds don't change it.

Which requests accept splits#

RequestAccepts splits
POST /v1/payment-intentsYes
POST /v1/payment-intents with order_idYes. See Divide a payment between sellers.
POST /v1/orders/{order_id}/pay with action: payYes, when the request creates a card or bank payment.
POST /v1/payment-intents/{payment_intent_id}/captureYes, with the final amount of each split. See Capture a payment with splits.
PATCH /v1/payment-intents/{payment_intent_id}No. To change the sellers before confirmation, cancel the payment intent and create another.
Checkout sessions, payment links, invoices, and subscriptionsNo.

A payment created without splits never gains them.

Collect the payment#

Flint doesn't collect a split payment on your connected payment account, so the browser setup differs from other payments. Initialize Stripe.js with your Flint publishable key alone and leave out stripeAccount. client_confirmation.stripe.account_id is null on these payments. Buyers enter a new payment method for each split payment; saved payment methods, stripe_payment_method credentials, and save_payment_method: true are refused. Divide a payment between sellers has the details.

What Flint checks first#

RefusalCause and next step
400 INVALID_REQUEST, INVALID_VALUE at splits, with maximum_moneyThe splits leave too little for Flint's largest fee across the offered payment options and one minor unit for you. Lower the total to maximum_money.
400 INVALID_REQUEST, NOT_ALLOWEDAn install token or a platform_fee was sent, a saved payment method or off-session charge was requested, param names another input splits can't combine with, or an install belongs to another app or merchant.
404 RESOURCE_NOT_FOUND at splits[i].partner_app_install_idThe install doesn't exist.
409 ACTION_NOT_ALLOWED, payment_split_consent_requiredThe seller hasn't approved splits in this mode. Send it through the authorize URL.
409 ACTION_NOT_ALLOWED, seller_not_readyThe seller can't receive payouts in this mode. It finishes onboarding.
409 MERCHANT_NOT_READY, capability_unavailableYour account's accept_card_payments or receive_payouts isn't ready.
409 MERCHANT_NOT_READY, payment_splits_unavailableFlint can't collect split payments on this account, or, in live mode, live splits aren't switched on. Contact Flint support.
409 ACTION_NOT_ALLOWED, platform_* reasonsIn live mode, your app's payment_splits capability isn't active. See When Flint refuses a platform capability.

A payment with splits can't carry a platform fee. Your commission is the part you don't send: what's left after Flint's fees and every split.

When sellers are paid#

A split doesn't reach the seller when the buyer pays. Flint transfers it after the payment's funds are available on Flint's balance, which takes about two business days for US cards, and after any dispute on the payment has closed. Until then the split is pending, and pending_reason says why:

pending_reasonMeaning
awaiting_paymentThe payment hasn't succeeded.
awaiting_fundsThe payment succeeded. The funds become available at funds_available_at.
dispute_openA dispute or inquiry on the payment is open. The split transfers after it closes.
reversals_pendingRefunds or disputes took back the whole split, and their outcomes are still pending.

Show sellers pending_reason and funds_available_at so they know when to expect the money. funds_available_at is null until Stripe reports it, a few seconds after the payment succeeds.

statusMeaning
pendingWaiting, as above.
processingFlint released the split and is transferring it. It retries while the seller can't receive.
succeededThe split is in the seller's balance, available at once. A seller's payout carries it to its bank.
failedThe seller couldn't receive it within seven days. The remaining amount went to you as a payment_split_failure.
canceledThe split will never transfer. canceled_reason is payment_not_completed, install_revoked, or fully_reversed.

succeeded, failed, and canceled are final. Reversals change amounts, not status. If a seller's approval ends before capture, its split is canceled with install_revoked, and the amount stays with you.

You can't hold a split until delivery, and you can't release one early. Flint transfers each split when its funds are available.

Refund a split payment#

Only you, the collecting merchant, can refund a payment with splits. Create the refund as usual:

cURL
curl -X POST https://api.withflintpay.com/v1/refunds \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Flint-Version: 2026-09-07" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: refund-pi-1042-partial" \
  -d '{
    "refund_type": "amount",
    "payment_intent_id": "pi_01KF4B1Z3X5C7V9B1N3M5Q7W9E",
    "amount_money": {"amount": 4000, "currency": "USD"}
  }'

With no split_reversals, Flint takes each party's share back in proportion. On Craftly's $100.00 payment, a $40.00 refund takes $24.00 from Mugworks, $10.00 from Loom & Co, and $6.00 from Craftly's share. Flint rounds across the splits, so repeated small refunds never strand a cent.

To choose the amounts, send split_reversals. The list is exhaustive: a split you don't name gives back nothing. Send [] to fund the whole refund yourself. Refund a split payment has the shape and its errors.

  • You fund whatever the sellers don't give back, first from your share of that payment, then from your balance.
  • Flint keeps its processing fee on a refund, as on any payment. A full refund costs you your share plus Flint's fee.
  • A split that hasn't transferred yet gives its share back by lowering the amount Flint will transfer. The seller's ledger shows nothing. A transferred split gives it back with a payment_split_reversal on the seller's ledger.
  • A failed or canceled refund reinstates what it took.

In the dashboard, open the payment, review the Seller splits panel, and choose Refund. For a payment with splits, the dialog offers "Take each seller's share back in proportion" or "Choose how much each seller gives back". Choosing amounts and entering none makes you fund the whole refund. Each refund shows how much sellers returned.

Disputes#

When Stripe withdraws a dispute's funds, each split gives back its share of the disputed amount by the same proportional rule, and you fund the rest. Dispute.split_reversals lists each seller allocation, as PaymentRefund.split_reversals does for refunds.

  • While a dispute or inquiry is open, splits that haven't transferred stay pending with dispute_open, even after the funds are available. A withdrawal lowers them, and Flint transfers what remains after every dispute closes.
  • Dispute fees are yours, as on any merchant's payment. Flint collects each fee from you when it posts.
  • If you win, every reversed amount goes back to whoever funded it, once the reinstated funds are available. If you lose, nothing more changes.
  • You answer the dispute as usual with response sessions. For a split payment, stripe_payment_id is the destination payment ID beginning py_.
  • A bank return that arrives after a payment succeeded, such as a late ACH return, follows the dispute rules. A payment that fails before it succeeds cancels its splits, and nothing was sent to sellers.

Negative seller balances#

A reversal takes only what the seller's balance covers. If a seller has already paid out the money, the rest is a shortfall, and you cover it at once. You don't wait for the seller to repay.

  • PaymentSplitReversal.shortfall_money is the part you covered. PaymentSplit.shortfall_money totals it, less reinstatements.
  • Your ledger shows a seller_shortfall_coverage entry. The seller's ledger shows the same entry as a credit that clears the negative balance a reversal left.
  • A seller's net from a split is amount_money - reversed_money + shortfall_money.
  • If a refund fails or you win a dispute, coverage comes back to you as seller_shortfall_coverage_reversal.

What a seller owes you after a shortfall is part of your own seller terms. Flint isn't a party to them.

Seller payouts#

A split credits the seller's Flint balance, and the seller's normal payouts send it to the seller's own verified bank account. A marketplace can't pay a seller's bank account directly, and Flint can't send a seller money outside a payment.

A seller reads every split it received with its own credentials: GET /v1/payment-splits?seller_merchant_id=MERCHANT_ID, with money_movement.payment_splits.read. The seller sees your description and external_reference_id, never the buyer or the payment. In the dashboard, a merchant that is a party to any split gets a Splits tab on Balances. It lists splits received and splits created, each with its status and next step, and opens a detail page with every reversal and the ledger entries behind it.

Reconcile#

Read splits through GET /v1/payment-splits, filtered by payment_intent_id, seller_merchant_id, partner_app_install_id, external_reference_id, status, or a time window. Both parties see the same resource. Collecting merchants also get payment_split.* webhook events. Sellers don't; a seller learns of money reaching or leaving its balance from balance_transaction.created.

Six balance transaction types record the movements. Each names the split in related_resource.

typeLedgerSignMovement
payment_splitSeller+A split reached the seller's balance.
payment_split_reversalSeller-A refund or dispute took back part of a split.
payment_split_reinstatementSeller+Taken-back funds returned, such as after a won dispute.
payment_split_failureYou+A split that couldn't reach its seller came back to you.
seller_shortfall_coverageYou (-), seller (+)-/+You covered what a seller's balance couldn't.
seller_shortfall_coverage_reversalYou+Coverage came back.

Your other entries keep their usual types but carry only your part. On Craftly's payment, the payment entry has amount_money $15.00 (the $100.00 captured minus both splits), fee_money $4.14, and net_money $10.86. The captured amount always equals Flint's fees plus every split plus your share.

See Balance transaction types for every type, and Payment splits for the resource.

What splits don't cover#

  • Checkout sessions, payment links, invoices, and subscriptions with splits.
  • Saved payment methods, off-session charges, overcapture, and Affirm on a split payment, and a payment that gift cards fund entirely.
  • Paying a seller's bank account directly, or sending a seller money outside a payment.
  • Holding a split until delivery, or releasing it before the payment's funds are available.
  • Splits created with a partner app token, and a platform fee on the same payment.
  • Choosing which seller funds a dispute.
  • Currencies other than USD.

Test it#

Test mode needs no review. Declare payment_splits, install your app on a test merchant, approve receiving splits, and create a test payment with splits. A test split transfers when Stripe's test funds become available. The test card 4000 0000 0000 0077 makes them available at once; see test cards.

Next steps#

Partner app installsDeclare payment_splits, send sellers to the consent screen, and track installs.Payment splitsRead splits, their statuses, pending reasons, and reversals.RefundsChoose each seller's amount with split_reversals.ReconciliationBalance transaction types for splits, reversals, and shortfall coverage.Platform feesTake a fee on payments your app creates for installed merchants.

Was this helpful?