Split Settlements

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:

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.
Each split account gets a unique code (e.g. SSA_C0900E891783950401871).
When you initiate a checkout, you pass those codes in the split_accounts array.
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 page. Use your public API key for all split settlement requests.

Set the following headers on every request:

{
  "Authorization": "Payaza <Your public key encoded in base 64>",
  "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

Step-by-step flow

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.

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.

Initiate a checkout and include the split_accounts array with the relevant code(s).

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.

Example: Marketplace with vendor split (PERCENTAGE)

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.

Example: Fixed platform fee (FLAT)

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.

curl --request POST \
  --url https://api.payaza.africa/live/settlement/settlement/merchant/split-account \
  --header 'Authorization: Payaza <Your public key encoded in base 64>' \
  --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

{
  "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)

{
  "code": "96",
  "success": null,
  "error": "Amount must be between 0 and 100 for percentage split type",
  "data": null,
  "message": null
}

Sample response — failed (duplicate)

{
  "code": "96",
  "success": null,
  "error": "split account already exists",
  "data": null,
  "message": null
}

API reference: 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.

Single split account

  "split_accounts": [
    {
      "code": "SSA_C0900E891783950401871"
    }
  ]

Multiple split accounts

  "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.

curl --request GET \
  --url 'https://api.payaza.africa/live/settlement/settlement/merchant/split-account?page=1&size=10' \
  --header 'Authorization: Payaza <Your public key encoded in base 64>' \
  --header 'X-TenantID: test'

Query parameters

Parameter	Required	Description
`page`	✓	Page number — starts at `1`
`size`	✓	Number of records per page

Sample response

{
  "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

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.

curl --request PUT \
  --url https://api.payaza.africa/live/settlement/merchant/split-account/114 \
  --header 'Authorization: Payaza <YOUR_PUBLIC_KEY>' \
  --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

{
  "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

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.

curl --request DELETE \
  --url https://api.payaza.africa/live/settlement/settlement/merchant/split-account/114 \
  --header 'Authorization: Payaza <YOUR_PUBLIC_KEY>' \
  --header 'X-TenantID: test'

const splitAccountId = 114;

const response = await fetch(
  `https://api.payaza.africa/live/settlement/settlement/merchant/split-account/${splitAccountId}`,
  {
    method: "DELETE",
    headers: {
      Authorization: "Payaza <YOUR_PUBLIC_KEY>",
      "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

{
  "code": "00",
  "success": true,
  "error": null,
  "data": null,
  "message": "split account deleted successfully"
}

Sample response — failed (invalid key)

{
  "code": "09",
  "data": null,
  "success": false,
  "message": "invalid key"
}

Sample response — failed (not found)

{
  "code": "97",
  "success": null,
  "error": "split account not found",
  "data": null,
  "message": null
}

Sample response — failed (already deleted or deactivated)

{
  "code": "98",
  "success": null,
  "error": "split account is deleted or deactivated",
  "data": null,
  "message": null
}

API reference: 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 <YOUR_PUBLIC_KEY>`
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.

Get started

Developer tools

Accept payments

Send money

Disputes & refunds

Account management

Split Settlements

Overview

Key Requirements

Split types

How split settlement works end to end

Step 1 — Create a Split Account

Step 2 — Use the split account code in Checkout

Step 3 — Fetch all Split Accounts

Step 4 — Update a Split Account

Step 5 — Delete a Split Account (optional)

Error handling

Developer notes

​Overview

​Key Requirements

​Split types

​How split settlement works end to end

​Step 1 — Create a Split Account

​Step 2 — Use the split account code in Checkout

​Step 3 — Fetch all Split Accounts

​Step 4 — Update a Split Account

​Step 5 — Delete a Split Account (optional)

​Error handling

​Developer notes

Overview

Key Requirements

Split types

How split settlement works end to end

Step 1 — Create a Split Account

Step 2 — Use the split account code in Checkout

Step 3 — Fetch all Split Accounts

Step 4 — Update a Split Account

Step 5 — Delete a Split Account (optional)

Error handling

Developer notes