KuvarPay Split Payments Guide

Split Payments allow merchants to automatically distribute revenue from a single transaction across multiple parties (e.g., vendors, partners, or affiliates). This guide explains how to configure and use Subaccounts and Split Groups within the KuvarPay ecosystem.

1. Key Concepts

Subaccounts

A Subaccount represents a secondary entity that receives a portion of a transaction's revenue. Each subaccount is linked to its own settlement destination — a bank account, a mobile-money wallet, or a crypto wallet.

Identified by a unique code: SUB_xxxxxxxx

Settlement type is one of BANK_TRANSFER, MOBILE_MONEY, or CRYPTO. If you omit type, it is inferred from the fields you provide.

Has its own settlement account (bank / MoMo keyed off a method_id from getBanks; crypto by wallet address).

Can have a default percentage charge (ignored if overridden by a Split Group).

Split Groups

A Split Group is a collection of one or more subaccounts used to distribute revenue according to predefined percentage shares.

Identified by a unique code: SPL_xxxxxxxx

Specifies a Bearer Type (who pays the KuvarPay transaction fees).

Total shares must sum to 100%.

2. Integration Workflow

Step 1: Create a Subaccount

Before you can split payments, you must create subaccounts for your recipients. A
subaccount settles to a bank, mobile money, or crypto destination.

1a. Look up the settlement destination

Bank and mobile-money subaccounts are keyed off an opaque method_id — never a bank
code. Fetch the list for the recipient's country first:

direction defaults to 'inbound' (collection methods). Subaccount settlement is a payout,
so pass 'outbound'. If your key belongs to a sandbox-mode business, add sandbox: true —
see Testing in Sandbox.

1b. Create the subaccount

Endpoint: POST /api/v1/subaccounts

Bank transfer — the method's own type selects the rail, so type is optional:

{
  "business_name": "Vendor A",
  "method_id": "3e27e89f-f760-4f11-b1cc-dbe0db12bed0",
  "account_number": "0690000032",
  "account_name": "Vendor A Enterprises",
  "percentage_charge": 10,
  "currency": "NGN"
}

Mobile money — same method_id field, with a phone instead of an account number:

{
  "business_name": "Vendor B",
  "method_id": "b91c7f04-2a1e-4d60-9f8c-73aa0c1d55e2",
  "mobile_money_number": "+254701234567",
  "percentage_charge": 10,
  "currency": "KES"
}

Changed 2026-08-02. settlement_bank and mobile_money_provider (raw provider bank /
network codes) are no longer accepted — pass method_id from step 1a instead. The gateway
resolves it to the provider's native code internally, so your integration never handles a
provider-specific identifier and keeps working if a corridor is re-routed. Reads return
method_id and bank_name.

Crypto wallet — crypto_network must be one of BEP20 or POLYGON:

{
  "business_name": "Vendor C",
  "type": "CRYPTO",
  "crypto_currency": "USDT",
  "crypto_network": "BEP20",
  "wallet_address": "0x...",
  "percentage_charge": 10,
  "currency": "NGN"
}

currency must be a supported settlement currency (e.g. NGN, KES, RWF) — it is the subaccount's accounting currency even for a crypto destination.

Step 2: (Optional) Create a Split Group

Create a group if you need to distribute revenue to multiple parties simultaneously.

Endpoint: POST /api/v1/split

{
  "name": "Revenue Share Group",
  "bearer_type": "account",
  "subaccounts": [
    { "subaccount": "SUB_ABC123", "share": 70 },
    { "subaccount": "SUB_XYZ456", "share": 30 }
  ]
}

Step 3: Initiate a Split Transaction

When creating a Checkout Session or Transaction, specify either a single subaccount or a split group.

[!IMPORTANT]
You cannot specify both subaccount and split_code in the same request.

Using a Single Subaccount

Revenue will be split between the main Merchant and this Subaccount based on the subaccount's percentage_charge.

// POST /api/v1/checkout-sessions
{
  "amount": 1000,
  "currency": "NGN",
  "subaccount": "SUB_ABC123"
}

Using a Split Group

Revenue will be distributed among all subaccounts in the group according to their defined shares.

// POST /api/v1/checkout-sessions
{
  "amount": 1000,
  "currency": "NGN",
  "split_code": "SPL_12345"
}

3. Bearer Types (Fee Responsibility)

