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 (Bank Account or Mobile Money wallet).Identified by a unique code: SUB_xxxxxxxx
Has its own settlement account (resolved via the Banks API).
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.Endpoint: POST /api/v1/subaccounts{
"business_name": "Vendor A",
"settlement_bank": "044",
"account_number": "0690000032",
"percentage_charge": 10,
"currency": "NGN"
}
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.
{
"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.
{
"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., changing the settlement bank 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#
Always verify bank account numbers before creating a subaccount. Use the Banks API to resolve the account name and ensure it matches the vendor's legal identity. This prevents settlement failures due to invalid account details.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 the isSandbox: true flag in your API calls or use your test API keys to simulate splits. Sandbox transactions will transition through the same lifecycle but will not result in real money movement.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.Modified at 2026-04-11 17:01:25
