Wallets

A wallet is a virtual account that holds funds for one of your customers. When you create a wallet for a customer, TagPay provisions a unique 10-digit account number for it. Your customers can receive funds, make payments, and transfer money — all through that account number. Your merchant account also has its own wallet, which you use to hold settlement funds and fund operations in sandbox mode.

Wallet account numbers

Every wallet is identified by a unique 10-digit account number. This number works like a conventional Nigerian bank account number — other parties can send funds directly to it via NIP (bank transfer). You can look up any wallet by its account number using GET /wallet/info.

GET https://api.tagpay.ng/v1/wallet/info?accountNumber=0123456789
Authorization: Bearer <your-access-token>

Wallet states

A wallet can be in one of three states:

State	Description
Active	The wallet is open and can send and receive funds normally.
Closed	The wallet is permanently shut. No credits or debits are permitted.
Blocked	The wallet is temporarily suspended. Transactions are rejected until the wallet is re-enabled.

Closing a wallet

To permanently close a wallet, call POST /wallet/close. This action is irreversible.

POST https://api.tagpay.ng/v1/wallet/close
Authorization: Bearer <your-access-token>
Content-Type: application/json

{
  "customerId": "cust_abc123",
  "reason": "Customer requested account closure"
}

Blocking and unblocking a wallet

Temporarily block a wallet with POST /wallet/close (passing a reason) or re-enable it with POST /wallet/enable.

POST https://api.tagpay.ng/v1/wallet/enable
Authorization: Bearer <your-access-token>
Content-Type: application/json

{
  "customerId": "cust_abc123",
  "reason": "Compliance hold lifted"
}

Creating a wallet

Create a wallet for a customer by calling POST /wallet. You must supply the customer’s personal details, date of birth, phone number, and at least one KYC identifier (BVN or NIN).

POST https://api.tagpay.ng/v1/wallet
Authorization: Bearer <your-access-token>
Content-Type: application/json

{
  "firstName": "Ngozi",
  "lastName": "Eze",
  "phoneNumber": "08034567890",
  "dateOfBirth": "1990-05-15",
  "email": "[email protected]",
  "bvn": "12345678901",
  "tier": "TIER_1",
  "currency": "NGN"
}

You must provide either a bvn or nin (or both). Wallets cannot be created without at least one KYC identifier.

Field	Required	Description
`firstName`	Yes	Customer’s first name
`lastName`	Yes	Customer’s last name
`phoneNumber`	Yes	Customer’s phone number
`dateOfBirth`	Yes	Date of birth in `YYYY-MM-DD` format
`email`	No	Customer’s email address
`bvn`	Conditional	11-digit Bank Verification Number
`nin`	Conditional	11-digit National Identification Number
`tier`	No	Wallet tier: `TIER_1`, `TIER_2`, or `TIER_3` (default: `TIER_1`)
`currency`	No	Currency code — only `NGN` is supported
`customerId`	No	Your own identifier for the customer
`metadata`	No	Arbitrary key-value data attached to the wallet

Bulk wallet creation

To create wallets for multiple customers in one request, upload a CSV file to POST /wallet/bulk-create-customers. The CSV must contain one row per customer with the same fields as the single-wallet endpoint.

Wallet balances

A wallet has two balance figures:

Balance	Description
Wallet balance (`availableBalance`)	Funds available for the customer to spend right now.
Booked balance (`bookedBalance`)	Total funds in the wallet, including amounts not yet cleared.

For day-to-day operations, use availableBalance to determine how much a customer can spend.

Post-no-credit mode

Post-no-credit mode allows a wallet to be debited but not credited. Use this to enforce collection-only behaviour on specific wallets — for example, loan repayment accounts that should never receive inbound transfers. Enable or disable post-no-credit mode per wallet. Only main merchants and admins can toggle this setting.

POST https://api.tagpay.ng/v1/wallet/enable-post-no-credit
Authorization: Bearer <your-access-token>
Content-Type: application/json

{
  "customerId": "cust_abc123",
  "reason": "Loan repayment wallet"
}

To restore normal credit behaviour:

