The invariant that governs everything: the sum of all shares always equals the payment amount, exactly. No money is created or lost — rounding always lands on merchant-main.

Units are not uniform across this API, and it's the single most common source of wrong splits. Check this table before writing any integration code.

Every response follows the same envelope, and every list endpoint wraps its results in a page object.

{ "status": "Success", "data": { }, "message": "..." }

{ "status": "Failed", "errors": [ { "message": "...", "error_code": "INVALID_INPUT", "code": 100000 } ] }

{
  "status": "Success",
  "data": {
    "results": [ /* the actual items */ ],
    "current_page": 1,
    "total_page": 1,
    "total_docs": 4,
    "has_next": false,
    "has_previous": false,
    "next_page": null,
    "previous_page": null
  },
  "message": "..."
}

Registers a verified bank account as a payout beneficiary under your merchant account.

Retrieves your subaccounts.

Retrieves a single subaccount.

Every create field is accepted, all optional, plus schedule.

A soft close: the subaccount stops appearing in every read, can no longer receive a split, and its history is preserved.

A reusable, named split. Create it once, then reference it at checkout by splitId.

Percentages must total under 100%, never exactly 100%. VAT is always taken from merchant-main, regardless of your split. A config whose percentages sum to 10000 bps leaves main with ₦0, and every charge against it then fails at checkout.

Split is not feasible for amount 1000: Fee borne by main (324) exceeds its gross (0)

Returns config headers without entries — see Fetch a Split Configuration to read a config's entries.

The only endpoint that returns a config's entries.

Every field is optional.

Soft and terminal.

Dry-runs the allocation engine. No payment is created, nothing is charged. Use it to render a breakdown before the customer confirms, and to catch an infeasible config before checkout fails.

Choose exactly one of three methods when calling POST /v1/checkouts/inline_initiation (public key) or POST /v1/transactions/initialize (secret key) — see the Transactions API for the rest of that endpoint's fields.

{ "amount": 1000, "subaccountId": "sub_a1b2c3d", "customer": { "email": "buyer@example.com" } }

"split": {
  "bearerType": "main",
  "remainderPolicy": "main",
  "entries": [
    { "subaccount": "sub_a1b2c3d", "shareType": "percentage", "shareValue": 3000 },
    { "subaccount": "sub_e4f5g6h", "shareType": "flat",       "shareValue": 2000 }
  ]
}

Two independent settings decide the money out. They compose; neither overrides the other.

Everything here is available with your secret key on GET /v1/transactions/{transactionRef}. Four fields carry the split — all are null on a payment that carried no split.

The transaction only records the instruction, not the resulting Naira. To render a per-party breakdown, call POST /v1/splits/preview with the same amount and fee — it runs the same allocation engine as capture, so identical inputs give identical numbers. The response carries two objects: the snapshot that would be frozen, and the result of allocating it.

Both filters match the value stored on the transaction — the form you sent at checkout.

Every figure below is the actual output of the allocation engine for a ₦1,000 payment with a ValuePay fee of ₦3.01 and VAT of ₦0.23, merchant paying the fee, unless noted otherwise. A party's feeAmount of ₦3.24 is the fee plus VAT.

Everything that returns 400. The last two rows are checked at payment time, not at config creation — a structurally valid config can still be infeasible for a given amount. Use /v1/splits/preview to catch it early, remembering that preview omits VAT.

A refund is borne by the merchant: on refund you are debited the full refunded amount including the processing fee. ValuePay does not return its fee — standard across the industry.

Before you ship a split-payments integration, confirm each of these.