# Airtime (/docs/products/airtime)

## What you can sell [#what-you-can-sell]

Airtime is a mobile top-up for one phone number. An operator is one mobile operator in one country, and it lists offers:

- **Fixed offers** deliver a set amount, such as 40 AZN.
- **Range offers** deliver the amount you choose within a minimum, a maximum and a step, such as 10 to 200 AZN.

Each item tops up one number once, so `quantity` is always 1. Prices are in your order currency, while the delivered value is in the operator's currency.

## The flow [#the-flow]

There are two ways to find an offer. Both end in the same quote and order.

**Detected flow.** Give OpenRoam the recipient's number, and it finds the operator and its offers.

1. [`GET /v1/airtime/search?phoneNumber=`](/docs/api-reference/airtime/search) returns the detected operator with its offers.

**Manual flow.** Use this when search finds no operator, or when you want your customer to choose.

1. [`GET /v1/airtime/operators?countryCode=`](/docs/api-reference/airtime/get-operators) lists the operators of a country, without offers.
2. [`GET /v1/airtime/operators/{id}?phoneNumber=`](/docs/api-reference/airtime/get-operator) returns the chosen operator with its offers, in the shape search returns.

**Then, in both flows:**

3. [`POST /v1/airtime/quote`](/docs/api-reference/airtime/quote) prices an order body. It has no side effects.
4. [`POST /v1/airtime/order`](/docs/api-reference/airtime/create-order) places the order. It needs an `Idempotency-Key` header and an API key with the `manage` permission.

Other routes:

- [`GET /v1/airtime/number-lookup?phoneNumber=`](/docs/api-reference/airtime/lookup-number) describes a number: validity, country, calling code, formats and line type, plus the network name OpenRoam finds for it. Nothing is stored.
- [`GET /v1/airtime/catalog`](/docs/api-reference/airtime/catalog) is the operator directory, page by page with a cursor, as summaries without offers. Filter with `countryCode`, page with `limit` (1 to 100) and `cursor`.

Phone numbers are always in international format: a leading `+` or `00`, with optional spaces, hyphens and parentheses. National numbers and bare digits are rejected. The country comes from the number.

Unknown query parameters are rejected with `400 / 10001` (`UNSUPPORTED_FIELD`).

See [Orders](/docs/orders) for order and item status, and [Idempotency](/docs/idempotency) for retries.

## Search [#search]

```bash
curl "https://api.sandbox.openroam.com/v1/airtime/search?phoneNumber=%2B994501234567" \
  -H "X-Partner-Key: $OPENROAM_API_KEY"
```

```json
{
  "items": [
    {
      "id": "operator_tq7vbm2xk4hdn6wzr3pyjc5fae",
      "name": "Example Mobile",
      "countryCode": "AZ",
      "category": null,
      "logoUrl": "https://example.com/airtime/example-mobile.png",
      "description": null,
      "offers": [
        {
          "publicId": "airtime_raanuxyz6cxzie3w3my6c3r2wm",
          "name": "Example Mobile 40 AZN",
          "description": "Top-up for **Example Mobile** numbers.",
          "value": { "type": "fixed", "amount": 40, "currency": "AZN" },
          "price": { "amount": 25.00, "currency": "USD" },
          "requiredInputs": [
            { "name": "phoneNumber", "type": "phone", "required": true, "description": "The recipient's mobile number in international format, starting with + or 00." }
          ],
          "details": { "redemptionType": "directTopUp", "readMore": "Credit arrives within minutes." }
        },
        {
          "publicId": "airtime_ms45o6lwxtqgrsculqdhop74zq",
          "name": "Example Mobile 10 - 200 AZN",
          "description": "Top-up for **Example Mobile** numbers.",
          "value": { "type": "range", "min": 10, "max": 200, "step": 0.01, "currency": "AZN" },
          "price": { "min": 6.25, "max": 125.00, "currency": "USD" },
          "requiredInputs": [
            { "name": "phoneNumber", "type": "phone", "required": true, "description": "The recipient's mobile number in international format, starting with + or 00." }
          ],
          "details": { "redemptionType": "directTopUp", "readMore": "Credit arrives within minutes." }
        }
      ]
    }
  ],
  "pagination": { "currentCount": 1, "totalCount": 1, "skip": 0, "limit": 10, "hasMore": false, "page": 1, "totalPages": 1 },
  "details": { "phoneLookup": { "status": "detected", "carrierName": "Example Mobile", "countryCode": "AZ" } }
}
```

