Split payments

Two unrelated features share the word split, and people arriving from another payment platform usually want a third thing that does not exist here. This page sets the boundary once.

Installment splitting

This has nothing to do with marketplaces. The same payer settles a single payment in two, three or four tranches, charged in sequence.

The call charges the payment like POST /payments/{id}, so it takes the same channel and data. Pass split_count for equal tranches, or split_amounts for unequal ones. The two are alternatives, and split_amounts must sum to what the payer pays: the payment's amount, or its amount_total when the payer bears the fee.

curl https://api.wajub.com/payments/trx_CSUGajfv9xh0XQ5wu2lx/splits \
  -H "Authorization: sk_test.xxxxxxxxxxxxxxxx…" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "cm.mtn",
    "data": { "phone": "+237670000000" },
    "split_count": 3
  }'

split_count accepts 2, 3 or 4 and nothing else. For uneven tranches, send the amounts yourself.

curl https://api.wajub.com/payments/trx_CSUGajfv9xh0XQ5wu2lx/splits \
  -H "Authorization: sk_test.xxxxxxxxxxxxxxxx…" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "cm.mtn",
    "data": { "phone": "+237670000000" },
    "split_amounts": [4000, 3000, 3000],
    "split_currency": "XAF"
  }'

Between two and four values, each at least 0.01 and in the currency's own precision: whole francs in XAF and XOF. One payer, one payment, several charges.

What each call does

The first call sets the plan and charges the first tranche. Each later call charges the next one: send it with the same channel and data, and without split_count or split_amounts, or with the same plan. A different plan is refused with a 422. Once a payment has a plan, any charge of it, POST /payments/{id} or the payment page, takes the next tranche, never the whole amount.

Every answer carries the tranche in transaction.split: its id, split_number, total_splits, amount and status. Equal tranches are whole units, and the last one takes what is left: 10 000 XAF in three is 3 333, 3 333 and 3 334.

A declined tranche is charged again by the next call. The tranches already paid stay paid: amount_collected is what they add up to, and the payment never goes back to pending once something was collected.

When the money is yours

Each tranche is yours as it clears: it is credited to your balance at once, under the usual hold, and pays its share of the Wajub fee then, in live as in sandbox. When the payer bears the fee, you are credited your part of each tranche and the tranches add up to amount. The payment reaches succeeded with its last tranche, and does not expire while it is partial. Each tranche sends payment.split.processing, then payment.split.succeeded or payment.split.failed; payment.succeeded comes once, with the last. The split events describe the payload.

When the payer stops paying

Nothing closes a partial payment on its own. You decide, with POST /payments/{id}/close and an outcome:

payment.succeeded is sent once, as for a payment paid in full; refunds and the refunded status then count against what was collected. A close while a tranche is with the payer answers 409 payment_in_progress, and DELETE /payments/{id} refuses a payment with tranches already paid (409 payment_partly_paid): close it instead.

Each tranche has to fit under the per-transaction ceiling of Mobile Money. A single charge above it is refused with a 422, in live and in sandbox: nothing splits a payment on its own, tranches are your choice. A payment paid in tranches is refunded by Wajub's team rather than automatically, because each tranche may have come from another number.

Per-connection pricing

This is the marketplace one. A payment attributed to a connection belongs to that merchant, and your platform is credited the commission configured on the connection.

curl https://api.wajub.com/payments \
  -H "Authorization: sk.xxxxxxxxxxxxxxxx…" \
  -H "X-Sync: acc_7Yh2MpL4tRb3nP8sZcXv" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 50000,
    "currency": "XAF",
    "customer": { "email": "[email protected]" }
  }'

There is no per-request override. The commission comes from the rules attached to the connection, which the merchant accepted and which only change with their agreement, and the payload carries no fee field at all. Account capabilities covers how the rule is chosen and clamped.

The one that does not exist

A multi-seller basket is therefore several payments, one per seller, each with its own header.

The last row is the one that saves you later. Reconciling a basket after the fact is only possible if every payment in it carries the same identifier of yours.

Paying a merchant out is a third thing again

Neither feature moves money to a merchant's bank or wallet. Funds from a connected payment settle into that merchant's own Wajub balance, and how they get out depends on the mode: a direct merchant withdraws for themselves, a lite merchant is paid automatically by Wajub, and a relay marketplace pays its sellers in bulk. All three are on Paying sellers. Your commission, meanwhile, has already moved to your own balance without any call on your part, and can be withdrawn once the sale it came from clears retention.