Wallet Management

Wallets are the core of TagPay’s customer financial accounts. Each wallet is tied to a customer identity and holds funds in NGN. This guide walks you through the complete wallet lifecycle: creation, funding, debiting, and closure.

Prerequisites

All wallet endpoints require a valid merchant Bearer token in the Authorization header:

Authorization: Bearer <your-token>

Create a wallet

Use POST /wallet to create a wallet for a new customer. You must supply at least one government-issued identifier — either a BVN or NIN.

Gather customer details

Collect the customer’s name, phone number, date of birth, and at least one of BVN or NIN. The customerId field is optional — if omitted, TagPay generates one.

Submit the creation request

curl -X POST https://api.tagpay.ng/v1/wallet \
  -H "Authorization: Bearer <your-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "Amara",
    "lastName": "Okafor",
    "phoneNumber": "08012345678",
    "dateOfBirth": "1990-06-15",
    "bvn": "12345678901",
    "email": "[email protected]",
    "currency": "NGN",
    "tier": "TIER_1"
  }'

{
  "success": true,
  "data": {
    "customerId": "cus_abc123",
    "accountNumber": "1234567890",
    "firstName": "Amara",
    "lastName": "Okafor",
    "balance": 0,
    "currency": "NGN",
    "tier": "TIER_1",
    "status": "active"
  }
}

Request fields

Field	Type	Required	Description
`firstName`	string	Yes	Customer’s first name
`lastName`	string	Yes	Customer’s last name
`phoneNumber`	string	Yes	Nigerian phone number
`dateOfBirth`	string	Yes	ISO date string (YYYY-MM-DD)
`bvn`	string	Yes*	11-digit BVN (*required if NIN not provided)
`nin`	string	Yes*	11-digit NIN (*required if BVN not provided)
`email`	string	No	Customer email address
`customerId`	string	No	Your internal customer ID
`currency`	string	No	Defaults to `NGN`
`tier`	string	No	`TIER_1`, `TIER_2`, or `TIER_3`. Defaults to `TIER_1`
`address`	string	No	Customer’s address
`metadata`	object	No	Arbitrary key-value pairs

You must provide either bvn or nin (or both). Requests without at least one identifier will be rejected.

Bulk wallet creation via CSV

To create wallets for many customers at once, upload a CSV file to POST /wallet/bulk-create-customers. The file must be sent as multipart/form-data with the field name customers.

cURL

curl -X POST https://api.tagpay.ng/v1/wallet/bulk-create-customers \
  -H "Authorization: Bearer <your-token>" \
  -F "customers=@/path/to/customers.csv"

Each CSV row should contain the same fields as the single-wallet creation request. TagPay processes the file asynchronously and creates wallets in the background.

The maximum recommended batch size is 500 customers per CSV upload. Split larger datasets across multiple files.

Check wallet balance

Use GET /wallet/balance to fetch your merchant settlement balance, or GET /wallet/customer to retrieve a specific customer’s wallet.

curl -X GET https://api.tagpay.ng/v1/wallet/balance \
  -H "Authorization: Bearer <your-token>"

curl -X GET "https://api.tagpay.ng/v1/wallet/customer?customerId=cus_abc123" \
  -H "Authorization: Bearer <your-token>"

curl -X GET "https://api.tagpay.ng/v1/wallet/customer/account?accountNumber=1234567890" \
  -H "Authorization: Bearer <your-token>"

To look up a wallet by account number and get detailed info:

cURL

curl -X GET "https://api.tagpay.ng/v1/wallet/info?accountNumber=1234567890" \
  -H "Authorization: Bearer <your-token>"

Credit a wallet

Use POST /wallet/credit to add funds to a customer’s wallet from your merchant settlement balance.

cURL

curl -X POST https://api.tagpay.ng/v1/wallet/credit \
  -H "Authorization: Bearer <your-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "customerId": "cus_abc123",
    "amount": 5000,
    "reference": "TXN-2026-001-CREDIT",
    "metadata": {
      "description": "Salary disbursement"
    }
  }'

Field	Type	Required	Description
`customerId`	string	Yes	The customer to credit
`amount`	number	Yes	Amount in kobo (smallest unit)
`reference`	string	No	Your unique transaction reference (min 10 chars)
`metadata`	object	No	Arbitrary key-value pairs

