TagPayTagPay

API Reference

Subaccounts

A Subaccount represents a vendor, agent, or sub-merchant who receives a share of split-tagged transactions. Phase 1 settles to an external NUBAN — give us the bank code + account number and we'll route a slice of every charge that references the subaccount through a Split rule.

Create a subaccount

POST/v1/subaccounts

Creates a subaccount keyed by an ACCT_… code. bank_code is validated against the NIBSS bank list — call List banks to discover valid codes. account_number must be a 10-digit NUBAN. The pair (bank_code, account_number) is immutable after creation; to change the settlement destination, create a new subaccount.

Body parameters

business_namestringrequired

Vendor label (1–200 chars). Shown in the dashboard and on settlement reports.

bank_codestringrequired

NIBSS bank code (3–6 digits). See **List banks**.

account_numberstringrequired

10-digit NUBAN of the destination account.

percentage_chargenumberrequired

Platform fee on the vendor's slice (0–100, max 2 decimal places). Distinct from TagPay's processing fee.

primary_contact_emailstringoptional

Contact email for the vendor.

primary_contact_namestringoptional

Contact name for the vendor (1–120 chars).

primary_contact_phonestringoptional

Contact phone (1–32 chars).

metadataobjectoptional

Arbitrary key/value pairs stored alongside the subaccount.

Response

201
subaccount_codestring

TagPay-assigned code (`ACCT_…`). Use this in every subsequent subaccount and split call.

business_namestring

Human-friendly label for the vendor / sub-merchant.

bank_namestring

Resolved bank name (derived from `bank_code`).

bank_codestring

NIBSS bank code (3–6 digits). **Immutable** after creation.

account_numberstring

10-digit NUBAN where settlements land. **Immutable** after creation.

settlement_bankstring

Same value as `bank_name`. Mirrored for backwards compatibility with older Paystack-style consumers.

percentage_chargenumber

Platform fee taken off the subaccount's slice (0–100). This is **your** fee on the vendor, separate from TagPay's processing fee.

primary_contact_emailstring | null

Contact email for the vendor, or null.

primary_contact_namestring | null

Contact name for the vendor, or null.

primary_contact_phonestring | null

Contact phone for the vendor, or null.

metadataobject | null

Arbitrary key/value pairs you stored on the subaccount.

activeboolean

Whether the subaccount can be used in new splits. Inactive subaccounts are rejected at split-create/initialize time.

created_atstring

ISO-8601 creation timestamp.

updated_atstring

ISO-8601 last-update timestamp.

Errors

VALIDATION_ERROR400A field is missing or invalid (`bank_code` not 3–6 digits, `account_number` not 10 digits, `percentage_charge` outside 0–100, etc.).
INVALID_BANK_CODE400The supplied `bank_code` is not in the NIBSS bank list.
SUBACCOUNT_DUPLICATE409An active subaccount with the same `bank_code` + `account_number` already exists for this merchant.
INVALID_KEY401Secret key missing or invalid.

List subaccounts

GET/v1/subaccounts

Returns subaccounts in reverse-chronological order. Filter by active to hide deactivated vendors, or search by a substring of business_name.

Query parameters

activebooleanoptional

If true, only return subaccounts currently usable in splits.

searchstringoptional

Case-insensitive substring match on business_name.

pageintegeroptional

Page number, 1-indexed. Defaults to 1.

per_pageintegeroptional

Results per page, max 100. Defaults to 20.

Response

200
dataarray<Subaccount>

Array of subaccount 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 subaccount

GET/v1/subaccounts/:code

Returns the full subaccount resource.

Path parameters

codestringrequired

The subaccount code (ACCT_…).

Response

200
subaccount_codestring

TagPay-assigned code (`ACCT_…`). Use this in every subsequent subaccount and split call.

business_namestring

Human-friendly label for the vendor / sub-merchant.

bank_namestring

Resolved bank name (derived from `bank_code`).

bank_codestring

NIBSS bank code (3–6 digits). **Immutable** after creation.

account_numberstring

10-digit NUBAN where settlements land. **Immutable** after creation.

settlement_bankstring

Same value as `bank_name`. Mirrored for backwards compatibility with older Paystack-style consumers.

percentage_chargenumber

Platform fee taken off the subaccount's slice (0–100). This is **your** fee on the vendor, separate from TagPay's processing fee.

primary_contact_emailstring | null

Contact email for the vendor, or null.

primary_contact_namestring | null

Contact name for the vendor, or null.

primary_contact_phonestring | null

Contact phone for the vendor, or null.

metadataobject | null

Arbitrary key/value pairs you stored on the subaccount.

activeboolean

Whether the subaccount can be used in new splits. Inactive subaccounts are rejected at split-create/initialize time.

created_atstring

ISO-8601 creation timestamp.

updated_atstring

ISO-8601 last-update timestamp.

Errors

NOT_FOUND404No subaccount with that code owned by this merchant.

Update a subaccount

PUT/v1/subaccounts/:code

Send only the fields you want to change. bank_code and account_number are immutable — they're deliberately not in the update payload. To deactivate a subaccount, send `{ "active": false }`; in-flight splits that reference it will reject at initialize time, but historical settlements are preserved.

Path parameters

codestringrequired

The subaccount code (ACCT_…).

Body parameters

business_namestringoptional

New vendor label (1–200 chars).

percentage_chargenumberoptional

New platform fee (0–100, max 2 decimal places).

primary_contact_emailstringoptional

New contact email.

primary_contact_namestringoptional

New contact name.

primary_contact_phonestringoptional

New contact phone.

metadataobjectoptional

Replaces the stored metadata entirely.

activebooleanoptional

Set false to deactivate, true to reactivate.

Response

200
subaccount_codestring

TagPay-assigned code (`ACCT_…`). Use this in every subsequent subaccount and split call.

business_namestring

Human-friendly label for the vendor / sub-merchant.

bank_namestring

Resolved bank name (derived from `bank_code`).

bank_codestring

NIBSS bank code (3–6 digits). **Immutable** after creation.

account_numberstring

10-digit NUBAN where settlements land. **Immutable** after creation.

settlement_bankstring

Same value as `bank_name`. Mirrored for backwards compatibility with older Paystack-style consumers.

percentage_chargenumber

Platform fee taken off the subaccount's slice (0–100). This is **your** fee on the vendor, separate from TagPay's processing fee.

primary_contact_emailstring | null

Contact email for the vendor, or null.

primary_contact_namestring | null

Contact name for the vendor, or null.

primary_contact_phonestring | null

Contact phone for the vendor, or null.

metadataobject | null

Arbitrary key/value pairs you stored on the subaccount.

activeboolean

Whether the subaccount can be used in new splits. Inactive subaccounts are rejected at split-create/initialize time.

created_atstring

ISO-8601 creation timestamp.

updated_atstring

ISO-8601 last-update timestamp.

Errors

NOT_FOUND404No subaccount with that code owned by this merchant.
VALIDATION_ERROR400A field is invalid, or an immutable field (`bank_code`, `account_number`) was sent.