Manage Wallets

Get customer wallet by customer ID

GET /wallet/customer Retrieves the wallet and transaction limit details for a single customer using their customerId.

Request

string

required

Bearer token.

string

required

The unique customer ID (UUID) returned when the wallet was created.

Response

boolean

true on success.

object

The customer wallet object, including tier-based transaction limits.

Show wallet properties

string

Wallet ID.

string

10-digit virtual account number.

string

Account holder name.

number

Spendable wallet balance in kobo.

string

ACTIVE or FROZEN.

string

Customer tier: TIER_1, TIER_2, or TIER_3.

number

Tier-specific daily transaction limit configured on your merchant account.

number

Tier-specific minimum balance requirement.

boolean

Whether NIN verification has been completed.

boolean

Whether BVN verification is still pending for this wallet.

Examples

curl "https://api.tagpay.ng/v1/wallet/customer?customerId=cust_9f8e7d6c-b5a4-3210-fedc-ba0987654321" \
  -H "Authorization: Bearer <token>"

const response = await fetch(
  "https://api.tagpay.ng/v1/wallet/customer?customerId=cust_9f8e7d6c-b5a4-3210-fedc-ba0987654321",
  { headers: { Authorization: "Bearer <token>" } }
);
const data = await response.json();

Response

{
  "status": true,
  "wallet": {
    "id": "wlt_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "accountNumber": "0123456789",
    "accountName": "Amaka Okonkwo",
    "availableBalance": 15000,
    "status": "ACTIVE",
    "tier": "TIER_1",
    "dailyLimit": 50000,
    "minBalance": 0,
    "isNINVerified": false,
    "isBVNVerificationRequired": false
  }
}

Get customer wallet by account number

GET /wallet/customer/account Retrieves a customer wallet using a 10-digit virtual account number. The account must belong to a customer under your merchant account.

Request

string

required

Bearer token.

string

required

Exactly 10-digit virtual account number.

Examples

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

Response

{
  "status": true,
  "wallet": {
    "id": "wlt_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "accountNumber": "0123456789",
    "accountName": "Amaka Okonkwo",
    "availableBalance": 15000,
    "status": "ACTIVE",
    "tier": "TIER_1",
    "dailyLimit": 50000,
    "minBalance": 0,
    "merchantId": "merch_abc123"
  }
}

Get wallet info by account number

GET /wallet/info Returns basic wallet information for any account number that belongs to your merchant (customer or merchant wallet). Unlike /wallet/customer/account, this endpoint returns a minimal object without customer-level details.

Request

string

required

Bearer token.

string

required

Exactly 10-digit account number.

Response

boolean

true on success.

object

Show data properties

string

Wallet ID.

string

ACTIVE or FROZEN.

string

Email associated with the wallet.

string

Account holder name.

number

Available balance in kobo.

string

ISO 8601 timestamp of wallet creation.

Examples

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

Response

{
  "status": true,
  "data": {
    "id": "wlt_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "status": "ACTIVE",
    "email": "[email protected]",
    "accountName": "Amaka Okonkwo",
    "availableBalance": 15000,
    "createdAt": "2024-05-01T10:30:00.000Z"
  }
}

Close a wallet

POST /wallet/close Freezes a customer wallet, preventing any further transactions. Provide a reason for audit purposes. The wallet remains frozen until you explicitly re-enable it with POST /wallet/enable.

Request

string

required

Bearer token.

string

required

The customer ID whose wallet you want to close.

string

required

Reason for closing the wallet. Stored for audit and shown if someone attempts to enable the wallet.

Response

boolean

true on success.

string

Confirmation message: "Customer wallet successfully frozen."

Examples

curl -X POST https://api.tagpay.ng/v1/wallet/close \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "customerId": "cust_9f8e7d6c-b5a4-3210-fedc-ba0987654321",
    "reason": "Suspicious activity reported"
  }'

Response

{
  "status": true,
  "message": "Customer wallet successfully frozen."
}

Enable a wallet

POST /wallet/enable Re-activates a previously frozen wallet. If the wallet was frozen due to BVN/NIN verification failure and BVN verification is still pending, the request is rejected until verification is resolved.

If the wallet was frozen because of a failed identity check (reason: "Invalid NIN/BVN", "BVN Lookup failed", etc.), you must complete BVN verification before re-enabling. Contact TagPay support to trigger re-verification.

