Skip to main content

​
Overview

The airtime and data endpoints let you recharge any Nigerian phone number directly from your Dancity wallet. Both follow the same pattern:
  1. Fetch the product/plan from the catalog
  2. Call the buy endpoint with the product name or plan ID

​
Authentication

Both endpoints require your merchant API key and the channel: API header. 
Authorization: Bearer dcy_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
channel: API

​
Buy airtime

POST /api/v1/airtime/buy

​
Request body

FieldTypeRequiredDescription
productstring✓Product name from catalog (e.g. "MTN Airtime"). Hyphens and underscores work as spaces — "MTN-Airtime" and "MTN_Airtime" are equivalent.
phonestring✓11-digit Nigerian phone number
amountnumber✓Amount in NGN (₦50 – ₦1,000)
customerRefstringYour internal reference ID
saveAsBeneficiarybooleanSave phone as beneficiary
beneficiaryNamestringLabel for saved beneficiary
promocodestringDiscount promo code
curl -sS -X POST "https://api.dancity.app/api/v1/airtime/buy" \
  -H "Authorization: Bearer $DANCITY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "channel: API" \
  -d '{
    "product": "MTN Airtime",
    "phone": "08012345678",
    "amount": 200
  }'

​
Sample response

{
  "success": true,
  "message": "Airtime purchase processed",
  "data": {
    "_id": "6a1c3ba6f269d84e04f098cc",
    "tranxId": "DNTY174825YP565I",
    "service": "AIRTIME",
    "product": "MTN Airtime",
    "status": "FAILED",
    "amount": 100,
    "amountPaid": 98.5,
    "number": "09037346247",
    "balanceBefore": 5276,
    "balanceAfter": 5177.5,
    "apiResponse": "Airtime purchase failed"
  }
}
amount is the airtime value you requested. amountPaid is what was debited from the wallet (after any group discount).

​
Purchase Data

POST /api/v1/data/buy

​
Request body

FieldTypeRequiredDescription
planstring✓Plan planId or _id from GET /api/v1/plans/data
phonestring✓11-digit Nigerian phone number
wallettypestringWallet to debit. Defaults to main when omitted.
customerRefstringYour internal reference ID
saveAsBeneficiarybooleanSave phone as beneficiary
promocodestringDiscount promo code
curl -sS -X POST "https://api.dancity.app/api/v1/data/buy" \
  -H "Authorization: Bearer $DANCITY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "channel: API" \
  -d '{
    "plan": "64f1a2b3c4d5e6f7a8b9c0d1",
    "phone": "08012345678"
  }'

​
Full purchase flow

1. GET /api/v1/products?service=Data
   → pick your product (e.g., "MTN Data")

2. GET /api/v1/plans/data?product=MTN%20Data
   → pick a plan, note its _id

3. GET /api/v1/wallet
   → confirm sufficient balance

4. POST /api/v1/data/buy
   → send plan and phone (API key authenticates the request)
Save data.tranxId from the response — use it with GET /api/v1/transactions/{transactionId} to requery the status if the response is slow or unclear.
The airtime amount is capped at ₦1,000 per transaction. For larger top-ups, split into multiple requests.

​
Next steps