Each search looks the number up once and returns at most one operator, so `page` must be 1. `limit` is 1 to 100 (default 10). `countryCode` and `cursor` are not search parameters.

`details.phoneLookup` tells you what the lookup found:

| `status` | Meaning | `items` |
|---|---|---|
| `detected` | The number's operator is in the catalog. | The operator with its offers. Empty when your offer filters leave none. |
| `notDetected` | No operator was found for the number. | Empty |
| `conflict` | The result contradicts the number's country, or matches several operators. | Empty |
| `notInCatalog` | The operator is not in the catalog, the line is not a mobile line, or no operator name came back. | Empty |

- `carrierName` is for display only. It is never an operator id.
- `countryCode` comes from the number itself and is present for every status.
- When `items` is empty, use the manual flow with `details.phoneLookup.countryCode`.
- A lookup that fails gives `503 / 10007` (`TEMPORARILY_UNAVAILABLE`). Retry later.

### Offer filters [#offer-filters]

`search` and `operators/{id}` take the same filters, which select offers inside the operator:

| Parameter | Meaning |
|---|---|
| `valueType` | `fixed` or `range`. |
| `valueCurrency` | Currency of `minValue` and `maxValue`. Required with either. |
| `minValue`, `maxValue` | Keep offers whose value overlaps this range. |
| `minPrice`, `maxPrice` | Keep offers whose indicative price overlaps this range, in the price currency. |
| `currency` | Price currency. The default is your API key's currency. |

The query parameter `maxPrice` filters indicative prices. It is not the `inputs.maxPrice` price limit of an order.

### Manual flow details [#manual-flow-details]

- `operators?countryCode=` takes only `countryCode` (ISO 3166-1 alpha-2, either letter case) and returns `{ items: [{ id, name, countryCode, category, logoUrl }] }` ordered by name, without paging.
- `operators/{id}` makes no lookup. A number of another country than the operator gives `400 / 10001` (`COUNTRY_MISMATCH`) at `phoneNumber`. An unknown id gives `404 / 10004`.
- Operator ids start with `operator_`. They name the operator only. You quote and order with an offer's `publicId`.

## Offers [#offers]

An operator lists its fixed offers by ascending value, then its range offers by ascending minimum.

- `value` is what the subscriber receives, in the operator's currency. A range has `min`, `max` and `step`.
- `price` is indicative and in the requested currency. For a range it is `{ min, max, currency }`, the price of the range's minimum and maximum. The quote is authoritative.
- A range's `step` is the smallest increment of the currency when the offer declares none (0.01 in most currencies, 1 in JPY, 0.001 in KWD). Quote and order accept the same `min`, `max` and `step` that search publishes. A step does not promise that every amount can be delivered. The quote checks the exact amount.
- `details.redemptionType` is `directTopUp` (an automatic recharge), `pin` (a PIN the customer activates) or null.
- `requiredInputs` lists `phoneNumber` first, then one `settings.<name>` entry for each setting the operator requires.

## Quote and order [#quote-and-order]

Quote and order take the same body. The fixed offer below is bought as it is, and the range offer at 50 AZN:

```json
{
  "currency": "USD",
  "referenceId": "partner-order-42",
  "items": [
    {
      "publicId": "airtime_raanuxyz6cxzie3w3my6c3r2wm",
      "quantity": 1,
      "inputs": {
        "phoneNumber": "+994501234567",
        "maxPrice": { "amount": 25, "currency": "USD" }
      }
    },
    {
      "publicId": "airtime_ms45o6lwxtqgrsculqdhop74zq",
      "quantity": 1,
      "inputs": {
        "phoneNumber": "+994501234567",
        "value": { "amount": 50, "currency": "AZN" },
        "maxPrice": { "amount": 31.25, "currency": "USD" }
      }
    }
  ]
}
```