Request

string

required

Bearer token.

string

required

The customer ID whose wallet you want to activate.

Response

boolean

true on success.

string

Confirmation message: "Customer wallet successfully activated."

Examples

curl -X POST https://api.tagpay.ng/v1/wallet/enable \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "customerId": "cust_9f8e7d6c-b5a4-3210-fedc-ba0987654321"
  }'

Response

{
  "status": true,
  "message": "Customer wallet successfully activated."
}

Set transaction PIN

PUT /wallet/transaction-pin Sets or updates the 4-digit transaction PIN for a customer wallet. The PIN is required by certain debit flows.

Request

string

required

Bearer token.

string

required

The customer ID whose PIN you are setting.

string

required

The new 4-digit PIN. Minimum 4 characters.

Response

boolean

true on success.

string

"Wallet transaction PIN successfully set."

Examples

curl -X PUT https://api.tagpay.ng/v1/wallet/transaction-pin \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "customerId": "cust_9f8e7d6c-b5a4-3210-fedc-ba0987654321",
    "pin": "1234"
  }'

Response

{
  "status": true,
  "message": "Wallet transaction PIN successfully set."
}

Enable post-no-credit mode

POST /wallet/enable-post-no-credit Enables post-no-credit (PNC) mode on a customer wallet. When PNC is active, any credits to that wallet — including from batch operations — are silently rejected with an error. Use this to block a wallet from receiving funds without fully freezing it.

This endpoint requires MainMerchant or Admin role. Standard API keys cannot call this endpoint.

Request

string

required

Bearer token with elevated permissions.

string

required

UUID of the customer. Must be a valid UUID format.

string

Optional reason for enabling PNC mode.

Examples

curl -X POST https://api.tagpay.ng/v1/wallet/enable-post-no-credit \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "customerId": "cust_9f8e7d6c-b5a4-3210-fedc-ba0987654321",
    "reason": "Credit block per customer request"
  }'

Response

{
  "status": true,
  "message": "Post no credit successfully enabled."
}

Disable post-no-credit mode

POST /wallet/disable-post-no-credit Removes the post-no-credit restriction from a customer wallet, allowing the wallet to receive credits again.

Requires MainMerchant or Admin role.

Request

string

required

Bearer token with elevated permissions.

string

required

UUID of the customer.

string

Optional reason for disabling PNC mode.

Examples

curl -X POST https://api.tagpay.ng/v1/wallet/disable-post-no-credit \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "customerId": "cust_9f8e7d6c-b5a4-3210-fedc-ba0987654321"
  }'

Response

{
  "status": true,
  "message": "Post no credit successfully disabled."
}

Error responses

HTTP Status	Description
`400`	Customer not found or does not belong to your merchant account
`400`	Wallet frozen due to verification failure — BVN verification required before enabling
`400`	Account number must be exactly 10 digits
`401`	Missing or invalid authentication token
`403`	Insufficient permissions for the requested operation

Wallets

Transfers

Transactions

Webhooks

Get customer wallet by customer ID

Request

Response

Examples

Get customer wallet by account number

Request

Examples

Get wallet info by account number

Request

Response

Examples

Close a wallet

Request

Response

Examples

Enable a wallet

Request

Response

Examples

Set transaction PIN

Request

Response

Examples

Enable post-no-credit mode

Request

Examples

Disable post-no-credit mode

Request

Examples

Error responses

​Get customer wallet by customer ID

​Request

​Response

​Examples

​Get customer wallet by account number

​Request

​Examples

​Get wallet info by account number

​Request

​Response

​Examples

​Close a wallet

​Request

​Response

​Examples

​Enable a wallet

​Request

​Response

​Examples

​Set transaction PIN

​Request

​Response

​Examples

​Enable post-no-credit mode

​Request

​Examples

​Disable post-no-credit mode

​Request

​Examples

​Error responses

Get customer wallet by customer ID

Request

Response

Examples

Get customer wallet by account number

Request

Examples

Get wallet info by account number

Request

Response

Examples

Close a wallet

Request

Response

Examples

Enable a wallet

Request

Response

Examples

Set transaction PIN

Request

Response

Examples

Enable post-no-credit mode

Request

Examples

Disable post-no-credit mode

Request

Examples

Error responses