Marketplace splits

For platforms collecting on behalf of third-party sellers (marketplaces, ride-hailing, delivery), splits divide an incoming transaction between several beneficiary merchants.

Model

• A parent transaction is collected by the platform merchant (you).
• Each payment_split line credits a beneficiary merchant with part of the amount.
• The actual distribution to the beneficiaries' balances happens in the settlement cycle (next day by default).

Create splits

POST /v1/payments/{transaction_id}/splits

{
  "splits": [
    {
      "beneficiary_merchant_id": "uuid-vendor-A",
      "amount": "60.00",
      "description": "Order #ORD-001 — Vendor A"
    },
    {
      "beneficiary_merchant_id": "uuid-vendor-B",
      "amount": "75.00"
    }
  ]
}

Here the parent transaction is Le 150.00: the platform keeps Le 15.00.

Invariants

• The sum of amount must not exceed the parent transaction amount.
• Each beneficiary_merchant_id must be an active merchant.
• Splits are immutable once created. To correct one, cancel it with an offsetting entry, then create it again.
• Refused if the transaction is in an unfavourable final state (cancelled, expired).
• Concurrency-safe: two parallel POST /v1/payments/{id}/splits calls on the same parent are serialised. A concurrent call that would exceed the total is rejected with 422 split_rejected, even if each call alone would have passed.

Response 201

{
  "data": [
    {
      "id": "...",
      "object": "payment_split",
      "transaction_id": "...",
      "beneficiary_merchant_id": "uuid-vendor-A",
      "amount": "60.00",
      "currency": "SLE",
      "is_settled": false,
      "settled_at": null,
      "created_at": "2026-10-21T09:41:00+00:00"
    },
    ...
  ]
}

List a transaction's splits

GET /v1/payments/{transaction_id}/splits

What the platform keeps

platform_keeps = transaction.amount − Σ(split.amount)

You can split up to 100 % of the amount (the platform keeps nothing) or keep a margin.

Settlement

When the transaction reaches success, unsettled splits credit the beneficiaries' balances. The actual bank transfer follows the cycle configured on their plan (daily/weekly).

Typical uses

Platform	Pattern
Product marketplace	1 customer payment → N seller splits + 1 platform commission
Ride-hailing	1 ride → 1 driver split (80 %) + 1 platform commission (20 %)
Rentals	1 rent payment → 1 landlord split (90 %) + 1 commission
Crowdfunding	1 donation → 1 beneficiary split + 1 service fee

Errors

Code	HTTP	Cause
split_rejected	422	Total above the transaction amount, inactive beneficiary, final transaction
transaction_not_found	404	Unknown id for this merchant