Skip to main content

​
Create a wallet

You must have either a BVN or NIN — or both — to create a wallet. Wallets created without verified identity documents are frozen until verification is completed.
POST /wallet Creates a new customer wallet and assigns a dedicated virtual account number. The merchant’s settlement wallet is debited a reservation charge upon creation. If BVN or NIN verification succeeds, the wallet is activated immediately with status: "ACTIVE". If verification fails, the wallet is created but frozen with status: "FROZEN".

​
Request

​
Authorization
string
required
Bearer token for your merchant account. Format: Bearer <token>
​
firstName
string
required
Customer’s first name. Must match the name on file with the BVN/NIN provider for verification to succeed.
​
lastName
string
required
Customer’s last name.
​
phoneNumber
string
required
Customer’s phone number. Must be unique across your merchant account (unless phone uniqueness checking is disabled). Accepts formats like 08012345678 or +2348012345678.
​
dateOfBirth
string
required
Customer’s date of birth in YYYY-MM-DD format.
​
bvn
string
Customer’s Bank Verification Number (BVN). Exactly 11 digits, numbers only. Either bvn or nin is required.
​
nin
string
Customer’s National Identification Number (NIN). Exactly 11 digits, numbers only. Either bvn or nin is required.
​
email
string
Customer’s email address. If omitted, a placeholder email derived from the phone number is generated automatically.
​
address
string
Customer’s physical address.
​
currency
string
default:"NGN"
Wallet currency. Currently only NGN is supported.
​
tier
string
default:"TIER_1"
Requested wallet tier. One of TIER_1, TIER_2, or TIER_3. The actual assigned tier depends on successful verification — wallets requiring dual BVN and NIN verification may be downgraded to TIER_1 if either check fails.
​
customerId
string
If provided, the wallet reservation charge is debited from this existing customer’s wallet rather than from your merchant settlement wallet.
​
metadata
object
Arbitrary key-value data you want to attach to the wallet. Returned in webhook payloads.
​
password
string
Optional password for the customer account. Minimum 6 characters.

​
Response

​
status
boolean
true when the request succeeded.
​
wallet
object
The newly created wallet object.
​
customer
object
The customer record created alongside the wallet.

​
Examples

curl -X POST https://api.tagpay.ng/v1/wallet \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "Amaka",
    "lastName": "Okonkwo",
    "phoneNumber": "08031234567",
    "dateOfBirth": "1990-05-14",
    "bvn": "12345678901",
    "email": "[email protected]",
    "tier": "TIER_1"
  }'
Response (201 Created)
{
  "status": true,
  "wallet": {
    "id": "wlt_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "accountNumber": "0123456789",
    "accountName": "Amaka Okonkwo",
    "bankName": "Providus Bank",
    "bankCode": "101",
    "currency": "NGN",
    "status": "ACTIVE",
    "accountReference": "REF-20240501-001"
  },
  "customer": {
    "id": "cust_9f8e7d6c-b5a4-3210-fedc-ba0987654321",
    "firstName": "Amaka",
    "lastName": "Okonkwo",
    "phoneNumber": "+2348031234567",
    "email": "[email protected]",
    "tier": "TIER_1"
  }
}

​
List wallets

GET /wallet Returns a paginated list of all customer wallets for your merchant account, ordered by creation date (newest first).

​
Request

​
Authorization
string
required
Bearer token.
​
page
number
default:"1"
Page number for pagination. Must be a positive integer.
​
perPage
number
default:"20"
Number of records per page. Must be a positive integer.
​
search
string
Filter by account name (partial match, case-insensitive).
​
accountNumber
string
Filter by an exact 10-digit account number. When provided, returns matching wallets directly without standard pagination.
​
phoneNumber
string
Filter by customer phone number (partial match).

​
Response

​
status
boolean
true on success.
​
wallets
array
Array of wallet objects.
​
metadata
object
Pagination metadata.

​
Examples

curl "https://api.tagpay.ng/v1/wallet?page=1&perPage=20" \
  -H "Authorization: Bearer <token>"
Response
{
  "status": true,
  "wallets": [
    {
      "id": "wlt_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "accountNumber": "0123456789",
      "accountName": "Amaka Okonkwo",
      "availableBalance": 15000,
      "status": "ACTIVE",
      "currency": "NGN",
      "customerId": "cust_9f8e7d6c-b5a4-3210-fedc-ba0987654321",
      "tier": "TIER_1"
    }
  ],
  "metadata": {
    "page": 1,
    "totalRecords": 1,
    "totalPages": 1
  }
}

​
Error responses

HTTP StatusDescription
400Validation error — missing required fields or invalid format
400BVN or NIN not provided
400Phone number, BVN, or NIN already registered for this merchant
400Insufficient balance for wallet reservation charge
401Missing or invalid authentication token
403API key lacks CREATE_CUSTOMER_WALLET permission
400 Bad Request
{
  "status": false,
  "message": "Please provided either NIN or BVN"
}