Skip to Content
OpenRoam Docs
Airtime

Order airtime

Places an airtime top-up order and returns the accepted order.

POST
/v1/airtime/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.

Authorization

PartnerApiKey
headerX-Partner-Key<token>

Partner API Key (X-Partner-Key)

Header Parameters

Idempotency-Key*string

UUID idempotency key for safe retries of this operation.

Formatuuid

Request Body

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

Response Body

OK

  1. response

The current state of an order.

id*string

Order id.

Formatuuid
origin*

Where the order was created.

status*string

Current order status: paymentPending, processing, completed, partiallyFulfilled, fulfillmentFailed, partiallyRefunded, refunded or cancelled.

Value in"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*string

When the order was created (UTC).

Formatdate-time
updatedAt*string

When anything in the order last changed (UTC): its status, an item's fulfillment, a refund or an amendment.

Formatdate-time
fulfillmentVersion*integer

Increases with every fulfillment change; matches the order.fulfillment.updated webhook.

Formatint64
referenceId?|

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.

Example Request
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"        }      }    }  ]}'
Example Response
{  "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}