Skip to main content

​
Overview

Every Dancity merchant account has one or more wallets (e.g., main, bonus). Your API key is tied to a specific account, so calling the wallet endpoint always returns balances for that account. Use wallet balances to:
  • Display a live balance before processing a purchase
  • Check which wallet type (wallettype) to pass in a buy request
  • Detect low-balance conditions and alert your team

​
Authentication

Wallet reads use your merchant API key only — no channel: API header is required for this endpoint. 
Authorization: Bearer dcy_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

​
Get wallets balance

GET /api/v1/wallet
Returns all wallets linked to the API key’s account, including their types and current balances.

​
Example

curl -sS "https://api.dancity.app/api/v1/wallet" \
  -H "Authorization: Bearer $DANCITY_API_KEY"

​
Sample response

{
  "success": true,
  "message": "Wallets retrieved",
  "data": [
    {
      "wallettype": "main",
      "balance": 15000.00,
      "currency": "NGN"
    },
    {
      "wallettype": "bonus",
      "balance": 250.00,
      "currency": "NGN"
    }
  ]
}

​
Using wallet types in purchases

Most buy endpoints accept an optional wallettype field. Omit it to debit your main wallet, or pass a value from GET /api/v1/wallet (e.g. "main", "bonus"). 
{
  "plan": "PLAN_ID",
  "phone": "08012345678"
}
If your balance is insufficient for the purchase amount, the API returns a 400 error with a message indicating low balance. Always check balances before bulk purchase flows.

​
Next steps