Skip to main content
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:
StateDescription
ActiveThe wallet is open and can send and receive funds normally.
ClosedThe wallet is permanently shut. No credits or debits are permitted.
BlockedThe 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.
FieldRequiredDescription
firstNameYesCustomer’s first name
lastNameYesCustomer’s last name
phoneNumberYesCustomer’s phone number
dateOfBirthYesDate of birth in YYYY-MM-DD format
emailNoCustomer’s email address
bvnConditional11-digit Bank Verification Number
ninConditional11-digit National Identification Number
tierNoWallet tier: TIER_1, TIER_2, or TIER_3 (default: TIER_1)
currencyNoCurrency code — only NGN is supported
customerIdNoYour own identifier for the customer
metadataNoArbitrary 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:
BalanceDescription
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:
EndpointDescription
POST /wallet/batch-credit-customer-walletCredit multiple wallets by customerId
POST /wallet/batch-debit-customer-walletDebit multiple wallets by customerId
POST /wallet/batch-credit-customer-via-wallet-idCredit multiple wallets by wallet ID
POST /wallet/batch-debit-customer-via-wallet-idDebit 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 typeDescriptionEndpoint
Wallet transferInstant transfer to another TagPay wallet by account numberCustomer-initiated via /customer/transfer/phone or bulk CSV
Bank transferNIP transfer to any Nigerian bank accountCustomer-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