Skip to content

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#

statusMeaning
pendingThe split is waiting. pending_reason says why.
processingFlint released the split and is transferring it, including retries while the seller can't receive.
succeededThe split reached the seller's Flint balance.
failedThe 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.
canceledThe 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:

  1. awaiting_payment: the payment hasn't succeeded.
  2. dispute_open: a dispute or inquiry remains open on the payment.
  3. reversals_pending: refunds or disputes took back the whole split, and their outcomes are still pending.
  4. 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_money is the split's share taken back.
  • shortfall_money is the part the collecting merchant covered because the seller couldn't fund it.
  • reinstated_money is 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_moneyobjectRequired

The admitted amount, or its final amount set at capture.

canceled_reasonenum

Present when status is canceled. Can gain values.

  • payment_not_completed
  • install_revoked
  • fully_reversed
collecting_merchant_idstringRequired

The merchant of record that collected the payment.

created_atstringRequired

When the payment's create recorded the split.

descriptionstring

The collecting merchant's description, shown to the seller.

external_reference_idstring

Caller-owned identifier for this resource in an external system. Shown to the seller. Exact, case-sensitive matching.

failure_reasonenum

Present when status is failed. Can gain values; unknown reasons use split_failed.

  • seller_cannot_receive
  • split_failed
funds_available_atstring or nullRequired

When 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_idstringRequired

The collecting merchant's partner app.

partner_app_install_idstringRequired

The seller's install of the app.

payment_intent_idstringRequired

The collecting merchant's payment. Sellers can read the split, but not the payment.

payment_split_idstringRequired

Unique identifier for the split.

pending_reasonenum

Present when status is pending. Can gain values.

  • awaiting_payment
  • dispute_open
  • reversals_pending
  • awaiting_funds
reversalsarray of objectRequired

Read-only nested children created by Flint, embedded whole. Empty when none. At most one per refund and one per dispute.

reversed_moneyobjectRequired

Reversals' total amount minus their reinstated amounts.

seller_merchant_idstringRequired

The merchant receiving the split.

shortfall_moneyobjectRequired

Reversed funds the collecting merchant covered for the seller, less reinstatements. The seller's net is amount_money minus reversed_money plus shortfall_money.

statusenumRequired

The split lifecycle status.

  • pending
  • processing
  • succeeded
  • failed
  • canceled
succeeded_atstring

When the split reached the seller's balance. Present when succeeded.

updated_atstringRequired

When the split last changed.

versionintegerRequired

Persisted version of this resource's owned state. Expanded resources and external observations can change independently.

JSON
{
  "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#

GET/v1/payment-splits

Requires 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_sizeinteger

Maximum number of results to return, from 1 to 100. Defaults to 20.

page_tokenstring

Opaque, 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_idstring

Exact match on the payment intent.

collecting_merchant_idstring

Exact match on the collecting merchant.

seller_merchant_idstring

Exact match on the seller.

partner_app_idstring

Exact match on the partner app.

partner_app_install_idstring

Exact match on the install.

external_reference_idstring

Exact, case-sensitive match on the collecting merchant's external identifier.

statusarray of enum

Statuses 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.

  • pending
  • processing
  • succeeded
  • failed
  • canceled
created_afterstring

Inclusive lower bound on created_at.

created_beforestring

Exclusive upper bound on created_at.

Response · 200

A page of payment splits.

dataarray of objectRequired

Resource, collection, or operation result returned by this request.

metaobject

Additional information about this response.

next_page_tokenstring

Opaque token to send as `page_token` to retrieve the next page. Omitted when there is no next page.

request_idstringRequired

Identifier 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.

JSON
{
  "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#

GET/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_idstringRequired

Flint 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.

dataobjectRequired

Resource, collection, or operation result returned by this request.

metaobject

Additional information about this response.

request_idstringRequired

Identifier 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.

JSON
{
  "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?