TagPayTagPay

API Reference

Wallet

A Wallet holds the funds you've collected through TagPay, denominated in kobo. There is one wallet per mode (test, live) per merchant — credits arrive automatically when charges succeed, debits fire when you withdraw via Transfers. Use these endpoints to read the live balance, inspect the ledger, see how each charge was split between you and TagPay's fee wallet, and configure automatic sweep-to-bank.

Get wallet balance

GET/v1/wallet/balance

Returns the wallet for the mode (test/live) determined by the secret key. The wallet is auto-provisioned on first read if it does not exist yet — new merchants get a 0-balance wallet instead of a 404.

Response

200
merchant_idstring

Your merchant ID.

currencystring

Always `NGN`.

balanceinteger

Total ledger balance in kobo. Same as `available_balance` today; the split between available and ledger exists for future hold/pending logic.

available_balanceinteger

Funds you can withdraw right now (kobo). Pending balances are excluded — debits are gated against this figure.

pending_balanceinteger

Funds credited but not yet released (kobo). Today this is always `0` for the live wallet; reserved for future hold rules.

ledger_balanceinteger

Available + pending (kobo). The accounting view of total wallet equity.

last_updatedstring

ISO-8601 timestamp of the most recent mutation to this wallet.

Errors

INVALID_KEY401Secret key missing or invalid.

List ledger entries

GET/v1/wallet/ledger

Returns ledger entries in reverse-chronological order. Each entry records a single credit or debit against the wallet and includes pre/post balances so you can audit the running total. Scoped to the mode of the secret key.

Query parameters

typeenum<'credit' | 'debit'>optional

Filter by direction.

fromstringoptional

ISO-8601 start date (inclusive).

tostringoptional

ISO-8601 end date (inclusive).

pageintegeroptional

Page number, 1-indexed. Defaults to 1.

per_pageintegeroptional

Results per page, max 100. Defaults to 50.

Response

200
dataarray<LedgerEntry>

Array of ledger entry objects.

metaobject

Pagination metadata.

totalinteger

Total matching records.

pageinteger

Current page.

per_pageinteger

Per-page count.

page_countinteger

Total number of pages.

Errors

INVALID_KEY401Secret key missing or invalid.

List transaction splits

GET/v1/wallet/splits

Shows how every successful charge was split between your wallet and TagPay's fee wallet. Useful for reconciling settlement reports — you see the gross amount alongside the exact kobo that landed in each wallet. Only successful transactions in the current mode are returned.

Query parameters

fromstringoptional

ISO-8601 start date (inclusive).

tostringoptional

ISO-8601 end date (inclusive).

pageintegeroptional

Page number, 1-indexed. Defaults to 1.

per_pageintegeroptional

Results per page, max 100. Defaults to 50.

Response

200
dataarray<TransactionSplit>

Array of transactions with their wallet-level splits.

transaction_idstring

Transaction ID.

referencestring

Original charge reference.

total_amountinteger

Gross charge amount in kobo.

currencystring

Always `NGN`.

splitsarray<object>

One entry per wallet credited from this charge.

walletstring

Either your merchant ID, or `tagpay_fees` for the system fee wallet.

labelstring

Human-readable wallet label — `Merchant` or `TagPay Fee`.

amountinteger

Kobo credited to this wallet from the charge.

created_atstring

ISO-8601 charge timestamp.

metaobject

Pagination metadata.

totalinteger

Total matching records.

pageinteger

Current page.

per_pageinteger

Per-page count.

page_countinteger

Total number of pages.

Errors

INVALID_KEY401Secret key missing or invalid.

Get auto-sweep config

GET/v1/wallet/auto-sweep

Auto-sweep is live-only — the config is read against the live wallet regardless of which key (test or live) you authenticate with. When no config has been set, enabled is false and every other field is null.

Response

200
enabledboolean

Whether auto-sweep is currently active. When false, no sweep will fire regardless of other fields.

modeenum<'threshold' | 'scheduled'> | null

Trigger mode. `threshold` sweeps when the available balance crosses a kobo amount; `scheduled` sweeps on a cadence. Null when disabled.

threshold_kobointeger | null

Trigger amount in kobo. Set only when `mode=threshold`.

scheduleenum<'daily' | 'weekly'> | null

Cadence. Set only when `mode=scheduled`.

settlement_account_idstring | null

The verified SettlementAccount the swept funds land in. Required when enabling; null when disabled.

last_run_atstring | null

ISO-8601 timestamp of the most recent sweep, or null if never run.

Errors

INVALID_KEY401Secret key missing or invalid.

Configure auto-sweep

PUT/v1/wallet/auto-sweep

Two modes, mutually exclusive: threshold sweeps whenever the available balance reaches threshold_kobo; scheduled sweeps on a daily or weekly cadence. The recipient must be a verified SettlementAccount you own. Pass enabled: false to disable — every other field is ignored in that case. Auto-sweep is live-only and moves real money, so configure it with your live secret key (sk_live_*) or from the dashboard; a test key gets KEY_ENV_MISMATCH.

Body parameters

enabledbooleanrequired

Master switch. When false, the config is wiped and no other fields are read.

modeenum<'threshold' | 'scheduled'>optional

Required when enabled=true.

threshold_kobointegeroptional

Minimum available balance in kobo that triggers a sweep. Required when mode=threshold.

scheduleenum<'daily' | 'weekly'>optional

Cadence. Required when mode=scheduled.

settlement_account_idstringoptional

SettlementAccount ID. Must be verified and owned by you. Required when enabled=true.

Response

200
enabledboolean

Whether auto-sweep is currently active. When false, no sweep will fire regardless of other fields.

modeenum<'threshold' | 'scheduled'> | null

Trigger mode. `threshold` sweeps when the available balance crosses a kobo amount; `scheduled` sweeps on a cadence. Null when disabled.

threshold_kobointeger | null

Trigger amount in kobo. Set only when `mode=threshold`.

scheduleenum<'daily' | 'weekly'> | null

Cadence. Set only when `mode=scheduled`.

settlement_account_idstring | null

The verified SettlementAccount the swept funds land in. Required when enabling; null when disabled.

last_run_atstring | null

ISO-8601 timestamp of the most recent sweep, or null if never run.

Errors

VALIDATION_ERROR400A required field is missing for the chosen mode (e.g. `threshold_kobo` when `mode=threshold`).
NOT_FOUND404`settlement_account_id` does not exist or is not owned by you.
UNPROCESSABLE422The settlement account is not verified — verify it first.
INVALID_KEY401Secret key missing or invalid.
KEY_ENV_MISMATCH401Called with a test key. Auto-sweep moves live money; use your live secret key.