Debit a wallet

Use POST /wallet/debit to withdraw funds from a customer’s wallet back to your merchant settlement balance.

cURL

curl -X POST https://api.tagpay.ng/v1/wallet/debit \
  -H "Authorization: Bearer <your-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "customerId": "cus_abc123",
    "amount": 1000,
    "reference": "TXN-2026-001-DEBIT"
  }'

The request body accepts the same fields as the credit endpoint.

Batch credit and debit

To credit or debit multiple wallets in a single API call, use the batch endpoints.

Batch credit (by customer ID)

cURL

curl -X POST https://api.tagpay.ng/v1/wallet/batch-credit-customer-wallet \
  -H "Authorization: Bearer <your-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "batchReference": "BATCH-2026-04-001",
    "transactions": [
      { "customerId": "cus_abc123", "amount": 5000, "reference": "REF-001-CREDIT" },
      { "customerId": "cus_def456", "amount": 3000, "reference": "REF-002-CREDIT" }
    ]
  }'

Batch debit (by customer ID)

cURL

curl -X POST https://api.tagpay.ng/v1/wallet/batch-debit-customer-wallet \
  -H "Authorization: Bearer <your-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "batchReference": "BATCH-2026-04-002",
    "transactions": [
      { "customerId": "cus_abc123", "amount": 1000, "reference": "REF-001-DEBIT" }
    ]
  }'

You can also target wallets by wallet ID instead of customer ID:

POST /wallet/batch-credit-customer-via-wallet-id
POST /wallet/batch-debit-customer-via-wallet-id

The body structure is the same, but uses walletId in each transaction object instead of customerId.

Batch reference requirements

batchReference must be at least 10 characters
Each reference within transactions must also be at least 10 characters

To reverse a batch transaction, call POST /wallet/reverse-batch-transaction with the batchReference and a description explaining the reason for reversal.

Enable or disable a wallet

You can temporarily disable a customer’s wallet (for example, when suspicious activity is detected) and re-enable it when ready.

curl -X POST https://api.tagpay.ng/v1/wallet/close \
  -H "Authorization: Bearer <your-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "customerId": "cus_abc123",
    "reason": "Suspicious activity detected"
  }'

curl -X POST https://api.tagpay.ng/v1/wallet/enable \
  -H "Authorization: Bearer <your-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "customerId": "cus_abc123",
    "reason": "Account review complete"
  }'

Field	Type	Required	Description
`customerId`	string	Yes	The customer whose wallet to close or enable
`reason`	string	Yes	The reason for the action

Disabling a wallet prevents all credits and debits on that wallet. Customers with disabled wallets cannot send or receive funds.

List all wallets

Retrieve a paginated list of all customer wallets under your merchant account:

cURL

curl -X GET "https://api.tagpay.ng/v1/wallet?page=1&perPage=20&search=amara" \
  -H "Authorization: Bearer <your-token>"

Query param	Type	Description
`page`	number	Page number (default: 1)
`perPage`	number	Results per page (default: 20)
`search`	string	Search by name or identifier
`accountNumber`	string	Filter by 10-digit account number
`phoneNumber`	string	Filter by phone number

Get Started

Core Concepts

Guides

Prerequisites

Create a wallet

Request fields

Bulk wallet creation via CSV

Check wallet balance

Credit a wallet

Debit a wallet

Batch credit and debit

Batch credit (by customer ID)

Batch debit (by customer ID)

Batch reference requirements

Enable or disable a wallet

List all wallets

​Prerequisites

​Create a wallet

​Request fields

​Bulk wallet creation via CSV

​Check wallet balance

​Credit a wallet

​Debit a wallet

​Batch credit and debit

​Batch credit (by customer ID)

​Batch debit (by customer ID)

​Batch reference requirements

​Enable or disable a wallet

​List all wallets

Prerequisites

Create a wallet

Request fields

Bulk wallet creation via CSV

Check wallet balance

Credit a wallet

Debit a wallet

Batch credit and debit

Batch credit (by customer ID)

Batch debit (by customer ID)

Batch reference requirements

Enable or disable a wallet

List all wallets