Skip to Content
OpenRoam Docs

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.

  1. 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.

  1. GET /v1/airtime/operators?countryCode= lists the operators of a country, without offers.
  2. GET /v1/airtime/operators/{id}?phoneNumber= returns the chosen operator with its offers, in the shape search returns.

Then, in both flows:

  1. POST /v1/airtime/quote prices an order body. It has no side effects.
  2. POST /v1/airtime/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= 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 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 for order and item status, and Idempotency for retries.

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:

statusMeaningitems
detectedThe number's operator is in the catalog.The operator with its offers. Empty when your offer filters leave none.
notDetectedNo operator was found for the number.Empty
conflictThe result contradicts the number's country, or matches several operators.Empty
notInCatalogThe 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

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

ParameterMeaning
valueTypefixed or range.
valueCurrencyCurrency of minValue and maxValue. Required with either.
minValue, maxValueKeep offers whose value overlaps this range.
minPrice, maxPriceKeep offers whose indicative price overlaps this range, in the price currency.
currencyPrice 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 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

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 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.json

Quote 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. 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, each item adds productType: "airtime" and takes the same inputs.

Inputs

MemberRequiredMeaning
phoneNumberyesThe recipient's number in international format. It must belong to the offer's country.
settingswhen 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" }.
valuefor a range offerThe top-up, { amount, currency }, in the offer's value currency, within min and max and on the step.
maxPricenoThe highest unit price you accept, { amount, currency }, in the order currency.
minDeliveredValuenoRange 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

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.

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.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}. 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:

ValueResult
Omitted or successA fulfilled item with the delivered value.
fulfillment.rejectedA rejected item with the normal fulfillment failure (11001) and no delivered result. It is refunded automatically.
fulfillment.pendingThe item stays pending without blocking, and becomes eligible for success after about 15 minutes.
fulfillment.late_successPending, then success after about 2 minutes.
fulfillment.late_rejectedPending, 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 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

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.

InputSandbox behavior
A valid international number, such as +994501234567Resolves a test operator and its offers for the number's country.
A valid number of an unsupported countrySearch returns no items with notInCatalog, not an error.
Manual flowYou can select any listed operator of the number's country and quote or buy its offers.
Checkout currencyUSD by default. Other configured currencies use a stored test exchange rate.

Sample denominations, in the currency each country delivers:

CountryFixed valuesRangeStep
AZ (AZN)10, 15, 20, 25, 30, 40, 505 to 501
US (USD)10, 15, 20, 25, 30, 40, 505 to 1001
TR (TRY)65, 70, 250, 300, 400, 500, 75065 to 1,0005
ES (EUR)5, 6, 10, 15, 20, 25, 305 to 501

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

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

Status / codeReasonWhenPath
400 / 10001INVALID_VALUEquantity is not 1, or the number is not international.quantity, inputs.phoneNumber
400 / 10001COUNTRY_MISMATCHThe number belongs to another country than the offer.inputs.phoneNumber
400 / 10001REQUIREDA required operator setting is missing, or a range offer has no value.inputs.settings.<name>, inputs.value
400 / 10001UNSUPPORTED_FIELDA setting the offer does not list.inputs.settings.<name>
400 / 10001INVALID_VALUEvalue 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 / 10001AMOUNT_UNAVAILABLENo delivery option can deliver the amount.inputs.value.amount
400 / 10001CURRENCY_MISMATCHvalue, minDeliveredValue or maxPrice in the wrong currency.inputs.value.currency, inputs.minDeliveredValue.currency, inputs.maxPrice.currency
400 / 10001NOT_ALLOWEDminDeliveredValue on a fixed offer.inputs.minDeliveredValue
400 / 11004EXPIRED_OR_INVALIDUnknown, malformed or foreign publicId, an operator id, or an offer of another product.items[i]
409 / 11003UNAVAILABLEThe offer cannot be sold now.items[i]
409 / 11002PRICE_CHANGEDThe current unit price is above inputs.maxPrice.inputs.maxPrice
409 / 20000AIRTIME_OPERATOR_CHANGEDThe lookup shows the offer's operator cannot be the number's.none
503 / 10007TEMPORARILY_UNAVAILABLEThe number lookup or the service is temporarily unavailable. Nothing is charged.none
404 / 10004operators/{id} with an unknown id, or an operator without an orderable offer.none
403 / 10003SERVICE_NOT_ENABLEDAirtime 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

On this page