Skip to main content

​
Credit a customer wallet

POST /wallet/credit Transfers funds from your merchant settlement wallet to a customer wallet. The merchant wallet is debited the transfer amount plus any applicable wallet-to-wallet transfer fees.
The customer wallet must be ACTIVE and must not have post-no-credit (PNC) mode enabled. Credits are also subject to the customer’s tier maximum balance limit — if the credit would push the wallet over its tier cap, the request is rejected.

​
Request

​
Authorization
string
required
Bearer token.
​
customerId
string
required
The UUID of the customer whose wallet you are crediting.
​
amount
number
required
Amount to credit, in kobo. Must be greater than 0.
​
reference
string
Your unique transaction reference. If omitted, one is auto-generated. Minimum 10 characters. Duplicate references are rejected.
​
metadata
object
Arbitrary key-value data attached to the transaction. Returned in webhook payloads.

​
Response

​
status
boolean
true on success.
​
message
string
"Transaction successfully completed." or "Transaction successfully submitted for approval." (for web-initiated requests that require maker-checker approval).
​
data
object
Present on successful API-initiated transactions.

​
Examples

curl -X POST https://api.tagpay.ng/v1/wallet/credit \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "customerId": "cust_9f8e7d6c-b5a4-3210-fedc-ba0987654321",
    "amount": 500000,
    "reference": "REF-CREDIT-20240501-001",
    "metadata": { "orderId": "ORD-999" }
  }'
Response
{
  "status": true,
  "message": "Transaction successfully completed.",
  "data": {
    "amount": 500000,
    "reference": "REF-CREDIT-20240501-001",
    "customer_id": "cust_9f8e7d6c-b5a4-3210-fedc-ba0987654321",
    "customer_wallet_id": "wlt_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "transaction_fee": 0,
    "metadata": { "orderId": "ORD-999" }
  }
}

​
Debit a customer wallet

POST /wallet/debit Withdraws funds from a customer wallet and credits them to your merchant settlement wallet. The net amount received by the merchant is the debited amount minus any applicable transfer fees.
Customer debit must be explicitly enabled on your merchant account. If canDebitCustomer is false, all debit requests return an error. Contact TagPay support to enable this feature.

​
Request

​
Authorization
string
required
Bearer token.
​
customerId
string
required
The UUID of the customer whose wallet you are debiting.
​
amount
number
required
Amount to debit, in kobo. Must be greater than 0.
​
reference
string
Your unique transaction reference. Minimum 10 characters. Duplicate references are rejected.
​
metadata
object
Arbitrary key-value data attached to the transaction.

​
Response

​
status
boolean
true on success.
​
message
string
"Transaction successfully completed" on success.
​
data
object

​
Examples

curl -X POST https://api.tagpay.ng/v1/wallet/debit \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "customerId": "cust_9f8e7d6c-b5a4-3210-fedc-ba0987654321",
    "amount": 200000,
    "reference": "REF-DEBIT-20240501-001"
  }'
Response
{
  "status": true,
  "message": "Transaction successfully completed",
  "data": {
    "amount": 200000,
    "reference": "REF-DEBIT-20240501-001",
    "customer_id": "cust_9f8e7d6c-b5a4-3210-fedc-ba0987654321",
    "customer_wallet_id": "wlt_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "transaction_fee": 0,
    "metadata": null
  }
}

​
Get merchant wallet balances

GET /wallet/balance Returns the total combined balance across all customer wallets under your merchant account. This is the sum of availableBalance for every customer wallet.

​
Request

​
Authorization
string
required
Bearer token.

​
Response

​
status
boolean
true on success.
​
data
object

​
Examples

curl "https://api.tagpay.ng/v1/wallet/balance" \
  -H "Authorization: Bearer <token>"
Response
{
  "status": true,
  "data": {
    "totalBalance": 4750000
  }
}

​
Get settlement balance

GET /wallet/settlement-balance Returns the total unsettled balance owed to customers — the difference between bookedBalance and availableBalance across all customer wallets. Use this before calling POST /wallet/settle-customer-balance to understand how much you need to fund.

​
Request

​
Authorization
string
required
Bearer token. Requires MANAGE_BALANCE_SETTLEMENT permission.

​
Response

​
status
boolean
true on success.
​
balance
number
Total pending settlement amount in kobo.

​
Examples

curl "https://api.tagpay.ng/v1/wallet/settlement-balance" \
  -H "Authorization: Bearer <token>"
Response
{
  "status": true,
  "balance": 850000
}

​
Settle customer balances

POST /wallet/settle-customer-balance Transfers funds from your merchant settlement wallet to cover the outstanding balances of all customers who have a bookedBalance greater than their availableBalance. Settlement is processed smallest-balance-first until your merchant wallet is exhausted.
This is an irreversible batch operation. Ensure your merchant wallet has sufficient funds before calling this endpoint. Check the settlement balance first using GET /wallet/settlement-balance.

​
Request

​
Authorization
string
required
Bearer token. Requires MANAGE_BALANCE_SETTLEMENT permission.

​
Response

​
status
boolean
true on success.
​
message
string
"Your customers wallet has been settled"

​
Examples

curl -X POST https://api.tagpay.ng/v1/wallet/settle-customer-balance \
  -H "Authorization: Bearer <token>"
Response
{
  "status": true,
  "message": "Your customers wallet has been settled"
}

​
Error responses

HTTP StatusDescription
400Reference already exists
400Insufficient balance in merchant or customer wallet
400Customer wallet is inactive or not found
400Post-no-credit is enabled on beneficiary wallet
400Daily transaction limit exceeded
400Tier max balance would be exceeded
400Customer debit not enabled for this merchant
401Missing or invalid authentication token
403Insufficient permissions
400 Insufficient Balance
{
  "status": false,
  "message": "Insufficient balance to complete this transaction"
}
400 Post-No-Credit Enabled
{
  "status": false,
  "message": "Post no credit has been enabled on the beneficiary account. Kindly reachout to support for help."
}