TagPayTagPay

API Reference

Transfers

A Transfer moves money out of your TagPay wallet to a bank account — a single payout or a bulk batch. Send to a saved recipient (RCP_ code) or a settlement-account id.

Initiate a transfer

POST/v1/transfers/initiate

Atomically debits your wallet and queues the disbursement. Pass an Idempotency-Key header to make retries safe. In live mode, a transfer above your OTP threshold returns status: "awaiting_otp" — finalize it with the emailed code (see *Finalize a transfer*). Sandbox transfers are never OTP-gated.

Body parameters

amountintegerrequired

Amount in kobo. Must exceed the configured minimum (see Get transfer config).

recipientstringrequired

An RCP_ recipient code or a settlement-account id.

narrationstringoptional

Statement narration, max 100 chars.

referencestringoptional

Your unique reference. Auto-generated if omitted. 1–100 chars of [A-Za-z0-9_-.].

currencystringoptional

NGN only at this time.

metadataobjectoptional

Arbitrary key/value pairs echoed back and in webhooks.

Response

200
transfer_idstring

TagPay-assigned transfer id (UUID).

referencestring

Transfer reference (trf_…). Use this to finalize/verify.

statusenum<'queued' | 'processing' | 'success' | 'failed' | 'reversed' | 'awaiting_otp'>

Lifecycle status.

amountinteger

Amount in kobo.

feeinteger

Transfer fee in kobo.

currencystring

Always NGN.

narrationstring

Statement narration.

recipientobject

Resolved destination.

idstring

Internal settlement-account id.

account_namestring

Resolved account name.

account_numberstring

10-digit NUBAN.

bank_codestring

NIP bank code.

provider_referencestring

Downstream NIP reference (null until processed).

created_atstring

ISO-8601 timestamp.

Errors

INSUFFICIENT_FUNDS400Wallet balance is below amount + fee.
AMOUNT_BELOW_MINIMUM400Amount is under the configured withdrawal minimum.
RECIPIENT_NOT_FOUND404No recipient/settlement account for that identifier.

Initiate a bulk transfer

POST/v1/transfers/bulk

One atomic wallet debit for the batch total. Each child transfer runs through the disbursement pipeline independently and compensates per-transfer on failure. Returns 202 with a batch summary; poll *Get a bulk batch* for progress. Bulk transfers are never OTP-gated.

Body parameters

currencystringoptional

NGN only at this time.

transfersarray<object>required

1–100 transfer items.

amountintegerrequired

Amount in kobo.

recipientstringrequired

RCP_ code or settlement-account id.

narrationstringoptional

Per-item narration, max 100 chars.

referencestringoptional

Per-item unique reference.

Response

202
batch_idstring

Batch id (UUID). Use it with Get a bulk batch.

statusstring

Batch-level status (e.g. processing).

total_countinteger

Number of child transfers.

total_amountinteger

Sum of all amounts in kobo.

currencystring

Always NGN.

transfersarray<Transfer>

The created child transfers.

Get a bulk batch

GET/v1/transfers/bulk/:batch_id

Returns the batch summary, per-status child counts, and the hydrated transfer list.

Path parameters

batch_idstringrequired

The batch id (UUID).

Response

200
batch_idstring

Batch id (UUID).

statusstring

Batch-level status.

countsobject

Child counts by status.

queuedinteger

Not yet processed.

processinginteger

In flight.

successinteger

Completed.

failedinteger

Failed (compensated).

transfersarray<Transfer>

Hydrated child transfers.

List transfers

GET/v1/transfers

Reverse-chronological by default. Filter by status, date range, or recipient, or search by reference.

Query parameters

pageintegeroptional

Page number, 1-indexed.

per_pageintegeroptional

Results per page, max 100.

statusstringoptional

Filter by transfer status.

fromstringoptional

ISO-8601 date — start of range.

tostringoptional

ISO-8601 date — end of range.

recipientstringoptional

Filter by recipient settlement-account id.

searchstringoptional

Search by your reference or the provider reference (partial, case-insensitive).

Response

200
dataarray<Transfer>

Array of transfer objects.

metaobject

Pagination metadata.

totalinteger

Total matching records.

pageinteger

Current page.

per_pageinteger

Per-page count.

Verify transfers

POST/v1/transfers/verify

Recon endpoint: hand us up to 100 references, get one row per requested reference in input order. Unknown references come back with status: "unknown" and found: false rather than being dropped.

Body parameters

referencesarray<string>required

1–100 transfer references.

Response

200
dataarray<object>

One row per requested reference.

referencestring

The requested reference.

foundboolean

False if no transfer matched.

statusstring

Transfer status, or "unknown" if not found.

amountinteger

Amount in kobo (0 if not found).

Get transfer config

GET/v1/transfers/config

Returns the current withdrawal minimum and flat fee, both in kobo. Admin-configurable; cached 30s server-side.

Response

200
min_amountinteger

Minimum transfer amount in kobo.

feeinteger

Flat transfer fee in kobo.

currencystring

Always NGN.

Retrieve a transfer

GET/v1/transfers/:id

Returns the full transfer resource.

Path parameters

idstringrequired

Transfer id (UUID).

Response

200
transfer_idstring

Transfer id (UUID).

referencestring

Transfer reference (trf_…).

statusstring

Lifecycle status.

amountinteger

Amount in kobo.

feeinteger

Fee in kobo.

provider_referencestring

Downstream NIP reference.

failure_reasonstring

Set when status is failed.

failure_codestring

Machine-readable failure code. Set when status is failed.

created_atstring

ISO-8601 timestamp.

Finalize a transfer

POST/v1/transfers/finalize_transfer

Live-only. Verifies the emailed 6-digit code, debits the wallet, and queues the disbursement. After 3 failed attempts the code locks — request a fresh one via *Resend transfer OTP*.

Body parameters

transfer_referencestringrequired

The reference from the awaiting_otp response of Initiate.

otpstringrequired

6-digit code from the email.

Response

200
referencestring

Transfer reference.

statusstring

Now "queued".

Errors

UNAUTHORIZED401Invalid, expired, or locked OTP.

Resend transfer OTP

POST/v1/transfers/resend_otp

Generates a new code, resets the attempt counter, extends expiry by 10 minutes, and re-sends the email.

Body parameters

transfer_referencestringrequired

The awaiting_otp transfer reference.

Response

200
transfer_referencestring

The transfer reference.

statusstring

Still "awaiting_otp".