Pay utility bills
Places a utility bill payment order and returns the accepted order.
Places a utility bill payment 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.
Every price is recalculated: a current price above inputs.maxPrice gives 409 / 11002 at
items[i].inputs.maxPrice before anything is charged, and without inputs.maxPrice the current price
is charged. The item is fulfilled when the payment is confirmed and, for a token biller, the
token is returned; track it 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 utility quote and order both take.
currency?|Order currency, the currency you are charged in, 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 paying one bill.
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/utility/order' \ -H 'Idempotency-Key: 0b8f7f3e-6b7a-4a52-9a5e-3d2f1a9c7e10' \ -H 'Content-Type: application/json' \ -d '{ "currency": "USD", "referenceId": "partner-order-42", "items": [ { "publicId": "utility_7tq2mw5kxr3nbv6hzc4dpe2ysa", "quantity": 1, "inputs": { "accountNumber": "1234567", "invoiceId": "invoice-1", "maxPrice": { "amount": 30, "currency": "USD" } } }, { "publicId": "utility_k4hv2cq7wnz5jr3xmtb6eyl2pa", "quantity": 1, "inputs": { "accountNumber": "7654321", "value": { "amount": 50, "currency": "AZN" }, "maxPrice": { "amount": 35, "currency": "USD" } } } ]}'{ "id": "01a14331-d5ce-7f2a-9b1c-4e6d8a0c2f13", "referenceId": "partner-order-42", "origin": { "channel": "api" }, "status": "processing", "total": { "amount": 61.56, "currency": "USD" }, "refunded": { "amount": 0, "currency": "USD" }, "payment": { "status": "completed", "method": "balance", "amount": { "amount": 61.56, "currency": "USD" }, "wallet": { "label": "Main wallet", "debited": { "amount": 61.56, "currency": "USD" } }, "failure": null }, "items": [ { "id": "01a14331-d5de-7970-b70e-5734e59e2f7c", "orderId": "01a14331-d5ce-7f2a-9b1c-4e6d8a0c2f13", "productType": "utility", "price": { "amount": 27.5, "currency": "USD" }, "purchasedProduct": { "name": "Fixed postpaid 40 AZN", "countryCode": "AZ", "logoUrl": null, "value": { "amount": 40, "currency": "AZN" }, "inputs": { "accountNumber": "***4567", "mobileNumber": null, "beneficiaryMobileNumber": null, "invoiceId": "***ce-1" }, "details": { "serviceType": "postpaid", "deliveryType": "directCredit" } }, "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": 27.5, "currency": "USD" } }, { "id": "01a14331-d5f1-7e18-8963-7fcdc3b15eab", "orderId": "01a14331-d5ce-7f2a-9b1c-4e6d8a0c2f13", "productType": "utility", "price": { "amount": 34.06, "currency": "USD" }, "purchasedProduct": { "name": "Range prepaid 50 AZN", "countryCode": "AZ", "logoUrl": null, "value": { "amount": 50, "currency": "AZN" }, "inputs": { "accountNumber": "***4321", "mobileNumber": null, "beneficiaryMobileNumber": null, "invoiceId": null }, "details": { "serviceType": "prepaid", "deliveryType": "token" } }, "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": 34.06, "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}Search airtime by phone number GET
Searches for a phone number's operator by carrier lookup and returns it with its offers (detected flow). Returns `{ items, pagination, details: { phoneLookup: { status, carrierName, countryCode } } }`. `items` holds at most the detected operator with its offers. It is empty when `status` is not `detected` or no offer remains after the filters; then let the customer choose the operator with `GET operators?countryCode=`, using `details.phoneLookup.countryCode`. Each call makes exactly one carrier lookup and returns at most one item, so `page` must be 1. A `phoneNumber` that is not in international format gives 400 / 10001; a carrier lookup that fails gives 503 / 10007, retry later.
Get a biller GET
Returns one biller with its offers, in the item shape that search returns. An unknown ID, an ID that does not start with `biller_` (an offer's `publicId` among them), or a biller without an orderable offer gives 404 / 10004.