API Reference

Splits

A Split rule defines how a single charge is divided across one or more subaccounts. Create the rule once with **Create a split**, then reference its `split_code` on **Initialize a charge** — every successful payment is automatically split per the rule at credit time. Supports both percentage and flat-fee allocation, with up to 50 members per rule.

Create a split

POST/v1/splits

Create a rule and reference its split_code on charge initialize. subaccounts must contain 1–50 active members, each owned by you. For type=percentage, shares are 0–100 and must sum to ≤ 100 (the merchant keeps the remainder). For type=flat, shares are kobo amounts; the merchant keeps amount minus their sum.

Body parameters

namestringrequired

Internal label (1–200 chars).

typestringrequired

Allocation mode.

Allowed: 'percentage''flat'

bearer_typestringrequired

Who absorbs TagPay's processing fee.

Allowed: 'account''subaccount''all-proportional'

currencystringoptional

NGN only at this time. Defaults to NGN.

subaccountsarray<object>required

1–50 members. Each subaccount must be an active ACCT_… you own.

subaccountstringrequired

Subaccount code (ACCT_…).

sharenumberrequired

Percentage 0–100 if parent type=percentage; kobo amount if type=flat. Must be > 0.

Response

201

split_codestring

TagPay-assigned code (`SPL_…`). Reference this on charge initialize to apply the rule.

namestring

Internal label.

typeenum<'percentage' | 'flat'>

`percentage` — each `share` is a percentage of the charge amount (sum ≤ 100). `flat` — each `share` is a fixed kobo amount.

currencystring

Always `NGN`.

bearer_typeenum<'account' | 'subaccount' | 'all-proportional'>

Who absorbs TagPay's processing fee. `account` — merchant absorbs. `subaccount` — subaccounts absorb pro-rata. `all-proportional` — fee comes off the top before splitting.

activeboolean

Whether the rule is currently usable on new charges. Inactive rules are rejected at charge initialize.

subaccountsarray<object>

Members of the split. Order is preserved.

subaccountstring

Subaccount code (`ACCT_…`).

sharenumber

Percentage (0–100) if `type=percentage`; kobo amount if `type=flat`.

created_atstring

ISO-8601 creation timestamp.

updated_atstring

ISO-8601 last-update timestamp.

Errors

VALIDATION_ERROR400Missing/invalid field, share ≤ 0, or sum of percentage shares exceeds 100.

UNSUPPORTED_CURRENCY400Only `NGN` splits are supported at this time.

NOT_FOUND404One or more `subaccount` codes don't exist or aren't owned by you.

SUBACCOUNT_INACTIVE400One or more referenced subaccounts are inactive.

INVALID_KEY401Secret key missing or invalid.

List splits

GET/v1/splits

Returns rules in reverse-chronological order. Filter by active to hide deactivated rules.

Query parameters

activebooleanoptional

If true, only return rules currently usable on new charges.

pageintegeroptional

Page number, 1-indexed. Defaults to 1.

per_pageintegeroptional

Results per page, max 100. Defaults to 20.

Response

200

dataarray<Split>

Array of split rule objects (same shape as create).

metaobject

Pagination metadata.

totalinteger

Total matching records.

pageinteger

Current page.

per_pageinteger

Per-page count.

page_countinteger

Total number of pages.

Retrieve a split

GET/v1/splits/:code

Returns the full rule, including its current member list.

Path parameters

codestringrequired

The split code (SPL_…).

Response

200

split_codestring

TagPay-assigned code (`SPL_…`). Reference this on charge initialize to apply the rule.

namestring

Internal label.

typeenum<'percentage' | 'flat'>

`percentage` — each `share` is a percentage of the charge amount (sum ≤ 100). `flat` — each `share` is a fixed kobo amount.

currencystring

Always `NGN`.

bearer_typeenum<'account' | 'subaccount' | 'all-proportional'>

Who absorbs TagPay's processing fee. `account` — merchant absorbs. `subaccount` — subaccounts absorb pro-rata. `all-proportional` — fee comes off the top before splitting.

activeboolean

Whether the rule is currently usable on new charges. Inactive rules are rejected at charge initialize.

subaccountsarray<object>