```bash
curl -X POST https://api.sandbox.openroam.com/v1/airtime/quote \
  -H "X-Partner-Key: $OPENROAM_API_KEY" \
  -H "Content-Type: application/json" \
  -d @airtime-order.json

curl -X POST https://api.sandbox.openroam.com/v1/airtime/order \
  -H "X-Partner-Key: $OPENROAM_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d @airtime-order.json
```

Quote response:

```json
{
  "currency": "USD",
  "items": [
    {
      "publicId": "airtime_raanuxyz6cxzie3w3my6c3r2wm",
      "quantity": 1,
      "name": "Example Mobile 40 AZN",
      "value": { "amount": 40, "currency": "AZN" },
      "price": { "amount": 25.00, "currency": "USD" },
      "details": { "estimatedDeliveredValue": { "amount": 40, "currency": "AZN" } }
    },
    {
      "publicId": "airtime_ms45o6lwxtqgrsculqdhop74zq",
      "quantity": 1,
      "name": "Example Mobile 50 AZN",
      "value": { "amount": 50, "currency": "AZN" },
      "price": { "amount": 31.25, "currency": "USD" },
      "details": { "estimatedDeliveredValue": { "amount": 50, "currency": "AZN" } }
    }
  ],
  "total": { "amount": 56.25, "currency": "USD" }
}
```

- 1 to 5 items. `quantity` is optional and must be 1.
- `referenceId` is your own reference. Quote validates it and ignores it.
- A quote reserves nothing and does not expire. Order recalculates the operator and the price, so a quote does not bind it.
- `price` is per unit, and `total` is the sum of each price times its quantity.
- Items are checked one at a time in request order, and the first failing item ends the request. Quote and order report the same error for it.
- In a mixed [`POST /v1/orders`](/docs/api-reference/orders/create-order), each item adds `productType: "airtime"` and takes the same `inputs`.

### Inputs [#inputs]

| Member | Required | Meaning |
|---|---|---|
| `phoneNumber` | yes | The recipient's number in international format. It must belong to the offer's country. |
| `settings` | when the offer lists a required `settings.<name>` | Operator settings as an object of text values, only with the names the offer lists. For example `{ "customerId": "C-1" }`. |
| `value` | for a range offer | The top-up, `{ amount, currency }`, in the offer's value currency, within `min` and `max` and on the `step`. |
| `maxPrice` | no | The highest unit price you accept, `{ amount, currency }`, in the order currency. |
| `minDeliveredValue` | no | Range offers only. The lowest value you accept the recipient to receive, `{ amount, currency }`, in the `value` currency and at most `value`. |

Rules for `value`, `maxPrice` and `minDeliveredValue`:

- On a fixed offer, `value` is optional. When sent, it must equal the offer's amount and currency, and the item is ordered exactly as one sent without it.
- A range offer without `value` fails with `REQUIRED` at `inputs.value`.
- An amount is above 0 and has at most the decimals of its currency (none in JPY or KRW, three in KWD, two in most). A currency is three letters in either case.
- A current unit price above `maxPrice` fails with `409 / 11002` (`PRICE_CHANGED`) at `items[i].inputs.maxPrice`. Nothing is ordered or charged. The value is never reduced to fit `maxPrice`.
- Without `minDeliveredValue`, a range top-up must deliver exactly `value`. With it, the top-up may deliver less, down to the minimum. A fixed offer rejects it with `NOT_ALLOWED`. A range offer that sends it without `value` gets `REQUIRED` at `inputs.value`.
- When no delivery option can deliver an amount between the minimum and `value`, the item fails with `400 / 10001` (`AMOUNT_UNAVAILABLE`) at `items[i].inputs.value.amount`. Choose another value or allow a minimum.
- Any other member of `inputs`, and any member beside `inputs`, fails with `INVALID_VALUE`.

