TagPayTagPay

API Reference

Collection Accounts

Collection accounts are virtual NUBANs for inbound bank transfers. Create expiring accounts for exact-amount one-off deposits, or use a permanent live account for open-ended merchant deposits.

Create a collection account

POST/v1/collection-accounts

Creates a virtual account under the authenticated merchant. This route is also available as /v1/virtual-accounts. For type="expiring", send reference and expectedAmount in kobo; TagPay always sets the expiry to 15 minutes and sends the vendor an exact expected amount in naira. For type="permanent", omit expectedAmount; permanent accounts are live-only and never expire. Every merchant starts with one auto-provisioned permanent account and can create additional ones — each additional permanent account requires an explicit reference.

Body parameters

typeenum<'expiring' | 'permanent'>required

Account type to create.

referencestringoptional

Merchant reference and idempotency key. Required for expiring and for any additional permanent account; a merchant's first permanent account may omit it and defaults to the merchant primary reference.

expectedAmountintegeroptional

Expected amount in kobo. Required for expiring; rejected for permanent.

labelstringoptional

Optional label shown during bank name-enquiry. Max 80 characters after bank-rail-safe normalization.

metadataobjectoptional

Arbitrary key/value metadata echoed by vendor webhooks.

Response

200
idstring

TagPay collection account ID.

merchantIdstring

Owning merchant ID.

vendorIdstring

Upstream TagPay Core collection-account ID.

accountNumberstring

10-digit NUBAN account number customers transfer into.

accountNamestring

Account name shown by bank name-enquiry.

referencestring

Merchant reference and create idempotency key.

labelstring | null

Human-readable account label sent to the bank rail.

typeenum<'expiring' | 'permanent'>

Collection-account type.

statusenum<'active' | 'expired' | 'deactivated'>

Current account status.

expiresAtstring | null

ISO-8601 expiry timestamp. Null for permanent accounts.

metadataobject | null

Metadata echoed back from the vendor on collection webhooks.

totalCollectedstring

Total collected through this account in kobo. Serialized as a string for precision.

transactionCountinteger

Number of successful credits recorded for this account.

lastCollectionAtstring | null

ISO-8601 timestamp of the most recent successful credit.

customerIdstring | null

Reserved for customer-scoped collection accounts.

transactionIdstring | null

Linked transaction ID for checkout-created expiring accounts. Null for direct accounts.

createdAtstring

ISO-8601 creation timestamp.

updatedAtstring

ISO-8601 last-update timestamp.

Errors

VALIDATION_ERROR400`type` is invalid, `reference` is missing for an expiring account, or `expectedAmount` is missing/invalid.
PERMANENT_REQUIRES_LIVE400Permanent collection accounts can only be created with live credentials.
REFERENCE_CONFLICT409The reference already exists as another collection-account type.
UNAUTHORIZED401Secret key missing or invalid.
VENDOR_UNAVAILABLE502The upstream collection-account provider rejected or could not complete the request.

List collection accounts

GET/v1/collection-accounts

Returns all collection accounts for the authenticated merchant from TagPay local storage, ordered by type and creation time. Use this to show permanent and expiring accounts in the dashboard without round-tripping to the vendor.

Response

200
dataarray<CollectionAccount>

Array of collection account objects.

Retrieve a collection account

GET/v1/collection-accounts/:id

Returns a single collection account by TagPay ID. Accounts owned by another merchant return 404.

Path parameters

idstringrequired

Collection account ID.

Response

200
idstring

TagPay collection account ID.

merchantIdstring

Owning merchant ID.

vendorIdstring

Upstream TagPay Core collection-account ID.

accountNumberstring

10-digit NUBAN account number customers transfer into.

accountNamestring

Account name shown by bank name-enquiry.

referencestring

Merchant reference and create idempotency key.

labelstring | null

Human-readable account label sent to the bank rail.

typeenum<'expiring' | 'permanent'>

Collection-account type.

statusenum<'active' | 'expired' | 'deactivated'>

Current account status.

expiresAtstring | null

ISO-8601 expiry timestamp. Null for permanent accounts.

metadataobject | null

Metadata echoed back from the vendor on collection webhooks.

totalCollectedstring

Total collected through this account in kobo. Serialized as a string for precision.

transactionCountinteger

Number of successful credits recorded for this account.

lastCollectionAtstring | null

ISO-8601 timestamp of the most recent successful credit.

customerIdstring | null

Reserved for customer-scoped collection accounts.

transactionIdstring | null

Linked transaction ID for checkout-created expiring accounts. Null for direct accounts.

createdAtstring

ISO-8601 creation timestamp.

updatedAtstring

ISO-8601 last-update timestamp.

Errors

NOT_FOUND404No collection account with that ID owned by this merchant.

List collection account transactions

GET/v1/collection-accounts/:id/transactions

Returns the upstream vendor ledger for reconciliation. Merchant-wide transaction history is still available from the Transactions API; this endpoint is for account-level collection reconciliation.

Path parameters

idstringrequired

Collection account ID.

Query parameters

pageintegeroptional

Page number, 1-indexed. Defaults to 1.

perPageintegeroptional

Results per page. Defaults to 20.

Response

200
dataarray<CollectionAccountTransaction>

Vendor ledger entries for this account.

metaobject

Pagination metadata from the vendor.

totalinteger

Total matching records.

pageinteger

Current page.

perPageinteger

Per-page count.

pageCountinteger

Total number of pages.

Errors

NOT_FOUND404No collection account with that ID owned by this merchant.