Fund & Debit

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

string

required

Bearer token.

string

required

The UUID of the customer whose wallet you are crediting.

number

required

Amount to credit, in kobo. Must be greater than 0.

string

Your unique transaction reference. If omitted, one is auto-generated. Minimum 10 characters. Duplicate references are rejected.

object

Arbitrary key-value data attached to the transaction. Returned in webhook payloads.

Response

boolean

true on success.

string

"Transaction successfully completed." or "Transaction successfully submitted for approval." (for web-initiated requests that require maker-checker approval).

object

Present on successful API-initiated transactions.

Show data properties

number

Amount credited to the customer wallet in kobo.

string

Transaction reference.

string

Customer UUID.

string

Customer wallet UUID.

number

Fee charged to the merchant for this transfer, in kobo.

object

Your metadata if provided.

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

const response = await fetch("https://api.tagpay.ng/v1/wallet/credit", {
  method: "POST",
  headers: {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    customerId: "cust_9f8e7d6c-b5a4-3210-fedc-ba0987654321",
    amount: 500000,
    reference: "REF-CREDIT-20240501-001",
    metadata: { orderId: "ORD-999" },
  }),
});

const data = await response.json();

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

string

required

Bearer token.

string

required

The UUID of the customer whose wallet you are debiting.

number

required

Amount to debit, in kobo. Must be greater than 0.

string

Your unique transaction reference. Minimum 10 characters. Duplicate references are rejected.

object

Arbitrary key-value data attached to the transaction.

Response

boolean

true on success.

string

"Transaction successfully completed" on success.

object

Show data properties

number

Amount debited from the customer wallet in kobo.

string

Transaction reference.

string

Customer UUID.

string

Customer wallet UUID.

number

Fee deducted from the debited amount before crediting the merchant wallet.

object

Your metadata if provided.

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

const response = await fetch("https://api.tagpay.ng/v1/wallet/debit", {
  method: "POST",
  headers: {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    customerId: "cust_9f8e7d6c-b5a4-3210-fedc-ba0987654321",
    amount: 200000,
    reference: "REF-DEBIT-20240501-001",
  }),
});

const data = await response.json();

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

string

required

Bearer token.

Response

boolean

true on success.

object

Show data properties

number

Total available balance across all customer wallets, in kobo.

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

string

required

Bearer token. Requires MANAGE_BALANCE_SETTLEMENT permission.

Response

boolean

true on success.

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

string

required

Bearer token. Requires MANAGE_BALANCE_SETTLEMENT permission.

Response

boolean

true on success.

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 Status	Description
`400`	Reference already exists
`400`	Insufficient balance in merchant or customer wallet
`400`	Customer wallet is inactive or not found
`400`	Post-no-credit is enabled on beneficiary wallet
`400`	Daily transaction limit exceeded
`400`	Tier max balance would be exceeded
`400`	Customer debit not enabled for this merchant
`401`	Missing or invalid authentication token
`403`	Insufficient 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."
}

Wallets

Transfers

Transactions

Webhooks

Credit a customer wallet

Request

Response

Examples

Debit a customer wallet

Request

Response

Examples

Get merchant wallet balances

Request

Response

Examples

Get settlement balance

Request

Response

Examples

Settle customer balances

Request

Response

Examples

Error responses

​Credit a customer wallet

​Request

​Response

​Examples

​Debit a customer wallet

​Request

​Response

​Examples

​Get merchant wallet balances

​Request

​Response

​Examples

​Get settlement balance

​Request

​Response

​Examples

​Settle customer balances

​Request

​Response

​Examples

​Error responses

Credit a customer wallet

Request

Response

Examples

Debit a customer wallet

Request

Response

Examples

Get merchant wallet balances

Request

Response

Examples

Get settlement balance

Request

Response

Examples

Settle customer balances

Request

Response

Examples

Error responses