> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dancity.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Airtime & data

> Top up a phone number with airtime or a mobile data bundle

## 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](https://docs.dancity.app/guides/catalog.md)
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.

```http theme={null}
Authorization: Bearer dcy_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
channel: API
```

***

## Buy airtime

```
POST /api/v1/airtime/buy
```

### Request body

| Field | Type | Required | Description |
| - | - | - | - |
| `product` | string | ✓ | Product name from catalog (e.g. `"MTN Airtime"`). Hyphens and underscores work as spaces — `"MTN-Airtime"` and `"MTN_Airtime"` are equivalent. |
| `phone` | string | ✓ | 11-digit Nigerian phone number |
| `amount` | number | ✓ | Amount in NGN (₦50 – ₦1,000) |
| `customerRef` | string | | Your internal reference ID |
| `saveAsBeneficiary` | boolean | | Save phone as beneficiary |
| `beneficiaryName` | string | | Label for saved beneficiary |
| `promocode` | string | | Discount promo code |

```bash cURL theme={null}
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
  }'
```

```javascript Node.js theme={null}
const res = await fetch("https://api.dancity.app/api/v1/airtime/buy", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.DANCITY_API_KEY}`,
    "Content-Type": "application/json",
    channel: "API",
  },
  body: JSON.stringify({
    product: "MTN Airtime",
    phone: "08012345678",
    amount: 200,
  }),
});
const data = await res.json();
```

```python Python theme={null}
import requests, os

res = requests.post(
    "https://api.dancity.app/api/v1/airtime/buy",
    headers={
        "Authorization": f"Bearer {os.environ['DANCITY_API_KEY']}",
        "Content-Type": "application/json",
        "channel": "API",
    },
    json={
        "product": "MTN Airtime",
        "phone": "08012345678",
        "amount": 200,
    },
)
print(res.json())
```

### Sample response

```json theme={null}
{
  "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

| Field | Type | Required | Description |
| - | - | - | - |
| `plan` | string | ✓ | Plan `planId` or `_id` from `GET /api/v1/plans/data` |
| `phone` | string | ✓ | 11-digit Nigerian phone number |
| `wallettype` | string | | Wallet to debit. Defaults to `main` when omitted. |
| `customerRef` | string | | Your internal reference ID |
| `saveAsBeneficiary` | boolean | | Save phone as beneficiary |
| `promocode` | string | | Discount promo code |

```bash cURL theme={null}
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"
  }'
```

```javascript Node.js theme={null}
const res = await fetch("https://api.dancity.app/api/v1/data/buy", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.DANCITY_API_KEY}`,
    "Content-Type": "application/json",
    channel: "API",
  },
  body: JSON.stringify({
    plan: "64f1a2b3c4d5e6f7a8b9c0d1", // from GET /plans/data
    phone: "08012345678",
  }),
});
const data = await res.json();
```

```python Python theme={null}
import requests, os

res = requests.post(
    "https://api.dancity.app/api/v1/data/buy",
    headers={
        "Authorization": f"Bearer {os.environ['DANCITY_API_KEY']}",
        "Content-Type": "application/json",
        "channel": "API",
    },
    json={
        "plan": "64f1a2b3c4d5e6f7a8b9c0d1",
        "phone": "08012345678",
    },
)
print(res.json())
```

***

## 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)
```

> [!TIP]
>
> 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.

> [!WARNING]
>
> The airtime `amount` is capped at **₦1,000 per transaction**. For larger top-ups, split into multiple requests.

## Next steps

* [Catalog: browse services and plans](https://docs.dancity.app/guides/catalog.md)
* [Transactions: requery a purchase](https://docs.dancity.app/guides/transactions.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.