Payment splits
A payment split divides one payment's funds between the collecting merchant, who is the merchant of record, and a seller who installed its partner app. The collecting merchant's payment intent names each split. Sellers can read their splits without access to that payment or its buyer.
Splits divide a payment's funds between merchants. Split tender means a buyer pays one order with several payment methods. Inventory transfers move stock between locations.
Read your splits#
GET /v1/payment-splits lists splits where you are the collecting merchant or the seller, newest first, then by payment_split_id descending. GET /v1/payment-splits/{payment_split_id} returns one. Use your own merchant credentials and money_movement.payment_splits.read; partner app tokens can't read splits.
Filter the list by payment_intent_id, collecting_merchant_id, seller_merchant_id, partner_app_id, partner_app_install_id, external_reference_id, status, created_after, or created_before. IDs and external references match exactly and are case-sensitive. status accepts several values. Use page_size and the returned next_page_token for pagination; keep the filters unchanged between pages.
Test splits belong to the collecting merchant's sandbox and are readable by the seller in its test grant's sandbox. Resetting that seller sandbox removes access from the new generation.
Transfer state#
status | Meaning |
|---|---|
pending | The split is waiting. pending_reason says why. |
processing | Flint released the split and is transferring it, including retries while the seller can't receive. |
succeeded | The split reached the seller's Flint balance. |
failed | The seller couldn't receive the split within seven days, so the remaining amount goes to the collecting merchant. failure_reason is seller_cannot_receive, or split_failed for a reason this API version doesn't name. |
canceled | The split will never transfer. canceled_reason is payment_not_completed, install_revoked, or fully_reversed. A later reinstatement is recorded on its reversal. |
succeeded, failed, and canceled are final statuses. Reversals change amounts, not a succeeded split's status. Reasons can gain values.
For a pending split, the first applicable pending_reason is:
awaiting_payment: the payment hasn't succeeded.dispute_open: a dispute or inquiry remains open on the payment.reversals_pending: refunds or disputes took back the whole split, and their outcomes are still pending.awaiting_funds: the payment's funds aren't available on Flint's balance yet.
funds_available_at is null until Stripe reports when the funds become available, and when the payment never succeeded. After a won dispute, it can move later to the availability of the reinstated funds. It is fixed when Flint releases the split. A split reaches the seller's balance only after its funds are available and all disputes on the payment are closed. The seller's normal payouts carry it to its own bank account.
Reversals#
reversals embeds every reversal, or [] when there are none. A reversal is a read-only child of its split, created by Flint for a refund or dispute. source names that refund or dispute. There is at most one reversal per refund and one per dispute for each split.
amount_moneyis the split's share taken back.shortfall_moneyis the part the collecting merchant covered because the seller couldn't fund it.reinstated_moneyis what came back to whoever funded the reversal, such as after a won dispute or failed refund.
A reversal is pending, succeeded, or canceled. canceled is final and means the refund failed before any money moved. reason is refund, dispute (including a late bank return), or other for a reason this API version doesn't name.
On the split, reversed_money totals reversals minus reinstatements. shortfall_money totals the part the collecting merchant covered, less reinstatements. The seller's net from the split is amount_money - reversed_money + shortfall_money. A refund before transfer reduces what the seller will receive without posting a movement to the seller's balance.
The Payment split object#
A top-level child of a payment intent dividing the collecting merchant's payment funds with one seller. Both parties read this same resource with their own credentials.
Returned by GET /v1/payment-splits/{payment_split_id} and carried by the endpoints below.
Attributes
amount_moneyobjectRequiredThe admitted amount, or its final amount set at capture.
amountintegerRequiredAmount in the currency's minor unit, such as cents for USD.
currencystringRequiredISO 4217 currency code for this amount.
canceled_reasonenumPresent when status is canceled. Can gain values.
payment_not_completedinstall_revokedfully_reversed
collecting_merchant_idstringRequiredThe merchant of record that collected the payment.
created_atstringRequiredWhen the payment's create recorded the split.
descriptionstringThe collecting merchant's description, shown to the seller.
external_reference_idstringCaller-owned identifier for this resource in an external system. Shown to the seller. Exact, case-sensitive matching.
failure_reasonenumPresent when status is failed. Can gain values; unknown reasons use split_failed.
seller_cannot_receivesplit_failed
funds_available_atstring or nullRequiredWhen the funds become available on Flint's balance. Null when Stripe has not reported it or the payment never succeeded. Can move later after a won dispute; frozen at release.
partner_app_idstringRequiredThe collecting merchant's partner app.
partner_app_install_idstringRequiredThe seller's install of the app.
payment_intent_idstringRequiredThe collecting merchant's payment. Sellers can read the split, but not the payment.
payment_split_idstringRequiredUnique identifier for the split.
pending_reasonenumPresent when status is pending. Can gain values.
awaiting_paymentdispute_openreversals_pendingawaiting_funds
reversalsarray of objectRequiredRead-only nested children created by Flint, embedded whole. Empty when none. At most one per refund and one per dispute.
amount_moneyobjectRequiredThe split's share taken back.
created_atstringRequiredWhen the reversal was recorded.
payment_split_reversal_idstringRequiredUnique identifier for the reversal.
reasonenumRequiredWhy Flint created the reversal.
refunddisputeother
reinstated_moneyobjectRequiredFunds returned to whoever funded the reversal, such as after a won dispute or failed refund.
shortfall_moneyobjectRequiredThe part the collecting merchant covered.
sourceobjectRequiredThe refund or dispute behind the reversal.
statusenumRequiredThe reversal lifecycle status.
pendingsucceededcanceled
succeeded_atstringWhen the split's share was recovered. Present when succeeded.
reversed_moneyobjectRequiredReversals' total amount minus their reinstated amounts.
amountintegerRequiredAmount in the currency's minor unit, such as cents for USD.
currencystringRequiredISO 4217 currency code for this amount.
seller_merchant_idstringRequiredThe merchant receiving the split.
shortfall_moneyobjectRequiredReversed funds the collecting merchant covered for the seller, less reinstatements. The seller's net is amount_money minus reversed_money plus shortfall_money.
amountintegerRequiredAmount in the currency's minor unit, such as cents for USD.
currencystringRequiredISO 4217 currency code for this amount.
statusenumRequiredThe split lifecycle status.
pendingprocessingsucceededfailedcanceled
succeeded_atstringWhen the split reached the seller's balance. Present when succeeded.
updated_atstringRequiredWhen the split last changed.
versionintegerRequiredPersisted version of this resource's owned state. Expanded resources and external observations can change independently.
{
"amount_money": {
"amount": 6000,
"currency": "USD"
},
"collecting_merchant_id": "mer_01KEZF7C00MPP0T9S0KH5BB4CC",
"created_at": "2026-11-12T16:40:21Z",
"funds_available_at": "2026-11-14T00:00:00Z",
"partner_app_id": "papp_01KEZF7C00D8DXK5AXR7NPRJ0J",
"partner_app_install_id": "pinst_01KF3A8C2D4E6F8G0H2J4K6M8N",
"payment_intent_id": "pi_01KF4B1Z3X5C7V9B1N3M5Q7W9E",
"payment_split_id": "psplit_01KF4B2C4D6E8F0G2H4J6K8M0N",
"pending_reason": "awaiting_funds",
"reversals": [],
"reversed_money": {
"amount": 0,
"currency": "USD"
},
"seller_merchant_id": "mer_01KF3A7B1C3D5E7F9G1H3J5K7M",
"shortfall_money": {
"amount": 0,
"currency": "USD"
},
"status": "pending",
"updated_at": "2026-11-12T16:40:21Z",
"version": 1
}List payment splits#
/v1/payment-splitsRequires scope money_movement.payment_splits.read
Rate limit: read
Lists splits where you are either party, newest first, then by payment_split_id descending. Read splits you collected or received, with your own credentials and money_movement.payment_splits.read. Install tokens can't read splits. Test splits are in the collecting merchant's sandbox and the seller's test grant's sandbox. Consumers include marketplace payment pages and seller reconciliation. Default order: created_at descending, then payment_split_id descending.
Query parameters
page_sizeintegerMaximum number of results to return, from 1 to 100. Defaults to 20.
page_tokenstringOpaque, signed next_page_token from the previous response, bound to the list and caller. Omit on the first request. You may change `page_size` between pages. Reuse it with the same endpoint, filters, sort, and request context. Do not parse or construct tokens. An altered, invalid, expired, or mismatched token returns a validation error.
payment_intent_idstringExact match on the payment intent.
collecting_merchant_idstringExact match on the collecting merchant.
seller_merchant_idstringExact match on the seller.
partner_app_idstringExact match on the partner app.
partner_app_install_idstringExact match on the install.
external_reference_idstringExact, case-sensitive match on the collecting merchant's external identifier.
statusarray of enumStatuses to include. Omit to include all statuses. Values are trimmed and deduplicated in first-seen order; empty or unknown entries are rejected. Values within this filter are ORed; separate filters are ANDed.
pendingprocessingsucceededfailedcanceled
created_afterstringInclusive lower bound on created_at.
created_beforestringExclusive upper bound on created_at.
Response · 200
A page of payment splits.
dataarray of objectRequiredResource, collection, or operation result returned by this request.
amount_moneyobjectRequiredThe admitted amount, or its final amount set at capture.
canceled_reasonenumPresent when status is canceled. Can gain values.
payment_not_completedinstall_revokedfully_reversed
collecting_merchant_idstringRequiredThe merchant of record that collected the payment.
created_atstringRequiredWhen the payment's create recorded the split.
descriptionstringThe collecting merchant's description, shown to the seller.
external_reference_idstringCaller-owned identifier for this resource in an external system. Shown to the seller. Exact, case-sensitive matching.
failure_reasonenumPresent when status is failed. Can gain values; unknown reasons use split_failed.
seller_cannot_receivesplit_failed
funds_available_atstring or nullRequiredWhen the funds become available on Flint's balance. Null when Stripe has not reported it or the payment never succeeded. Can move later after a won dispute; frozen at release.
partner_app_idstringRequiredThe collecting merchant's partner app.
partner_app_install_idstringRequiredThe seller's install of the app.
payment_intent_idstringRequiredThe collecting merchant's payment. Sellers can read the split, but not the payment.
payment_split_idstringRequiredUnique identifier for the split.
pending_reasonenumPresent when status is pending. Can gain values.
awaiting_paymentdispute_openreversals_pendingawaiting_funds
reversalsarray of objectRequiredRead-only nested children created by Flint, embedded whole. Empty when none. At most one per refund and one per dispute.
reversed_moneyobjectRequiredReversals' total amount minus their reinstated amounts.
seller_merchant_idstringRequiredThe merchant receiving the split.
shortfall_moneyobjectRequiredReversed funds the collecting merchant covered for the seller, less reinstatements. The seller's net is amount_money minus reversed_money plus shortfall_money.
statusenumRequiredThe split lifecycle status.
pendingprocessingsucceededfailedcanceled
succeeded_atstringWhen the split reached the seller's balance. Present when succeeded.
updated_atstringRequiredWhen the split last changed.
versionintegerRequiredPersisted version of this resource's owned state. Expanded resources and external observations can change independently.
metaobjectAdditional information about this response.
api_versionstringAPI version used to produce this response.
idempotency_replayedbooleanWhether this response replays a stored result for the supplied Idempotency-Key.
trace_idstringTrace identifier to include when contacting Flint about this request.
warningsarray of objectConditions that need attention even though the request succeeded.
next_page_tokenstringOpaque token to send as `page_token` to retrieve the next page. Omitted when there is no next page.
request_idstringRequiredIdentifier of this API request, used to correlate logs and support requests.
curl https://api.withflintpay.com/v1/payment-splits \
-H "Flint-Version: 2026-09-07" \
-H "Authorization: Bearer YOUR_API_KEY"A page of payment splits.
{
"data": [
{
"amount_money": {
"amount": 6000,
"currency": "USD"
},
"collecting_merchant_id": "mer_01KEZF7C00MPP0T9S0KH5BB4CC",
"created_at": "2026-11-12T16:40:21Z",
"funds_available_at": "2026-11-14T00:00:00Z",
"partner_app_id": "papp_01KEZF7C00D8DXK5AXR7NPRJ0J",
"partner_app_install_id": "pinst_01KF3A8C2D4E6F8G0H2J4K6M8N",
"payment_intent_id": "pi_01KF4B1Z3X5C7V9B1N3M5Q7W9E",
"payment_split_id": "psplit_01KF4B2C4D6E8F0G2H4J6K8M0N",
"pending_reason": "awaiting_funds",
"reversals": [],
"reversed_money": {
"amount": 0,
"currency": "USD"
},
"seller_merchant_id": "mer_01KF3A7B1C3D5E7F9G1H3J5K7M",
"shortfall_money": {
"amount": 0,
"currency": "USD"
},
"status": "pending",
"updated_at": "2026-11-12T16:40:21Z",
"version": 1
}
],
"meta": {
"api_version": "2026-09-07"
},
"next_page_token": "opaque-next-page-token",
"request_id": "req_01KWM6WAHG3N9Q8T2V5XRZ7C4D"
}Get a payment split#
/v1/payment-splits/{payment_split_id}Requires scope money_movement.payment_splits.read
Rate limit: read
Read splits you collected or received, with your own credentials and money_movement.payment_splits.read. Install tokens can't read splits. Test splits are in the collecting merchant's sandbox and the seller's test grant's sandbox. Consumers include marketplace payment pages and seller reconciliation.
Path parameters
payment_split_idstringRequiredFlint payment split ID. Must be a valid ID with prefix psplit_. Malformed IDs return 400 INVALID_REQUEST with detail INVALID_VALUE; well-formed IDs that do not exist return 404 RESOURCE_NOT_FOUND.
Response · 200
The payment split.
dataobjectRequiredResource, collection, or operation result returned by this request.
amount_moneyobjectRequiredThe admitted amount, or its final amount set at capture.
canceled_reasonenumPresent when status is canceled. Can gain values.
payment_not_completedinstall_revokedfully_reversed
collecting_merchant_idstringRequiredThe merchant of record that collected the payment.
created_atstringRequiredWhen the payment's create recorded the split.
descriptionstringThe collecting merchant's description, shown to the seller.
external_reference_idstringCaller-owned identifier for this resource in an external system. Shown to the seller. Exact, case-sensitive matching.
failure_reasonenumPresent when status is failed. Can gain values; unknown reasons use split_failed.
seller_cannot_receivesplit_failed
funds_available_atstring or nullRequiredWhen the funds become available on Flint's balance. Null when Stripe has not reported it or the payment never succeeded. Can move later after a won dispute; frozen at release.
partner_app_idstringRequiredThe collecting merchant's partner app.
partner_app_install_idstringRequiredThe seller's install of the app.
payment_intent_idstringRequiredThe collecting merchant's payment. Sellers can read the split, but not the payment.
payment_split_idstringRequiredUnique identifier for the split.
pending_reasonenumPresent when status is pending. Can gain values.
awaiting_paymentdispute_openreversals_pendingawaiting_funds
reversalsarray of objectRequiredRead-only nested children created by Flint, embedded whole. Empty when none. At most one per refund and one per dispute.
reversed_moneyobjectRequiredReversals' total amount minus their reinstated amounts.
seller_merchant_idstringRequiredThe merchant receiving the split.
shortfall_moneyobjectRequiredReversed funds the collecting merchant covered for the seller, less reinstatements. The seller's net is amount_money minus reversed_money plus shortfall_money.
statusenumRequiredThe split lifecycle status.
pendingprocessingsucceededfailedcanceled
succeeded_atstringWhen the split reached the seller's balance. Present when succeeded.
updated_atstringRequiredWhen the split last changed.
versionintegerRequiredPersisted version of this resource's owned state. Expanded resources and external observations can change independently.
metaobjectAdditional information about this response.
api_versionstringAPI version used to produce this response.
idempotency_replayedbooleanWhether this response replays a stored result for the supplied Idempotency-Key.
trace_idstringTrace identifier to include when contacting Flint about this request.
warningsarray of objectConditions that need attention even though the request succeeded.
request_idstringRequiredIdentifier of this API request, used to correlate logs and support requests.
curl https://api.withflintpay.com/v1/payment-splits/psplit_01KEZF7C00Y5HA4Z8D4KRA07K8 \
-H "Flint-Version: 2026-09-07" \
-H "Authorization: Bearer YOUR_API_KEY"The payment split.
{
"data": {
"amount_money": {
"amount": 6000,
"currency": "USD"
},
"collecting_merchant_id": "mer_01KEZF7C00MPP0T9S0KH5BB4CC",
"created_at": "2026-11-12T16:40:21Z",
"funds_available_at": "2026-11-14T00:00:00Z",
"partner_app_id": "papp_01KEZF7C00D8DXK5AXR7NPRJ0J",
"partner_app_install_id": "pinst_01KF3A8C2D4E6F8G0H2J4K6M8N",
"payment_intent_id": "pi_01KF4B1Z3X5C7V9B1N3M5Q7W9E",
"payment_split_id": "psplit_01KF4B2C4D6E8F0G2H4J6K8M0N",
"pending_reason": "awaiting_funds",
"reversals": [],
"reversed_money": {
"amount": 0,
"currency": "USD"
},
"seller_merchant_id": "mer_01KF3A7B1C3D5E7F9G1H3J5K7M",
"shortfall_money": {
"amount": 0,
"currency": "USD"
},
"status": "pending",
"updated_at": "2026-11-12T16:40:21Z",
"version": 1
},
"meta": {
"api_version": "2026-09-07"
},
"request_id": "req_01KWM6WAHG3N9Q8T2V5XRZ7C4D"
}Was this helpful?