`details.estimatedDeliveredValue` in the quote is what the recipient is expected to receive. With `minDeliveredValue` it can be below `value`, so show it as the expected receipt.

### The number is looked up again [#the-number-is-looked-up-again]

Quote and order look the number up again for every item, whichever flow found the offer.

- When the operator is confirmed for the number, the item is priced and sold as usual.
- When the number cannot belong to the offer's operator, the item fails with `409 / 20000` (`AIRTIME_OPERATOR_CHANGED`) before anything is charged. This happens when another catalog operator is detected, the number is in another country than the operator, or several catalog operators match and the offer's is not one of them. Search again.
- In every other case, such as `notDetected` or `notInCatalog`, the item is sold as a manual selection, through the offers of the manual flow.

<Callout type="warn">
OpenRoam cannot always confirm that a number belongs to the operator chosen in the manual flow, and a top-up delivered after a wrong manual choice is not refunded. Ask your customer to check the operator before a manual purchase.
</Callout>

## The order item [#the-order-item]

An airtime item carries `purchasedProduct`, what was bought, and `fulfillment.result`, what was delivered:

```json
{
  "id": "01a1432e-7121-7829-a554-d8e2b22270c6",
  "orderId": "01a1432e-7121-7b0e-a0a0-c35454d3b883",
  "productType": "airtime",
  "price": { "amount": 31.25, "currency": "USD" },
  "purchasedProduct": {
    "name": "Example Mobile 50 AZN",
    "countryCode": "AZ",
    "logoUrl": "https://example.com/airtime/example-mobile.png",
    "value": { "amount": 50, "currency": "AZN" },
    "inputs": { "phoneNumber": "+994***4567", "minDeliveredValue": null },
    "details": {
      "redemptionType": "directTopUp",
      "estimatedDeliveredValue": { "amount": 50, "currency": "AZN" },
      "readMore": "Credit arrives within minutes."
    }
  },
  "fulfillment": {
    "status": "fulfilled",
    "result": {
      "deliveredValue": { "amount": 50, "currency": "AZN" },
      "details": { "redemption": { "type": "directTopUp", "pin": null, "instructions": null } }
    },
    "failure": null
  },
  "actions": {
    "amendment": { "availability": "notAvailable", "reason": null },
    "cancellation": { "availability": "notAvailable", "reason": null },
    "update": { "availability": "notAvailable", "reason": null }
  },
  "createdAt": "2026-10-16T05:27:59.521962Z",
  "effectivePaidAmount": { "amount": 31.25, "currency": "USD" }
}
```

- `purchasedProduct.name` is frozen at purchase. A range purchase is named at the purchased value.
- `purchasedProduct.value` is the top-up ordered.
- `purchasedProduct.inputs.phoneNumber` is masked as a plus sign, the country calling code, `***` and the last four digits, for example `+994***4567`. `minDeliveredValue` is echoed, and is null when none was sent. Operator `settings` are not echoed.
- `fulfillment.result.deliveredValue` is the amount reported as received by the recipient. It is null until known. A value reported later updates the result and sends another `order.fulfillment.updated` webhook with a higher `fulfillmentVersion`, while the status stays `fulfilled`.
- `fulfillment.result.details.redemption` is `{ type, pin, instructions }`, or null when the delivery is not declared. A `pin` top-up carries the issued PIN as a string and the customer `instructions`. Either is null when it was not received. Both are null for a `directTopUp`.

Read the order with [`GET /v1/orders/{id}`](/docs/api-reference/orders/get-by-id). The [`order.fulfillment.updated` webhook](/docs/api-reference/webhooks/order-fulfillment-updated) carries the same `result`. See [Webhooks](/docs/webhooks).

