Create Wallet

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

string

required

Bearer token for your merchant account. Format: Bearer <token>

string

required

Customer’s first name. Must match the name on file with the BVN/NIN provider for verification to succeed.

string

required

Customer’s last name.

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.

string

required

Customer’s date of birth in YYYY-MM-DD format.

string

Customer’s Bank Verification Number (BVN). Exactly 11 digits, numbers only. Either bvn or nin is required.

string

Customer’s National Identification Number (NIN). Exactly 11 digits, numbers only. Either bvn or nin is required.

string

Customer’s email address. If omitted, a placeholder email derived from the phone number is generated automatically.

string

Customer’s physical address.

string

default:"NGN"

Wallet currency. Currently only NGN is supported.

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.

string

If provided, the wallet reservation charge is debited from this existing customer’s wallet rather than from your merchant settlement wallet.

object

Arbitrary key-value data you want to attach to the wallet. Returned in webhook payloads.

string

Optional password for the customer account. Minimum 6 characters.

Response

boolean

true when the request succeeded.

object

The newly created wallet object.

Show wallet properties

string

Unique wallet ID (UUID).

string

10-digit virtual account number assigned to this wallet.

string

Account name displayed on transfers — typically the customer’s full name.

string

Name of the partner bank that issued the virtual account.

string

Sort code of the issuing bank.

string

Wallet currency (NGN).

string

Wallet status: ACTIVE or FROZEN.

string

Internal account reference assigned by the issuing bank.

object

The customer record created alongside the wallet.

Show customer properties

string

Unique customer ID (UUID). Use this as customerId in future wallet and transfer operations.

string

Customer’s first name.

string

Customer’s last name.

string

Normalized phone number in E.164 format.

string

Customer email address.

string

Assigned wallet tier (TIER_1, TIER_2, or TIER_3).

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"
  }'

const response = await fetch("https://api.tagpay.ng/v1/wallet", {
  method: "POST",
  headers: {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    firstName: "Amaka",
    lastName: "Okonkwo",
    phoneNumber: "08031234567",
    dateOfBirth: "1990-05-14",
    bvn: "12345678901",
    email: "[email protected]",
    tier: "TIER_1",
  }),
});

const data = await response.json();

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

string

required

Bearer token.

number

default:"1"

Page number for pagination. Must be a positive integer.

number

default:"20"

Number of records per page. Must be a positive integer.

string

Filter by account name (partial match, case-insensitive).

string

Filter by an exact 10-digit account number. When provided, returns matching wallets directly without standard pagination.

string

Filter by customer phone number (partial match).

Response

boolean

true on success.

array

Array of wallet objects.

object

Pagination metadata.

Show metadata properties

number

Current page number.

number

Total number of customer records matching the query.

number

Total number of pages.

Examples

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

curl "https://api.tagpay.ng/v1/wallet?page=1&perPage=50&search=Amaka" \
  -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 Status	Description
`400`	Validation error — missing required fields or invalid format
`400`	BVN or NIN not provided
`400`	Phone number, BVN, or NIN already registered for this merchant
`400`	Insufficient balance for wallet reservation charge
`401`	Missing or invalid authentication token
`403`	API key lacks `CREATE_CUSTOMER_WALLET` permission

400 Bad Request

{
  "status": false,
  "message": "Please provided either NIN or BVN"
}

Wallets

Transfers

Transactions

Webhooks

Create a wallet

Request

Response

Examples

List wallets

Request

Response

Examples

Error responses

​Create a wallet

​Request

​Response

​Examples

​List wallets

​Request

​Response

​Examples

​Error responses

Create a wallet

Request

Response

Examples

List wallets

Request

Response

Examples

Error responses