When using Split Groups, you can define who bears the transaction fees:

account: The main merchant pays the full fee.

subaccount: One specific subaccount is designated to pay the fee (not supported for multi-splits).

all: Fees are shared proportionally among all parties based on their revenue shares.

4. Immutable Records: Split Snapshots

KuvarPay implements Split Snapshots. When a transaction is created, the system captures the exact split configuration at that moment.

If you delete a subaccount or change a split group's shares later, finished transactions will still be settled based on the snapshot.

This ensures historical accuracy and prevents settlement disputes.

The snapshot is returned in the transaction details as splitSnapshot.

5. SDK Usage

Web SDK (Frontend)

In the Web SDK, simply add the subaccount or split_code parameters to your openPayment call:

Server SDK (Backend)

Management of subaccounts and split groups is typically done on the backend using the Server SDK (which requires your Secret API Key).

Create a Subaccount

Create a Split Group

Initiate Checkout Session with Split

6. Management Operations

Beyond creation, the Server SDK and API support full management of the split payment lifecycle.

Updating Subaccounts

You can update subaccount details (e.g. switching the settlement destination with a new method_id, or increasing the percentage charge). Note that updates will not affect existing transactions already in progress.

Method: kv.updateSubaccount(code, data)

Listing and Querying

Useful for building administration dashboards.

Deleting Entities

KuvarPay uses Soft Deletion for subaccounts and split groups.

Deleting a subaccount prevents it from being used in new checkout sessions.

Deleting a split group makes the split_code invalid for future transactions.

Ongoing Settlements: Transactions created before the deletion will continue to settle according to the splitSnapshot captured at checkout.

7. Best Practices and Guidelines

To ensure smooth automated settlements, follow these integration guidelines:

Verify Bank Details First

Where verification is available, resolve the account name before creating a subaccount so it
matches the vendor's legal identity — this prevents settlement failures from mistyped details.

Coverage is NGN bank accounts. Every other currency, and all mobile money, returns
supported: false — that is a normal response, not an error. Use the name your vendor supplied
and continue.

Do not block subaccount creation on resolved. Outside NGN it is always false, so
gating on it makes every other corridor uncreatable. Only treat
supported: true, resolved: false as a real failure — that means the lookup ran and the
account was not found.

Currency Alignment

Ensure the subaccount's settlement currency matches your settlement currency. While KuvarPay handles some conversions, aligned currencies result in faster payouts and lower fees for your vendors.

Idempotency

If you are programmatically creating subaccounts based on your own user database, store the subaccount_code in your system immediately. Do not attempt to re-create a subaccount for the same vendor multiple times.

Testing in Sandbox

Use a sandbox-mode API key. Sandbox transactions run the same lifecycle without real money
movement.

Live and sandbox are separate method_id spaces — the same bank has a different id in
each. Construct the client with sandbox: true (or pass it per call to getBanks) so the
destination list matches the mode your key operates in:

getBanks is served by a public endpoint that cannot see your key, so without this it returns
the live list. A live method_id used with a sandbox key fails with
reason: 'METHOD_MODE_MISMATCH' on resolveRecipient and on subaccount creation — that error
means the id came from the wrong environment, not that the account is invalid.

Monitoring Snapshots

Always verify the splitSnapshot field in transaction webhooks. This is the definitive record of how a transaction's revenue was distributed, regardless of any subsequent changes to your split groups.

Split Payment Guide

KuvarPay Split Payments Guide#

1. Key Concepts#

Subaccounts#

Split Groups#

2. Integration Workflow#

Step 1: Create a Subaccount#

1a. Look up the settlement destination#

1b. Create the subaccount#

Step 2: (Optional) Create a Split Group#

Step 3: Initiate a Split Transaction#

Using a Single Subaccount#

Using a Split Group#

3. Bearer Types (Fee Responsibility)#

4. Immutable Records: Split Snapshots#

5. SDK Usage#

Web SDK (Frontend)#

Server SDK (Backend)#

Create a Subaccount#

Create a Split Group#

Initiate Checkout Session with Split#

6. Management Operations#

Updating Subaccounts#

Listing and Querying#

Deleting Entities#

7. Best Practices and Guidelines#

Verify Bank Details First#

Currency Alignment#

Idempotency#

Testing in Sandbox#

Monitoring Snapshots#