Skip to main content

​
Two credential types

SurfaceBase pathCredentialExtra headers
VAS (merchant)/api/external/v1/...dcy_live_... API keychannel: API (required) + IP allowlist
App API (wallet, transactions, …)/api/...JWT from user loginNo channel header
Do not send merchant API keys from mobile apps or browsers. Keep them on your backend.

​
Merchant API key

Every VAS (/api/external/v1) request must include: 
Authorization: Bearer dcy_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
channel: API
Your API key can spend wallet balance and purchase services on behalf of the linked account. Never expose it in client-side code, public repositories, or logs. Store it only in server-side environment variables.

​
API key format

dcy_live_<40-char-hex>
The key is shown only once after generation. Regenerating invalidates the previous key immediately.

​
Example (merchant)

curl -sS "https://api.dancity.app/api/external/v1/cable/validate?smartcardNumber=demo&cableplan=demo&cablename=demo" \
  -H "Authorization: Bearer dcy_live_xxxx..." \
  -H "channel: API"

​
The channel header (merchant only)

channel is required on /api/external/v1/* routes. For server integrations use: 
channel: API
ValueDescription
APIPartner / merchant backend
WEBWeb browser
IOS APPiOS app
ANDROID APPAndroid app
USSDUSSD channel

​
JWT (app API)

First-party routes such as GET /api/wallet/{id} expect a normal JWT issued by Dancity auth flows: 
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
No channel header is required for these calls. 
curl -sS "https://api.dancity.app/api/wallet/${DANCITY_WALLET_ID}" \
  -H "Authorization: Bearer ${DANCITY_JWT}"
Use the wallet id from your signed-in user or app state—only that user’s wallet is returned.

​
IP allowlist (merchant keys)

Restrict your API key to specific IPs or CIDR ranges from your API key page. Adding or changing entries requires OTP verification.
An empty IP allowlist blocks all traffic. Add at least one IP or CIDR before calling the VAS (merchant) API.
FormatExample
IPv4203.0.113.5
IPv62001:db8::1
IPv4 CIDR192.168.1.0/24
IPv6 CIDR2001:db8::/32
Up to 20 entries.

​
Unauthorized responses

{
  "statusCode": 401,
  "message": "Missing API key"
}
Common causes:
  • Wrong credential type (JWT vs API key) for the route
  • Missing channel: API on merchant endpoints
  • IP not allowlisted
  • Revoked or rotated API key

​
Key rotation

  1. Open the API Key page
  2. Choose Regenerate API Key
  3. Complete the email OTP
  4. Copy the new key once and update all servers
  5. Old keys stop working immediately
For runnable curl snippets, see Run & test.