POST https://api.tagpay.ng/v1/wallet/disable-post-no-credit
Authorization: Bearer <your-access-token>
Content-Type: application/json

{
  "customerId": "cust_abc123"
}

Crediting and debiting wallets

Use the wallet endpoints to directly credit or debit a customer’s wallet from your merchant account.

Credit a wallet

POST https://api.tagpay.ng/v1/wallet/credit
Authorization: Bearer <your-access-token>
Content-Type: application/json

{
  "customerId": "cust_abc123",
  "amount": 5000,
  "reference": "ref_20260101_001",
  "metadata": { "orderId": "ORD-987" }
}

Debit a wallet

POST https://api.tagpay.ng/v1/wallet/debit
Authorization: Bearer <your-access-token>
Content-Type: application/json

{
  "customerId": "cust_abc123",
  "amount": 2000,
  "reference": "ref_20260101_002",
  "metadata": { "orderId": "ORD-988" }
}

The reference field must be at least 10 characters. Use a unique value for every transaction to allow safe retries and prevent duplicates.

Batch operations

To credit or debit multiple wallets in a single request, use the batch endpoints:

Endpoint	Description
`POST /wallet/batch-credit-customer-wallet`	Credit multiple wallets by `customerId`
`POST /wallet/batch-debit-customer-wallet`	Debit multiple wallets by `customerId`
`POST /wallet/batch-credit-customer-via-wallet-id`	Credit multiple wallets by wallet ID
`POST /wallet/batch-debit-customer-via-wallet-id`	Debit multiple wallets by wallet ID

Each batch request takes a batchReference (minimum 10 characters) and an array of transactions:

{
  "batchReference": "batch_payroll_20260401",
  "transactions": [
    { "customerId": "cust_001", "amount": 10000, "reference": "ref_001_20260401" },
    { "customerId": "cust_002", "amount": 15000, "reference": "ref_002_20260401" }
  ]
}

Wallet-to-wallet vs bank transfers

TagPay supports two types of outbound transfers from a customer wallet:

Transfer type	Description	Endpoint
Wallet transfer	Instant transfer to another TagPay wallet by account number	Customer-initiated via `/customer/transfer/phone` or bulk CSV
Bank transfer	NIP transfer to any Nigerian bank account	Customer-initiated via `POST /customer/transfer/bank`

Both transfer types require the customer to be authenticated and, where a PIN is set, to supply their transaction PIN.

Listing wallets

Retrieve all wallets under your merchant account:

GET https://api.tagpay.ng/v1/wallet?page=1&perPage=20
Authorization: Bearer <your-access-token>

Filter by accountNumber, phoneNumber, or a search term. Up to 500 account numbers can be looked up in a single bulk request via GET /wallet/customer/accounts.

Wallet management guide

Step-by-step guide to creating and managing wallets

Funds transfer

Send funds to banks and between wallets

Customers

Understand customer accounts and KYC tiers

Transactions

Understand transaction states, types, and reversals

Get Started

Core Concepts

Guides

Wallet account numbers

Wallet states

Closing a wallet

Blocking and unblocking a wallet

Creating a wallet

Bulk wallet creation

Wallet balances

Post-no-credit mode

Crediting and debiting wallets

Credit a wallet

Debit a wallet

Batch operations

Wallet-to-wallet vs bank transfers

Listing wallets

Wallet management guide

Funds transfer

Customers

Transactions

​Wallet account numbers

​Wallet states

​Closing a wallet

​Blocking and unblocking a wallet

​Creating a wallet

​Bulk wallet creation

​Wallet balances

​Post-no-credit mode

​Crediting and debiting wallets

​Credit a wallet

​Debit a wallet

​Batch operations

​Wallet-to-wallet vs bank transfers

​Listing wallets

​Related pages

Wallet management guide

Funds transfer

Customers

Transactions

Wallet account numbers

Wallet states

Closing a wallet

Blocking and unblocking a wallet

Creating a wallet

Bulk wallet creation

Wallet balances

Post-no-credit mode

Crediting and debiting wallets

Credit a wallet

Debit a wallet

Batch operations

Wallet-to-wallet vs bank transfers

Listing wallets

Related pages