A delivered top-up cannot be cancelled, amended or updated. Cancel and its preview answer `422 / 18000`, amendments `422 / 18002` and update `422 / 18004`. While the top-up is pending, cancel answers `409 / 18001`. A rejected top-up is refunded in full automatically and reported by the `order-item.refunded` webhook. See [Orders](/docs/orders).

## Testing in Sandbox [#testing-in-sandbox]

Use [Sandbox](/docs/environments) with your Sandbox key. Authentication, validation, pricing, wallet payment and webhooks behave as in production, and the catalog and outcomes are synthetic.

### Scenarios [#scenarios]

`POST /v1/airtime/order` and the shared `POST /v1/orders` accept the `OpenRoam-Sandbox-Scenario` header:

| Value | Result |
|---|---|
| Omitted or `success` | A fulfilled item with the delivered value. |
| `fulfillment.rejected` | A rejected item with the normal fulfillment failure (`11001`) and no delivered result. It is refunded automatically. |
| `fulfillment.pending` | The item stays `pending` without blocking, and becomes eligible for success after about 15 minutes. |
| `fulfillment.late_success` | Pending, then success after about 2 minutes. |
| `fulfillment.late_rejected` | Pending, then rejection after about 2 minutes. |

```bash
curl -X POST https://api.sandbox.openroam.com/v1/airtime/order \
  -H "X-Partner-Key: $OPENROAM_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "OpenRoam-Sandbox-Scenario: fulfillment.rejected" \
  -H "Content-Type: application/json" \
  -d @airtime-order.json
```

- The scenario is saved with the order and takes part in idempotency. The same key and body replay the order. The same key with a different scenario returns `409 / 12001`. Use a new key to try another scenario. While the first request is still being accepted, the same key returns `409 / 12002`: retry after the `Retry-After` seconds.
- Search, quote and reads take no scenario header. Sending it there, or outside Sandbox, returns `400 / 10001` (`NOT_ALLOWED`). An unknown, empty or repeated value returns `400 / 10001` (`INVALID_VALUE`).
- Scenarios do not bypass validation, permissions or wallet checks.
- Timing is approximate and not a guarantee. A pending item may show `fulfillment.progress` with code `CONFIRMING_OUTCOME`. By default Sandbox fulfillment takes a few seconds, so read the order again before assuming a final state.

### Sandbox catalog [#sandbox-catalog]

The Sandbox catalog covers 30 countries: AZ, US, CA, TR, AE, ES, MY, MX, PH, ID, IT, PT, PL, GE, AM, PK, BD, VN, TH, EG, SA, ZA, BR, AR, CL, CO, NG, KE, SG and KR. Each country has one to three operators. Each operator has five to seven fixed denominations and one range, in the country's currency. Do not hardcode offer ids: search and the operator routes return them.

| Input | Sandbox behavior |
|---|---|
| A valid international number, such as `+994501234567` | Resolves a test operator and its offers for the number's country. |
| A valid number of an unsupported country | Search returns no items with `notInCatalog`, not an error. |
| Manual flow | You can select any listed operator of the number's country and quote or buy its offers. |
| Checkout currency | USD by default. Other configured currencies use a stored test exchange rate. |

Sample denominations, in the currency each country delivers:

| Country | Fixed values | Range | Step |
|---|---|---|---|
| AZ (AZN) | 10, 15, 20, 25, 30, 40, 50 | 5 to 50 | 1 |
| US (USD) | 10, 15, 20, 25, 30, 40, 50 | 5 to 100 | 1 |
| TR (TRY) | 65, 70, 250, 300, 400, 500, 750 | 65 to 1,000 | 5 |
| ES (EUR) | 5, 6, 10, 15, 20, 25, 30 | 5 to 50 | 1 |

Try these cases with `+994501234567`:

- Quote the fixed 10 AZN offer, and the range at 5 AZN and 50 AZN. The same range rejects 4, 5.50 and 51 AZN with `INVALID_VALUE` at `inputs.value.amount`.
- Send `currency: "EUR"` to see the checkout price in EUR while the delivered value stays in AZN.
- Search with `valueType=fixed&valueCurrency=AZN&minValue=12&maxValue=12` to find a fixed 12 AZN offer that lists a required `settings.recipientReference`. Quote it with `"settings": { "recipientReference": "test-ref-01" }`. Without the setting you get `400 / 10001` (`REQUIRED`).
- Search an operator's details with `valueType=range&valueCurrency=AZN&minValue=55` to find a range from 55 to 75 AZN where only 55 AZN is delivered exactly, and any higher value delivers 1 AZN less. Request 60 AZN with `"minDeliveredValue": { "amount": 59, "currency": "AZN" }` to be quoted and delivered 59 AZN. Without the minimum, or with a minimum of 60, you get `400 / 10001` (`AMOUNT_UNAVAILABLE`).
- Use `+966501234567` to test a country with a single operator.

## Errors [#errors]

Paths below are relative to the item. On quote, order and the shared order they are prefixed with `items[i].`.

| Status / code | Reason | When | Path |
|---|---|---|---|
| `400 / 10001` | `INVALID_VALUE` | `quantity` is not 1, or the number is not international. | `quantity`, `inputs.phoneNumber` |
| `400 / 10001` | `COUNTRY_MISMATCH` | The number belongs to another country than the offer. | `inputs.phoneNumber` |
| `400 / 10001` | `REQUIRED` | A required operator setting is missing, or a range offer has no `value`. | `inputs.settings.<name>`, `inputs.value` |
| `400 / 10001` | `UNSUPPORTED_FIELD` | A setting the offer does not list. | `inputs.settings.<name>` |
| `400 / 10001` | `INVALID_VALUE` | `value` outside the range, off its step, or not the fixed offer's amount, or an amount that is not above 0 or has too many decimals. | `inputs.value.amount` |
| `400 / 10001` | `AMOUNT_UNAVAILABLE` | No delivery option can deliver the amount. | `inputs.value.amount` |
| `400 / 10001` | `CURRENCY_MISMATCH` | `value`, `minDeliveredValue` or `maxPrice` in the wrong currency. | `inputs.value.currency`, `inputs.minDeliveredValue.currency`, `inputs.maxPrice.currency` |
| `400 / 10001` | `NOT_ALLOWED` | `minDeliveredValue` on a fixed offer. | `inputs.minDeliveredValue` |
| `400 / 11004` | `EXPIRED_OR_INVALID` | Unknown, malformed or foreign `publicId`, an operator id, or an offer of another product. | `items[i]` |
| `409 / 11003` | `UNAVAILABLE` | The offer cannot be sold now. | `items[i]` |
| `409 / 11002` | `PRICE_CHANGED` | The current unit price is above `inputs.maxPrice`. | `inputs.maxPrice` |
| `409 / 20000` | `AIRTIME_OPERATOR_CHANGED` | The lookup shows the offer's operator cannot be the number's. | none |
| `503 / 10007` | `TEMPORARILY_UNAVAILABLE` | The number lookup or the service is temporarily unavailable. Nothing is charged. | none |
| `404 / 10004` | | `operators/{id}` with an unknown id, or an operator without an orderable offer. | none |
| `403 / 10003` | `SERVICE_NOT_ENABLED` | Airtime is not enabled for your account, or the key lacks the `manage` permission for an order. | `service` |

`409 / 20000` and `503 / 10007` carry no `details`, so they do not name the item. After one of them in a request with several items, quote the items one at a time to find it.

Check which services are enabled with [`GET /v1/account/services`](/docs/api-reference/account/get-services). Idempotency errors are shared across products; see [Idempotency](/docs/idempotency). For the common error format, see [Errors](/docs/errors).

## Next steps [#next-steps]

- [Quickstart](/docs/quickstart) for your first order.
- [Authentication](/docs/authentication) and [Environments](/docs/environments) for keys and hosts.
- [Orders](/docs/orders) for order and item status.
- [Webhooks](/docs/webhooks) for signing and retries.