Order airtime
Places an airtime top-up order and returns the accepted order.
Places an airtime top-up order and returns the accepted order.
Takes the same body as quote and needs the manage order permission (403 / 10003 without it). An
Idempotency-Key header with a new UUID is required for every purchase: a retry with the same key and body
returns the order already accepted, 409 / 12002 with Retry-After while it is still being accepted, and a
changed body gives 409 / 12001. The number's operator is looked up again, as in quote; item errors are named
at items[i], and a current price above inputs.maxPrice gives 409 / 11002 before anything is
charged. Track fulfillment with the order routes or the order.fulfillment.updated webhook. A wallet
charge that fails creates no order and gives 402 / 16000, with details[0] naming wallet and
INSUFFICIENT_BALANCE or WALLET_BLOCKED; send the same request with the same key after a top-up.
PartnerApiKeyX-Partner-Key<token>Partner API Key (X-Partner-Key)
Idempotency-Key*stringUUID idempotency key for safe retries of this operation.
uuid- body
The body B2B airtime quote and order both take.
currency?|Order currency, three letters in either case; the API key's currency when omitted. An unsupported code gives
400 / 10001 at currency, reason NOT_SUPPORTED, before any item is checked.
referenceId?|Optional partner order reference, unique per partner, at most 128 characters without leading or trailing spaces. A quote validates it and ignores it.
items*array<>1 to 5 items, each topping up one number once.
OK
- response
The current state of an order.
id*stringOrder id.
uuidorigin*Where the order was created.
status*stringCurrent order status: paymentPending, processing, completed,
partiallyFulfilled, fulfillmentFailed, partiallyRefunded, refunded or cancelled.
"paymentPending""processing""completed""partiallyFulfilled""fulfillmentFailed""partiallyRefunded""refunded""cancelled"total*What was charged for the order, in the order's currency, before refunds: the item prices plus completed amendment charges, less completed amendment credits.
refunded*What completed item refunds returned, in the order's currency; zero when nothing was
returned. You paid total minus refunded, the sum of the items' effectivePaidAmount.
payment?|The latest payment attempt; null when none was made.
items*array<>The order items, one per unit bought.
timeline*array<>Every status the order has had, oldest first, each once per stretch.
createdAt*stringWhen the order was created (UTC).
date-timeupdatedAt*stringWhen anything in the order last changed (UTC): its status, an item's fulfillment, a refund or an amendment.
date-timefulfillmentVersion*integerIncreases with every fulfillment change; matches the
order.fulfillment.updated webhook.
int64referenceId?|Your own order reference, when one was sent.
customer?|The traveller who paid on your hosted site, masked; null unless the origin is site, and
once the traveller's details are deleted at the end of their retention period.
curl -X POST 'https://api.sandbox.openroam.com/v1/airtime/order' \ -H 'Idempotency-Key: 0b8f7f3e-6b7a-4a52-9a5e-3d2f1a9c7e10' \ -H 'Content-Type: application/json' \ -d '{ "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" } } } ]}'{ "id": "01a1432e-7121-7b0e-a0a0-c35454d3b883", "referenceId": "partner-order-42", "origin": { "channel": "api" }, "status": "processing", "total": { "amount": 56.25, "currency": "USD" }, "refunded": { "amount": 0, "currency": "USD" }, "payment": { "status": "completed", "method": "balance", "amount": { "amount": 56.25, "currency": "USD" }, "wallet": { "label": "Main wallet", "debited": { "amount": 56.25, "currency": "USD" } }, "failure": null }, "items": [ { "id": "01a1432e-7121-70bc-800a-3f896e23b7c8", "orderId": "01a1432e-7121-7b0e-a0a0-c35454d3b883", "productType": "airtime", "price": { "amount": 25, "currency": "USD" }, "purchasedProduct": { "name": "Test operator 40 AZN", "countryCode": "AZ", "logoUrl": "https://cdn.openroam.test/airtime/test-operator.png", "value": { "amount": 40, "currency": "AZN" }, "inputs": { "phoneNumber": "+994***4567", "minDeliveredValue": null }, "details": { "redemptionType": "directTopUp", "estimatedDeliveredValue": { "amount": 40, "currency": "AZN" }, "readMore": "Credit arrives within minutes." } }, "fulfillment": { "status": "pending", "result": 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": 25, "currency": "USD" } }, { "id": "01a1432e-7121-7829-a554-d8e2b22270c6", "orderId": "01a1432e-7121-7b0e-a0a0-c35454d3b883", "productType": "airtime", "price": { "amount": 31.25, "currency": "USD" }, "purchasedProduct": { "name": "Test operator 50 AZN", "countryCode": "AZ", "logoUrl": "https://cdn.openroam.test/airtime/test-operator.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": "pending", "result": 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" } } ], "timeline": [ { "status": "paymentPending", "occurredAt": "2026-10-16T05:27:59.521962Z" }, { "status": "processing", "occurredAt": "2026-10-16T05:27:59.521962Z" } ], "createdAt": "2026-10-16T05:27:59.521962Z", "updatedAt": "2026-10-16T05:27:59.521962Z", "fulfillmentVersion": 1}Airtime catalog GET
Returns the operator directory, page by page, for partner inventory. Returns `{ items: [{ id, name, countryCode, category, logoUrl }], nextCursor }`, ordered by operator ID. Pass `nextCursor` back as `cursor` with the same `countryCode` until it is null; a page can hold fewer items than `limit`, and the cursor does not expire. A cursor reused with another `countryCode`, or a blank or invalid `countryCode`, gives 400 / 10001. Offers are not exported: they depend on whether the operator is detected or chosen, so read them with `operators/{id}?phoneNumber=`.
Get an airtime operator GET
Returns one operator with its offers for a phone number of its country (manual flow, step 2). Returns the operator in the item shape that search returns, without a carrier lookup. A number of another country than the operator's gives 400 / 10001 with `COUNTRY_MISMATCH` at `phoneNumber`. An unknown ID, including any value that is not an operator ID, or an operator without an orderable offer, gives 404 / 10004. Offer filters that match none of the operator's offers leave `offers` empty. A manual choice is not checked against the number's carrier, so have the customer confirm the operator before ordering.