Members of the split. Order is preserved.

subaccountstring

Subaccount code (`ACCT_…`).

sharenumber

Percentage (0–100) if `type=percentage`; kobo amount if `type=flat`.

created_atstring

ISO-8601 creation timestamp.

updated_atstring

ISO-8601 last-update timestamp.

Errors

NOT_FOUND404No split with that code owned by this merchant.

Update a split

PUT/v1/splits/:code

Partial update. Sending subaccounts replaces the entire member list in one atomic transaction — there is no per-member patch; pass the full new list. To remove a single member without rebuilding the array, use Remove a subaccount from a split instead. To deactivate, send `{ "active": false }`; existing snapshots taken at charge initialize are unaffected, but new charges referencing the rule will be rejected.

Path parameters

codestringrequired

The split code (SPL_…).

Body parameters

namestringoptional

New label (1–200 chars).

typestringoptional

New allocation mode.

Allowed: 'percentage''flat'

bearer_typestringoptional

New fee-bearer policy.

Allowed: 'account''subaccount''all-proportional'

subaccountsarray<object>optional

Replaces the entire member list (1–50 members).

subaccountstringrequired

Subaccount code (ACCT_…).

sharenumberrequired

Share value per parent type.

activebooleanoptional

Set false to deactivate, true to reactivate.

Response

200

split_codestring

TagPay-assigned code (`SPL_…`). Reference this on charge initialize to apply the rule.

namestring

Internal label.

typeenum<'percentage' | 'flat'>

`percentage` — each `share` is a percentage of the charge amount (sum ≤ 100). `flat` — each `share` is a fixed kobo amount.

currencystring

Always `NGN`.

bearer_typeenum<'account' | 'subaccount' | 'all-proportional'>

Who absorbs TagPay's processing fee. `account` — merchant absorbs. `subaccount` — subaccounts absorb pro-rata. `all-proportional` — fee comes off the top before splitting.

activeboolean

Whether the rule is currently usable on new charges. Inactive rules are rejected at charge initialize.

subaccountsarray<object>

Members of the split. Order is preserved.

subaccountstring

Subaccount code (`ACCT_…`).

sharenumber

Percentage (0–100) if `type=percentage`; kobo amount if `type=flat`.

created_atstring

ISO-8601 creation timestamp.

updated_atstring

ISO-8601 last-update timestamp.

Errors

NOT_FOUND404No split with that code, or a referenced subaccount doesn't exist.

VALIDATION_ERROR400A field is invalid, or a percentage-share sum exceeds 100.

Remove a subaccount from a split

DELETE/v1/splits/:code/subaccount

Surgical removal of one member without rebuilding the full subaccounts array. The split must have at least two members — removing the last member is rejected; delete the entire rule (via update with active: false) or replace it instead.

Path parameters

codestringrequired

The split code (SPL_…).

Body parameters

subaccountstringrequired

The subaccount code (ACCT_…) to remove from this split.

Response

200

split_codestring

TagPay-assigned code (`SPL_…`). Reference this on charge initialize to apply the rule.

namestring

Internal label.

typeenum<'percentage' | 'flat'>

`percentage` — each `share` is a percentage of the charge amount (sum ≤ 100). `flat` — each `share` is a fixed kobo amount.

currencystring

Always `NGN`.

bearer_typeenum<'account' | 'subaccount' | 'all-proportional'>

Who absorbs TagPay's processing fee. `account` — merchant absorbs. `subaccount` — subaccounts absorb pro-rata. `all-proportional` — fee comes off the top before splitting.

activeboolean

Whether the rule is currently usable on new charges. Inactive rules are rejected at charge initialize.

subaccountsarray<object>

Members of the split. Order is preserved.

subaccountstring

Subaccount code (`ACCT_…`).

sharenumber

Percentage (0–100) if `type=percentage`; kobo amount if `type=flat`.

created_atstring

ISO-8601 creation timestamp.

updated_atstring

ISO-8601 last-update timestamp.

Errors

NOT_FOUND404No split with that code, or the subaccount is not a member.

LAST_SUBACCOUNT400Cannot remove the last subaccount from a split — delete the split or add a replacement first.