Split payments let a platform divide a single collection between itself and the people it pays — drivers, couriers, vendors, restaurants — at the moment of capture. You create a sub-account for each recipient, attach a split instruction to the charge, and each leg is credited to the recipient's ledger when the payment settles and clawed back automatically if it is later reversed.
iBuilt for marketplaces
You remain the merchant of record. Splits are an accounting and payout convenience inside your workspace, not a licence to hold funds belonging to third parties — see the Merchant Acceptance Policy for the conditions that apply to marketplace models.
Sub-accounts
A sub-account is a named settlement destination scoped to your business and to one mode. The same reference can exist in test and live independently.
POST
/v1/sub-accounts| Field | Type | Description |
|---|---|---|
name | string · required | Human name shown in your dashboard, e.g. "Kwame Mensah". |
reference | string | Your own stable id — letters, digits, - and _. Derived from name if omitted. |
settlement_method | enum | momo (default) or bank. |
account_number | string · required | Wallet number (0XXXXXXXXX) for momo, account number for bank. |
network | enum | Required for momo: MTN · AT · TELECEL · GMONEY. |
bank_code | string | Required for bank sub-accounts. |
account_name | string | Optional name on the destination account. |
shell
curl -X POST https://api.webrabbitmedia.com/v1/sub-accounts \
-H "Authorization: Bearer wr_test_..." \
-H "Content-Type: application/json" \
-d '{
"name": "Kwame Mensah",
"reference": "driver_8814",
"settlement_method": "momo",
"account_number": "0244000000",
"network": "MTN"
}'201 Created
{
"id": "0f2c…",
"reference": "driver_8814",
"name": "Kwame Mensah",
"status": "unverified",
"settlement_method": "momo",
"account_number": "0244000000",
"network": "MTN",
"mode": "test",
"balance": 0,
"balance_minor": 0,
"currency": "GHS"
}List, retrieve, update, ledger
| Field | Type | Description |
|---|---|---|
GET /v1/sub-accounts | list | All sub-accounts for the key's mode, newest first, with live balances. |
GET /v1/sub-accounts/{reference} | retrieve | One sub-account by reference or id. |
PATCH /v1/sub-accounts/{reference} | update | Change name, destination, or set status to disabled / unverified. |
GET /v1/sub-accounts/{reference}/ledger | ledger | Credit and reversal entries with running balance. limit 1–200. |
!Changing a destination re-opens verification
Updating
account_number or network resets the sub-account to unverified. Only Web Rabbit sets verified; you can set disabled to stop new splits landing on it.Splitting a charge
Add a split object to POST /v1/collect/momo or POST /v1/checkout/session. Each recipient is either a percentage of the collection or a fixed amount, and whatever is left over stays with you.
| Field | Type | Description |
|---|---|---|
split.fee_bearer | enum | merchant (default) — the Web Rabbit fee comes out of your share. recipients — the fee is taken off the top before percentages are applied. |
split.recipients[].sub_account | string · required | Sub-account reference or id, in the same mode as the key. |
split.recipients[].percentage | number | Share of the split base, 0–100. Use this or amount, not both. |
split.recipients[].amount / amount_minor | number / integer | Fixed leg in GHS or pesewas. |
POST /v1/collect/momo
{
"amount_minor": 5000,
"subscriber_number": "0244000000",
"network": "MTN",
"description": "Trip 88142",
"split": {
"fee_bearer": "merchant",
"recipients": [
{ "sub_account": "driver_8814", "percentage": 85 }
]
}
}Preview the arithmetic before you charge — useful in tests and for showing a driver their payout before the trip is confirmed.
POST
/v1/splits/preview200 OK
{
"currency": "GHS",
"gross_amount": 50,
"gross_amount_minor": 5000,
"fee_amount": 7.5,
"fee_amount_minor": 750,
"net_amount": 42.5,
"net_amount_minor": 4250,
"fee_bearer": "merchant",
"merchant_amount": 0,
"merchant_amount_minor": 0,
"recipients": [
{ "sub_account": "driver_8814", "type": "percentage", "value": 85, "amount": 42.5, "amount_minor": 4250 }
]
}iInteger arithmetic, always
Legs are computed in pesewas. Any rounding remainder is added to the largest leg, so the legs plus your share always equal the net amount exactly.
Settlement and reversal
| Field | Type | Description |
|---|---|---|
pending | split_status | Instruction recorded, payment not yet approved. Nothing has been credited. |
settled | split_status | Payment approved — each leg is credited to its sub-account ledger once, and split.settled fires. |
reversed | split_status | Payment was clawed back — every credited leg is debited back and split.reversed fires. |
GET /v1/transactions/{id} returns split_status and the full splits array, so reconciliation never has to be inferred.
!Size your payout hold against the reversal window
Mobile Money collections can be reversed for up to 7 days after settlement; card collections carry chargeback exposure for up to 120 days. If you pay recipients out faster than that, you are carrying the reversal risk yourself.
Webhook events
| Field | Type | Description |
|---|---|---|
split.settled | event | Fired once per transaction when all legs are credited. Includes every leg with amount_minor. |
split.reversed | event | Fired when a settled collection is reversed and the legs are debited back. |