Skip to main content

​
Get customer wallet by customer ID

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

​
Request

​
Authorization
string
required
Bearer token.
​
customerId
string
required
The unique customer ID (UUID) returned when the wallet was created.

​
Response

​
status
boolean
true on success.
​
wallet
object
The customer wallet object, including tier-based transaction limits.

​
Examples

curl "https://api.tagpay.ng/v1/wallet/customer?customerId=cust_9f8e7d6c-b5a4-3210-fedc-ba0987654321" \
  -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,
    "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

​
Authorization
string
required
Bearer token.
​
accountNumber
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

​
Authorization
string
required
Bearer token.
​
accountNumber
string
required
Exactly 10-digit account number.

​
Response

​
status
boolean
true on success.
​
data
object

​
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

​
Authorization
string
required
Bearer token.
​
customerId
string
required
The customer ID whose wallet you want to close.
​
reason
string
required
Reason for closing the wallet. Stored for audit and shown if someone attempts to enable the wallet.

​
Response

​
status
boolean
true on success.
​
message
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

​
Authorization
string
required
Bearer token.
​
customerId
string
required
The customer ID whose wallet you want to activate.

​
Response

​
status
boolean
true on success.
​
message
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

​
Authorization
string
required
Bearer token.
​
customerId
string
required
The customer ID whose PIN you are setting.
​
pin
string
required
The new 4-digit PIN. Minimum 4 characters.

​
Response

​
status
boolean
true on success.
​
message
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

​
Authorization
string
required
Bearer token with elevated permissions.
​
customerId
string
required
UUID of the customer. Must be a valid UUID format.
​
reason
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

​
Authorization
string
required
Bearer token with elevated permissions.
​
customerId
string
required
UUID of the customer.
​
reason
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 StatusDescription
400Customer not found or does not belong to your merchant account
400Wallet frozen due to verification failure — BVN verification required before enabling
400Account number must be exactly 10 digits
401Missing or invalid authentication token
403Insufficient permissions for the requested operation