Airtime
Top up mobile numbers in many countries with fixed or range-priced airtime offers, from number lookup to delivered value.
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
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.
GET /v1/airtime/search?phoneNumber=returns the detected operator with its offers.
Manual flow. Use this when search finds no operator, or when you want your customer to choose.
GET /v1/airtime/operators?countryCode=lists the operators of a country, without offers.GET /v1/airtime/operators/{id}?phoneNumber=returns the chosen operator with its offers, in the shape search returns.
Then, in both flows:
POST /v1/airtime/quoteprices an order body. It has no side effects.POST /v1/airtime/orderplaces the order. It needs anIdempotency-Keyheader and an API key with themanagepermission.
Other routes:
GET /v1/airtime/number-lookup?phoneNumber=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/catalogis the operator directory, page by page with a cursor, as summaries without offers. Filter withcountryCode, page withlimit(1 to 100) andcursor.
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 for order and item status, and Idempotency for retries.
Search
curl "https://api.sandbox.openroam.com/v1/airtime/search?phoneNumber=%2B994501234567" \
-H "X-Partner-Key: $OPENROAM_API_KEY"{
"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 |
carrierNameis for display only. It is never an operator id.countryCodecomes from the number itself and is present for every status.- When
itemsis empty, use the manual flow withdetails.phoneLookup.countryCode. - A lookup that fails gives
503 / 10007(TEMPORARILY_UNAVAILABLE). Retry later.
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
operators?countryCode=takes onlycountryCode(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 gives400 / 10001(COUNTRY_MISMATCH) atphoneNumber. An unknown id gives404 / 10004.- Operator ids start with
operator_. They name the operator only. You quote and order with an offer'spublicId.
Offers
An operator lists its fixed offers by ascending value, then its range offers by ascending minimum.
valueis what the subscriber receives, in the operator's currency. A range hasmin,maxandstep.priceis 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
stepis 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 samemin,maxandstepthat search publishes. A step does not promise that every amount can be delivered. The quote checks the exact amount. details.redemptionTypeisdirectTopUp(an automatic recharge),pin(a PIN the customer activates) or null.requiredInputslistsphoneNumberfirst, then onesettings.<name>entry for each setting the operator requires.
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:
{
"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" }
}
}
]
}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.jsonQuote response:
{
"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.
quantityis optional and must be 1. referenceIdis 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.
priceis per unit, andtotalis 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, each item addsproductType: "airtime"and takes the sameinputs.
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,
valueis 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
valuefails withREQUIREDatinputs.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
maxPricefails with409 / 11002(PRICE_CHANGED) atitems[i].inputs.maxPrice. Nothing is ordered or charged. The value is never reduced to fitmaxPrice. - Without
minDeliveredValue, a range top-up must deliver exactlyvalue. With it, the top-up may deliver less, down to the minimum. A fixed offer rejects it withNOT_ALLOWED. A range offer that sends it withoutvaluegetsREQUIREDatinputs.value. - When no delivery option can deliver an amount between the minimum and
value, the item fails with400 / 10001(AMOUNT_UNAVAILABLE) atitems[i].inputs.value.amount. Choose another value or allow a minimum. - Any other member of
inputs, and any member besideinputs, fails withINVALID_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
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
notDetectedornotInCatalog, the item is sold as a manual selection, through the offers of the manual flow.
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.
The order item
An airtime item carries purchasedProduct, what was bought, and fulfillment.result, what was delivered:
{
"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.nameis frozen at purchase. A range purchase is named at the purchased value.purchasedProduct.valueis the top-up ordered.purchasedProduct.inputs.phoneNumberis masked as a plus sign, the country calling code,***and the last four digits, for example+994***4567.minDeliveredValueis echoed, and is null when none was sent. Operatorsettingsare not echoed.fulfillment.result.deliveredValueis the amount reported as received by the recipient. It is null until known. A value reported later updates the result and sends anotherorder.fulfillment.updatedwebhook with a higherfulfillmentVersion, while the status staysfulfilled.fulfillment.result.details.redemptionis{ type, pin, instructions }, or null when the delivery is not declared. Apintop-up carries the issued PIN as a string and the customerinstructions. Either is null when it was not received. Both are null for adirectTopUp.
Read the order with GET /v1/orders/{id}. The order.fulfillment.updated webhook carries the same result. See 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.
Testing in Sandbox
Use Sandbox with your Sandbox key. Authentication, validation, pricing, wallet payment and webhooks behave as in production, and the catalog and outcomes are synthetic.
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. |
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 returns409 / 12002: retry after theRetry-Afterseconds. - 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 returns400 / 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.progresswith codeCONFIRMING_OUTCOME. By default Sandbox fulfillment takes a few seconds, so read the order again before assuming a final state.
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_VALUEatinputs.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=12to find a fixed 12 AZN offer that lists a requiredsettings.recipientReference. Quote it with"settings": { "recipientReference": "test-ref-01" }. Without the setting you get400 / 10001(REQUIRED). - Search an operator's details with
valueType=range&valueCurrency=AZN&minValue=55to 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 get400 / 10001(AMOUNT_UNAVAILABLE). - Use
+966501234567to test a country with a single operator.
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. Idempotency errors are shared across products; see Idempotency. For the common error format, see Errors.
Next steps
- Quickstart for your first order.
- Authentication and Environments for keys and hosts.
- Orders for order and item status.
- Webhooks for signing and retries.