> ## Documentation Index
> Fetch the complete documentation index at: https://docs.payaza.africa/llms.txt
> Use this file to discover all available pages before exploring further.
# Split Settlements
> Automatically distribute funds from a single payment to one or more beneficiary accounts using Payaza Split Settlement.
## Overview
Split Settlement lets you automatically route a portion of every payment directly to a beneficiary's bank account at settlement time — no manual transfers or reconciliation needed. A typical use case is a marketplace or platform that needs to pay a vendor, partner, or sub-merchant their share of every transaction.
**How the split is calculated:**
> The `split_value` defines how much of the transaction amount **you (the Payaza account owner) keep**. The **remainder** is sent to the split account beneficiary.
For example, with `split_type: "PERCENTAGE"` and `split_value: 20` on a ₦10,000 transaction — you keep ₦2,000 (20%) and the split account beneficiary receives ₦8,000 (80%).
Here is how it fits into a payment flow:
1. You create one or more **split accounts** via the API — each one defines a beneficiary bank account, a split type, and the portion you retain.
2. Each split account gets a unique **`code`** (e.g. `SSA_C0900E891783950401871`).
3. When you initiate a checkout, you pass those codes in the `split_accounts` array.
4. Payaza automatically retains your defined portion and routes the remainder to the beneficiary at settlement time.
## Key Requirements
Retrieve your API keys from your dashboard by following the steps on our
[Authentication](/guides/authentication) page. Use your **public API key** for
all split settlement requests.
Set the following headers on every request:
```json theme={null}
{
"Authorization": "Payaza ",
"X-TenantID": "test"
}
```
Set `X-TenantID` to `test` while developing and `live` when processing real
payments.
***
## Split types
When creating a split account, you choose how the retained amount is calculated. In both cases, **`split_value` defines what you (the Payaza account owner) keep** — the beneficiary receives whatever is left over.
| `split_type` | What `split_value` means | Example |
| ------------ | ------------------------------------------------------------ | -------------------------------------------------------------------- |
| `PERCENTAGE` | The percentage of the transaction amount **you retain** | `split_value: 20` → you keep 20%, beneficiary receives 80% |
| `FLAT` | The fixed naira amount **you retain** from every transaction | `split_value: 2000` → you keep ₦2,000, beneficiary receives the rest |
This is the opposite of what you might expect. The `split_value` is **your
cut**, not the beneficiary's. The beneficiary always receives the remainder
after your portion is deducted.
For `PERCENTAGE` splits, `split_value` must be between `0` and `100`. Passing
a value outside this range will return an error.
## How split settlement works end to end
1. **Create a split account** for each beneficiary using the Create Split
Account endpoint. Each account is tied to a bank account number, bank code,
split type, and the portion **you** retain.
2. **Copy the `code`** from the Create Split Account response (e.g.
`SSA_C0900E891783950401871`). This is the only value you need to reference
the split account later.
3. **Initiate a checkout** and include the `split_accounts` array with the
relevant code(s).
4. When a customer completes the payment, Payaza automatically retains your
defined portion and routes the remainder to the beneficiary. No further
action is needed from your server.
You run a marketplace. For every ₦10,000 sale, you want to keep your 20% platform fee and send the rest to the vendor.
Create one split account for the vendor with `split_type: "PERCENTAGE"` and `split_value: 20`.
* **You (Payaza account owner) keep:** ₦2,000 (20%)
* **Vendor (split account beneficiary) receives:** The remainder of the transaction
At checkout, pass that split account's code in the `split_accounts` array. Payaza handles the rest automatically.
You charge a flat ₦1,500 platform fee on every order and want the rest to go to the service provider, regardless of order size.
Create one split account for the service provider with `split_type: "FLAT"` and `split_value: 1500`.
* **You (Payaza account owner) keep:** ₦1,500
* **Service provider (split account beneficiary) receives:** the remainder of every transaction
On a ₦10,000 order, the provider receives ₦8,500. On a ₦5,000 order, the provider receives ₦3,500.
## Step 1 — Create a Split Account
This creates a new split account for a beneficiary. A unique `code` is returned on success which can be passed in the checkout SDK.
```bash cURL theme={null}
curl --request POST \
--url https://api.payaza.africa/live/settlement/settlement/merchant/split-account \
--header 'Authorization: Payaza ' \
--header 'Content-Type: application/json' \
--header 'X-TenantID: test' \
--data '{
"account_no": "0123456789",
"account_name": "John Doe",
"bank_code": "000001",
"name": "John Doe Vendor Account",
"email": "johndoe@gmail.com",
"currency": "NGN",
"country": "NGA",
"split_type": "PERCENTAGE",
"split_value": 80
}'
```
**Request body parameters**
| Parameter | Type | Required | Description |
| -------------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `account_no` | String | ✓ | The beneficiary bank account number. |
| `account_name` | String | ✓ | The name of the beneficiary bank account. |
| `bank_code` | String | ✓ | The bank code of the beneficiary bank. |
| `name` | String | ✓ | The name assigned to the Split Account. |
| `email` | String | ✓ | The beneficiary's email address |
| `currency` | String | ✓ | The settlement currency — ISO 4217 (e.g. `NGN`) |
| `country` | String | ✓ | The country code — ISO 3166-1 Alpha-3 (e.g. `NGA`) |
| `split_type` | String | ✓ | The calculation mechanism applied to process transaction splits. `PERCENTAGE` retains a percentage of the transaction amount for you; `FLAT` retains a fixed naira amount for you. In both cases, the remainder is sent to the beneficiary. |
| `split_value` | Number | ✓ | The amount **you (the Payaza account owner) retain** — either a percentage (0–100) or a flat naira amount depending on `split_type`. The beneficiary receives the rest. |
**Sample response — success**
```json theme={null}
{
"code": "00",
"success": true,
"error": null,
"data": {
"code": "SSA_C0900E891783950401871",
"id": 114
},
"message": "split account created successfully"
}
```
Save `data.code` immediately after creating a split account. This is the value
you will pass to the Checkout SDK — without it you cannot use this split
account in a transaction. It can be retrieved by using the Fetch Split
Accounts API.
**Sample response — failed (invalid percentage)**
```json theme={null}
{
"code": "96",
"success": null,
"error": "Amount must be between 0 and 100 for percentage split type",
"data": null,
"message": null
}
```
**Sample response — failed (duplicate)**
```json theme={null}
{
"code": "96",
"success": null,
"error": "split account already exists",
"data": null,
"message": null
}
```
**API reference:** [Create Split Account](/api-reference/split-settlements/create-split-account)
## Step 2 — Use the split account code in Checkout
Once you have a split account `code`, pass it in the `split_accounts` array when initiating a Checkout transaction. Payaza will automatically route settlement to the beneficiary accounts you specify.
You can include multiple split accounts in a single checkout to distribute funds across several beneficiaries at once.
```json Single split account theme={null}
"split_accounts": [
{
"code": "SSA_C0900E891783950401871"
}
]
```
```json Multiple split accounts theme={null}
"split_accounts": [
{
"code": "SSA_C0900E891783950401871"
},
{
"code": "SSA_39B5E6E91783951863120"
}
]
```
Every `code` in the `split_accounts` array must reference an **existing,
active** split account.
**`split_accounts` parameters**
| Parameter | Type | Description |
| ---------------- | ------ | ------------------------------------------------------------------------- |
| `split_accounts` | Array | List of split account objects to apply to the transaction |
| `code` | String | The unique split account code returned when the split account was created |
***
## Step 3 — Fetch all Split Accounts
Retrieve a paginated list of all split accounts belonging to your merchant account. Useful for displaying a list of configured beneficiaries in your dashboard or verifying that a split account exists before including it in a checkout.
```bash cURL theme={null}
curl --request GET \
--url 'https://api.payaza.africa/live/settlement/settlement/merchant/split-account?page=1&size=10' \
--header 'Authorization: Payaza ' \
--header 'X-TenantID: test'
```
**Query parameters**
| Parameter | Required | Description |
| --------- | -------- | --------------------------- |
| `page` | ✓ | Page number — starts at `1` |
| `size` | ✓ | Number of records per page |
**Sample response**
```json theme={null}
{
"code": "00",
"success": true,
"error": null,
"data": {
"items": [
{
"id": 116,
"account_no": "0223456789",
"code": "SSA_C70E2C391783952664709",
"account_name": "Jane Doe",
"name": "Jane doe",
"email": "janedoe@gmail.com",
"bank_code": "123456",
"bank_name": "YOUR BANK",
"currency": "NGN",
"country": "NGA",
"split_type": "FLAT",
"split_value": 3000,
"active": true,
"created_at": "2026-07-13T14:24:24.709239",
"last_modified": "2026-07-13T14:24:24.713178"
},
{
"id": 115,
"account_no": "0123456789",
"code": "SSA_39B5E6E91783951863120",
"account_name": "John Doe",
"name": "John doe",
"email": "johndoe@gmail.com",
"bank_code": "654321",
"bank_name": "MY BANK",
"currency": "NGN",
"country": "NGA",
"split_type": "PERCENTAGE",
"split_value": 2,
"active": true,
"created_at": "2026-07-13T14:11:03.120587",
"last_modified": "2026-07-13T14:11:03.123849"
}
],
"page": 1,
"size": 2,
"total_elements": 8,
"total_pages": 4,
"has_next": true
},
"message": "split accounts fetched successfully"
}
```
**API reference:** [Fetch Split Accounts](/api-reference/split-settlements/fetch-split-accounts)
## Step 4 — Update a Split Account
Update the details of an existing split account using its `id`. All body parameters are optional — include only the fields you want to change. Fields not included in the request retain their existing values.
```bash cURL theme={null}
curl --request PUT \
--url https://api.payaza.africa/live/settlement/merchant/split-account/114 \
--header 'Authorization: Payaza ' \
--header 'Content-Type: application/json' \
--header 'X-TenantID: test' \
--data '{
"account_name": "Jane Doe",
"split_type": "FLAT",
"split_value": 5000,
"active": true
}'
```
**Path parameter**
| Parameter | Type | Description |
| --------- | ------- | --------------------------------------------------------------------------- |
| `id` | Integer | The `id` of the split account to update — from the Create or Fetch response |
**BODY Parameters** *(all optional)*
| Parameter | Type | Description |
| -------------- | ------- | ------------------------------------------------------------------ |
| `account_no` | String | Updated beneficiary bank account number |
| `account_name` | String | Updated name on the beneficiary bank account |
| `bank_code` | String | Updated bank code |
| `name` | String | Updated internal display name |
| `email` | String | Updated beneficiary email address |
| `currency` | String | Updated settlement currency |
| `country` | String | Updated country code |
| `split_type` | String | Updated split type: `PERCENTAGE` or `FLAT` |
| `split_value` | Number | Updated percentage or flat amount |
| `active` | Boolean | Set to `false` to deactivate the split account without deleting it |
**Sample response — success**
```json theme={null}
{
"code": "00",
"success": true,
"error": null,
"data": {
"id": 118,
"account_no": "1212121212",
"code": "SSA_E55380AD1783952772114",
"account_name": "Jane Doe",
"name": "Janet Doe",
"email": "janetdoe@gmail.com",
"bank_code": "100004",
"bank_name": "OPAY",
"currency": "NGN",
"country": "NGA",
"split_type": "FLAT",
"split_value": 5000,
"active": true,
"created_at": "2026-07-13T14:26:12.115065",
"last_modified": "2026-07-14T14:19:46.542508009"
},
"message": "split account updated successfully"
}
```
Setting `active: false` deactivates the split account without deleting it. A
deactivated split account cannot be used in a checkout until it is reactivated
by setting `active: true` again.
**API reference:** [Update Split Account](/api-reference/split-settlements/update-split-account)
## Step 5 — Delete a Split Account *(optional)*
Permanently deletes a split account by its `id`. This cannot be undone. If you want to temporarily stop using a split account without deleting it, use the Update endpoint to set `active: false` instead.
```bash cURL theme={null}
curl --request DELETE \
--url https://api.payaza.africa/live/settlement/settlement/merchant/split-account/114 \
--header 'Authorization: Payaza ' \
--header 'X-TenantID: test'
```
```javascript Node.js theme={null}
const splitAccountId = 114;
const response = await fetch(
`https://api.payaza.africa/live/settlement/settlement/merchant/split-account/${splitAccountId}`,
{
method: "DELETE",
headers: {
Authorization: "Payaza ",
"X-TenantID": "test",
},
},
);
const data = await response.json();
console.log(data.message); // "split account deleted successfully"
```
**Path parameter**
| Parameter | Type | Description |
| --------- | ------- | --------------------------------------- |
| `id` | Integer | The `id` of the split account to delete |
**Sample response — success**
```json theme={null}
{
"code": "00",
"success": true,
"error": null,
"data": null,
"message": "split account deleted successfully"
}
```
**Sample response — failed (invalid key)**
```json theme={null}
{
"code": "09",
"data": null,
"success": false,
"message": "invalid key"
}
```
**Sample response — failed (not found)**
```json theme={null}
{
"code": "97",
"success": null,
"error": "split account not found",
"data": null,
"message": null
}
```
**Sample response — failed (already deleted or deactivated)**
```json theme={null}
{
"code": "98",
"success": null,
"error": "split account is deleted or deactivated",
"data": null,
"message": null
}
```
**API reference:** [Delete Split Account](/api-reference/split-settlements/delete-split-account)
## Error handling
| Message | What to do |
| ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Validation error | Read the `error` field — common causes: `split_value` out of range for `PERCENTAGE`, or a duplicate split account already exists for that bank account |
| Split account not found | Confirm the `id` in the URL path matches an existing split account from your Fetch response |
| Split account deleted or deactivated | The account has been deleted or set to `active: false`. Reactivate via Update, or create a new one |
| Invalid API key | Confirm your `Authorization` header is formatted as `Payaza ` |
| Success | No action needed |
## Developer notes
* **`split_value` is your cut, not the beneficiary's.** The `split_value` defines how much the Payaza account owner retains. The split account beneficiary always receives the remainder. This is the single most important thing to get right when configuring splits.
* For `PERCENTAGE` splits, a `split_value` of `20` means you keep 20% — the beneficiary receives 80%. If you want the beneficiary to receive only 10%, set `split_value: 90`.
* For `FLAT` splits, a `split_value` of `2000` means you keep ₦2,000 from every transaction — the beneficiary receives the transaction amount minus ₦2,000. Ensure your `split_value` never exceeds the minimum transaction amount or the split will fail.
* Always save `data.code` immediately after creating a split account — this is the only identifier used in Checkout requests, and it can be retrieved later using the Fetch Split Accounts API.
* The `id` (integer) and `code` (string prefixed `SSA_`) are two different identifiers. Use `code` in Checkout requests; use `id` in Update and Delete requests.
* You can include multiple split accounts in a single checkout by adding multiple objects to the `split_accounts` array. Each must have a valid, active `code`.
* Prefer `active: false` via the Update endpoint over Delete if you think you may need the split account again. Deletion is permanent.
* Split accounts can be created in advance and reused across many transactions — you do not need to create a new split account per transaction. Create once, reference many times.
* If you add multiple `PERCENTAGE` split accounts to a single checkout, each one defines a separate retained amount — the percentages do not combine. Validate your split logic carefully in the test environment before going live.