Skip to main content

​
Prerequisites

  • A Dancity account with Tier 3 status
  • An approved API client (see Before you start)
  • A generated API key from your API key page
  • At least one allowlisted IP that matches the machine running these commands

​
Step 1 — Set up your credentials

Store your API key in an environment variable. Never commit it to source control. 
export DANCITY_API_KEY="dcy_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

​
Step 2 — Confirm connectivity (optional)

Wallet reads use a JWT, not your merchant key. To prove your key + IP allowlist work, call a merchant endpoint with safe placeholders (expect 400 until you substitute real catalogue values): 
curl -sS "https://api.dancity.app/api/external/v1/cable/validate?smartcardNumber=000&cableplan=000&cablename=demo" \
  -H "Authorization: Bearer $DANCITY_API_KEY" \
  -H "channel: API"
  • 401 → key, channel, or IP allowlist issue.
  • 400 / vendor message → auth is fine; swap in real smartcardNumber, cableplan, and cablename from support or your catalogue.
Check balances anytime in the Dancity app (wallet screen).

​
Step 3 — Buy airtime

curl -sS -X POST "https://api.dancity.app/api/external/v1/airtime/buy" \
  -H "Authorization: Bearer $DANCITY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "channel: API" \
  -d '{
    "product": "MTN Airtime",
    "phone": "08012345678",
    "amount": 100,
    "pin": "1234"
  }'
Response (shape): 
{
  "success": true,
  "message": "Airtime purchase processed",
  "data": {}
}
data mirrors the internal transaction record (tranxId, balances, status, etc.).

​
Step 4 — Receive webhooks (optional)

Set your webhook URL from your profile page. Dancity will POST a signed payload to that URL for transaction events. See the Webhook guide for verification instructions.

​
What’s next?

Authentication

Learn how API key auth and IP allowlists work

Run & test

Copy-paste curl recipes and env vars

Error codes

Understand every error response

OpenAPI & Try it

Technical endpoints and interactive playground