Utility bill payments
Pay electricity, water, gas, internet and other bills, or buy prepaid tokens and PINs, for billers in many countries.
What you can sell
A biller is one payee in one country, such as an electricity company or a television operator. Billers belong to a category (electricity, water, gas, internet, television, landline, voip, toll or other) and a service type (prepaid or postpaid).
A biller sells fixed amounts, a range of amounts, or both. Two kinds of delivery exist:
directCredit: the payment reaches the biller. The item has no token.token: the payment returns a usable token, such as a prepaid meter token or a PIN.
OpenRoam sells ranged and fixed bill payments and recharges with the inputs listed on each offer. Each item pays one bill, so quantity is always 1. To pay the same biller twice, send two items.
The flow
Search
GET /v1/utility/search returns billers with their offers, one page at a time. countryCode is required. Other filters are category, serviceType, q (text in the biller name, at most 100 characters), currency, page and limit.
Related routes:
GET /v1/utility/billers/{id}returns one biller in the shape search returns.GET /v1/utility/catalogwalks every biller in id order, page by page with a cursor.countryCodeis optional here.
Utility has no list of summaries, and no value or price filters: valueType, minValue, maxValue, minPrice and maxPrice are unknown parameters. Unknown parameters are rejected with 400 / 10001 (UNSUPPORTED_FIELD).
Quote
POST /v1/utility/quote prices an order body. It has no side effects: no token, no reservation, no expiry, no payment, and no check of the customer's account with the biller. To hold a quoted price, send it as inputs.maxPrice in the order.
Order
POST /v1/utility/order takes the same body as the quote. It needs an Idempotency-Key header and an API key with the manage permission. The response is the shared order envelope, read later with GET /v1/orders/{id}. See Idempotency and Orders.
You can also pay bills together with other products through POST /v1/orders, where each item adds productType: "utility".
Search
curl "https://api.sandbox.openroam.com/v1/utility/search?countryCode=AZ" \
-H "X-Partner-Key: $OPENROAM_API_KEY"{
"items": [
{
"id": "biller_3jx464dkw4ekdjgj4qxuib5wki",
"name": "Fixed postpaid",
"countryCode": "AZ",
"category": "other",
"logoUrl": null,
"description": null,
"offers": [
{
"publicId": "utility_7tq2mw5kxr3nbv6hzc4dpe2ysa",
"name": "Local tier",
"description": null,
"value": { "type": "fixed", "amount": 40, "currency": "AZN" },
"price": { "amount": 27.5, "currency": "USD" },
"requiredInputs": [
{ "name": "accountNumber", "type": "text", "required": true, "description": "The customer's account or meter number with the biller." }
]
}
],
"details": { "serviceType": "postpaid", "deliveryType": "directCredit" }
},
{
"id": "biller_jeicjoplfgowwmc2h7mbwbatqe",
"name": "Range prepaid",
"countryCode": "AZ",
"category": "other",
"logoUrl": null,
"description": null,
"offers": [
{
"publicId": "utility_k4hv2cq7wnz5jr3xmtb6eyl2pa",
"name": "Range prepaid 20–200 AZN",
"description": null,
"value": { "type": "range", "min": 20, "max": 200, "step": 0.01, "currency": "AZN" },
"price": { "min": 14.38, "max": 132.5, "currency": "USD" },
"requiredInputs": [
{ "name": "accountNumber", "type": "text", "required": true, "description": "The customer's account or meter number with the biller." }
]
}
],
"details": { "serviceType": "prepaid", "deliveryType": "token" }
}
],
"pagination": { "currentCount": 2, "totalCount": 2, "skip": 0, "limit": 10, "hasMore": false, "page": 1, "totalPages": 1 }
}Billers
idis the biller's opaque token, starting withbiller_. It names the biller, not something to buy. Quote and order take an offer'spublicId. Sending a biller id, or any malformed id, as apublicIdgives400 / 11004.countryCodeis the biller's ISO 3166-1 alpha-2 country and is never null.categoryis one of the values above. A category OpenRoam does not map isother.details.serviceTypeisprepaidorpostpaid.details.deliveryTypeistokenordirectCredit.billers/{id}returns404 / 10004for an unknown id, an id that does not start withbiller_, and a biller without an orderable offer. Search does not list such billers either.- A search page holds fewer billers than
limitwhen some billers on it cannot be priced.pagination.totalCountcounts billers that match the filters and have an orderable route.
Catalog walks
Continue with nextCursor, the same filters and the same currency until nextCursor is null. A page can hold fewer billers than limit, even none, while nextCursor is not null. A cursor reused with other filters or another currency gives 400 / 10001, so start the walk again.
The walk is not a frozen snapshot. A biller that stays available during the whole walk appears exactly once, and one that appears or disappears during the walk may be missing. Update your copy by biller id, and remove a biller only when a complete walk with the same filters did not return it. On 429, wait for Retry-After and request the same page again.
Offers
A biller's offers are:
- one fixed offer per package: a product sold under its own label, such as a fixed recharge or a PIN. Two packages can have the same amount, so the amount does not name one;
- one fixed offer per fixed amount without a package, per currency;
- one range offer per currency and set of required inputs.
Fixed offers come first, by ascending value, then the range offers.
publicIdis an opaque token starting withutility_. Order with it exactly as browse returns it. Do not build or parse it. The id stays the same while the biller has that offer. When a biller stops selling an offer its id names nothing, and a new offer gets a new id. The offer id alone decides what is bought: there is no package or option input.nameis the stored label of a package or fixed amount when one exists, for exampleLocal tier. Otherwise it is built from the biller and the value, such asFixed postpaid 40 AZNorRange prepaid 20–200 AZN.valueis in the currency the biller is paid in:{ type: "fixed", amount, currency }or{ type: "range", min, max, step, currency }. A range'smaxis null when there is no upper bound. Use the offer's currency, not a country-wide assumption: a country can have billers paid in local currency and in USD.priceis indicative and in the requested currency. A range'spriceis{ min, max, currency }, the price of its minimum and maximum value, andprice.maxis null whenvalue.maxis. The quote is authoritative, and it can be higher or lower than the browse price. An offer whose price cannot be computed is left out.- One range offer can combine several ranges in the same currency that take the same inputs. Its
minis the lowest minimum and itsmaxthe highest maximum. An amount must be on the published range and step. An amount on that grid that none of the underlying ranges sells gives409 / 11003atitems[i]. An amount outside the published range gives400 / 10001(INVALID_VALUE).
Required inputs
requiredInputs lists the customer inputs an offer takes. Each listed input is required.
name | type | Listed when the biller needs |
|---|---|---|
accountNumber | text | The customer's account or meter number. |
mobileNumber | phone | The customer's mobile number with the biller. |
beneficiaryMobileNumber | phone | The mobile number of the person who receives the payment. |
invoiceId | text | The id of the bill to pay, as the biller issued it. At most 64 characters. Only for an offer that lists it. |
- A value is trimmed, must not be empty, and has at most 128 characters. Account numbers keep their leading zeros.
- A
phonevalue must be an international number starting with+or00. Spaces, hyphens and brackets are removed, and00becomes+. Bare digits such as994501234567are rejected withINVALID_VALUEatitems[i].inputs.mobileNumber(orbeneficiaryMobileNumber), because OpenRoam does not guess the country. - A listed input the item leaves out is
REQUIREDatitems[i].inputs.<name>. An input the offer does not list isNOT_ALLOWEDat the same path, before any purchase is attempted. - An offer can list no inputs, for example a PIN product.
inputsmay then be omitted, unless the offer is a range, which needsinputs.value.
inputs also takes the standard value and maxPrice fields. requiredInputs never lists them.
Quote and order
Quote and order take the same body. The fixed offer below is bought without a value, and the range offer at 50 AZN:
{
"currency": "USD",
"referenceId": "partner-order-42",
"items": [
{
"publicId": "utility_7tq2mw5kxr3nbv6hzc4dpe2ysa",
"quantity": 1,
"inputs": {
"accountNumber": "1234567",
"maxPrice": { "amount": 30, "currency": "USD" }
}
},
{
"publicId": "utility_k4hv2cq7wnz5jr3xmtb6eyl2pa",
"quantity": 1,
"inputs": {
"accountNumber": "7654321",
"value": { "amount": 50, "currency": "AZN" },
"maxPrice": { "amount": 35, "currency": "USD" }
}
}
]
}curl -X POST https://api.sandbox.openroam.com/v1/utility/quote \
-H "X-Partner-Key: $OPENROAM_API_KEY" \
-H "Content-Type: application/json" \
-d @utility-order.json
curl -X POST https://api.sandbox.openroam.com/v1/utility/order \
-H "X-Partner-Key: $OPENROAM_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d @utility-order.jsonQuote response:
{
"currency": "USD",
"items": [
{
"publicId": "utility_7tq2mw5kxr3nbv6hzc4dpe2ysa",
"quantity": 1,
"name": "Fixed postpaid 40 AZN",
"value": { "amount": 40, "currency": "AZN" },
"price": { "amount": 27.5, "currency": "USD" },
"details": { "deliveryType": "directCredit" }
},
{
"publicId": "utility_k4hv2cq7wnz5jr3xmtb6eyl2pa",
"quantity": 1,
"name": "Range prepaid 50 AZN",
"value": { "amount": 50, "currency": "AZN" },
"price": { "amount": 34.06, "currency": "USD" },
"details": { "deliveryType": "token" }
}
],
"total": { "amount": 61.56, "currency": "USD" }
}- 1 to 5 items.
quantitymust be 1. currencyis the price currency, the one you are charged in. It is optional, and the default is your API key's currency. It is separate from the value currency.referenceIdis your own reference. Quote validates it and ignores it.publicIdin the quote response is always the one you sent.- 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.
inputs.value is the amount to pay the biller, { amount, currency }, in the offer's value currency:
- A range offer requires it, on the published range and step. A range offer without it fails with
REQUIREDatitems[i].inputs.value. - A fixed offer takes it optionally. When sent, it must equal the offer's amount. A fixed offer without it pays its own amount.
- An amount outside the published range, off its step, or other than the fixed offer's amount is
400 / 10001(INVALID_VALUE) atitems[i].inputs.value.amount. A value in another currency isCURRENCY_MISMATCHatitems[i].inputs.value.currency. - An amount is above 0 and has at most the decimals of its currency (two in most currencies, none in JPY, three in KWD).
inputs.maxPrice is the highest unit price you accept, { amount, currency }, in the order currency. It is optional.
- Order recalculates every price. A lower price is charged as calculated. A higher price is accepted up to
maxPrice. Above it, the order fails with409 / 11002atitems[i].inputs.maxPriceand nothing is charged. - Without
maxPrice, the current price is charged, including an increase since the quote. - The amount paid to the biller is never reduced to fit
maxPrice.
A purchase name is the same in the quote and on the order item. A package keeps its stored label, or the biller name when its label is blank. Any other purchase is named from the biller and the purchased value, for example Range prepaid 50 AZN. A range purchase is never named by its bounds.
Delivery types and the order item
deliveryType says what a paid bill delivers, and when the item becomes fulfilled:
deliveryType | fulfillment.status becomes fulfilled when | result.details.token |
|---|---|---|
token | The payment is confirmed and a usable token is returned, such as a prepaid meter token or a PIN. | The token |
directCredit | The payment is confirmed as reaching the biller. | null |
A payment that is confirmed without the token it promised stays pending until it is resolved. A reference alone does not mean fulfilled.
{
"id": "01a14331-d5f1-7e18-8963-7fcdc3b15eab",
"orderId": "01a14331-d5d2-7a25-9f98-9bbd58e02e05",
"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": "fulfilled",
"result": {
"deliveredValue": { "amount": 50, "currency": "AZN" },
"details": { "token": "example-meter-token" }
},
"failure": null
},
"actions": {
"amendment": { "availability": "notAvailable", "reason": null },
"cancellation": { "availability": "notAvailable", "reason": null },
"update": { "availability": "notAvailable", "reason": null }
},
"createdAt": "2026-10-16T05:31:41.959678Z",
"effectivePaidAmount": { "amount": 34.06, "currency": "USD" }
}purchasedProduct:
nameis the purchase name.countryCodeis the biller's country.logoUrlis always null on the item, so read the logo from the biller.valueis the amount paid to the biller.inputsechoesaccountNumber,mobileNumber,beneficiaryMobileNumberandinvoiceId, and an input the item did not store is null. Masking:accountNumberandinvoiceIdare masked as***followed by the last four characters. A value of four characters or fewer is shown as***.mobileNumberandbeneficiaryMobileNumberare masked as a plus sign, the country code,***and the last four digits.valueandmaxPriceare not echoed. The amount ispurchasedProduct.value.
detailshasserviceTypeanddeliveryType. It readsunknownfor items bought before the delivery type was stored.
fulfillment.result:
deliveredValueis the amount confirmed as received by the customer. It is null until confirmed and is never copied frompurchasedProduct.value. A later confirmation sends anotherorder.fulfillment.updatedwebhook with a higherfulfillmentVersion.details.tokenis the token of atokenbiller once the payment is ready, and null otherwise. Handle it as a secret: show it only to the customer who paid.
fulfillment.status stays pending until the payment is confirmed and, for a token biller, the token is known. Read the order with GET /v1/orders/{id}. The order.fulfillment.updated webhook carries the same result. See Webhooks and Orders.
A bill payment cannot be taken back or changed. Once delivered, cancel and its preview answer 422 / 18000, amendments 422 / 18002 and update 422 / 18004. While the payment is pending, cancel answers 409 / 18001. A rejected payment is refunded in full automatically and reported by the order-item.refunded webhook. A reversal after delivery does not credit your wallet by itself.
Testing in Sandbox
Use Sandbox with your Sandbox key. Authentication, validation, pricing, wallet payment and webhooks behave as in production. The catalog and outcomes are synthetic, and no real account lookup or payment happens.
Scenarios
POST /v1/utility/order and the shared POST /v1/orders accept the OpenRoam-Sandbox-Scenario header:
| Value | Result |
|---|---|
Omitted or success | Confirmed delivery. A directCredit item has no token. A token item returns a code starting with SANDBOX-NONREDEEMABLE-, which cannot pay a real bill. |
fulfillment.rejected | A definitive rejection, with no delivered value and no token. The item 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/utility/order \
-H "X-Partner-Key: $OPENROAM_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H "OpenRoam-Sandbox-Scenario: fulfillment.rejected" \
-H "Content-Type: application/json" \
-d @utility-order.json- The scenario is saved with the order and takes part in idempotency. The same key and body replay the order. Omitted and explicit
successare equivalent. The same key with a different scenario returns409. - Search, billers, catalog, quote, reads and refunds 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). - Timing is approximate and not a guarantee. A pending item may show
fulfillment.progresswith codeCONFIRMING_OUTCOME. By default Sandbox fulfillment takes a few seconds, during whichGET /v1/orders/{id}shows the item aspending. - The delivered value in a successful result is confirmed test data, not a copy of the purchased value.
Sandbox catalog
The Sandbox catalog covers 35 countries with 95 services, 190 billers and 760 offers. Each service has one fixed biller with seven offers and one range biller with one offer. Names, categories and currencies follow real catalog entries, and amounts, steps, inputs and prices are synthetic. Do not hardcode offer ids: search, billers and the catalog return them. A valid country without fixtures returns an empty items array, not an error.
Test values:
accountNumber:001234567mobileNumberandbeneficiaryMobileNumber:+994501234567. A value such as00 994 (50) 123-45-67normalizes to the same number.
Azerbaijan has test billers that cover each delivery shape:
| Biller | Category / service type | Delivery | Offers | Required input |
|---|---|---|---|---|
| AZ Electricity (fixed) | electricity / postpaid | directCredit | seven fixed values | accountNumber |
| AZ Electricity (range) | electricity / postpaid | directCredit | one range | mobileNumber |
| AZ Water (fixed) | water / prepaid | token | seven fixed values | beneficiaryMobileNumber |
| AZ Water (range) | water / prepaid | token | one range | accountNumber |
| AZ Gas | gas / postpaid | directCredit | seven fixed values and one range | accountNumber and mobileNumber |
| AZ Internet PIN | internet / prepaid | token | seven fixed packages and one range | none |
- The fixed AZ values are 10, 20, 40, 60, 100, 150 and 200 AZN. The AZ ranges run from 20 to 200 AZN in steps of 5.
- Find AZ Gas with
GET /v1/utility/search?countryCode=AZ&category=gas&serviceType=postpaid. Quote its range at 50 AZN with bothaccountNumberandmobileNumber. A successful order credits the test account and issues no token. - Find the AZ Internet PIN services with
GET /v1/utility/search?countryCode=AZ&category=internet&q=AZ%20Internet%20PIN. Its packages are 5, 10, 15, 20, 25, 50 and 100 USD, and its range accepts 5 to 100 USD in steps of 1, with onlyinputs.valuerequired. A successful order issues a test token. - Invoice payment flows are not enabled in Sandbox. An input an offer does not list, including
invoiceId, isNOT_ALLOWED.
Errors
Paths below are for the items[] bodies. They are prefixed with items[i]. on quote, order and the shared order.
| Status / code | When | Path (reason) |
|---|---|---|
400 / 10001 | A listed input is missing, not allowed, or malformed | inputs.<name> (REQUIRED, NOT_ALLOWED or INVALID_VALUE) |
400 / 10001 | A range offer without inputs.value | inputs.value (REQUIRED) |
400 / 10001 | inputs.value outside the published range, off its step, or not the fixed offer's amount | inputs.value.amount (INVALID_VALUE) |
400 / 10001 | inputs.value in another currency than the offer's | inputs.value.currency (CURRENCY_MISMATCH) |
400 / 10001 | inputs.maxPrice in another currency than the order's | inputs.maxPrice.currency (CURRENCY_MISMATCH) |
400 / 10001 | An amount not above 0 or with too many decimals, or a currency that is not three letters | inputs.value.amount, inputs.maxPrice.amount, inputs.value.currency, inputs.maxPrice.currency (INVALID_VALUE) |
400 / 10001 | quantity other than 1, or no items or more than 5 | quantity (INVALID_VALUE), items |
400 / 10001 | A value or maxPrice beside inputs, or any unknown member | the field path (INVALID_VALUE) |
400 / 10001 | Unknown query parameter, invalid filter, or a catalog cursor issued for other filters or another currency | the parameter |
400 / 11004 | Unknown or malformed publicId, a biller id, or an offer of another product | items[i] (EXPIRED_OR_INVALID) |
409 / 11003 | The offer cannot be sold now, or no range sells an amount on a combined range | items[i] (UNAVAILABLE) |
409 / 11002 | The current price is above inputs.maxPrice | inputs.maxPrice (PRICE_CHANGED) |
404 / 10004 | billers/{id} with an unknown id, an id that does not start with biller_, or a biller with no orderable offer | none |
403 / 10003 | Utility is not enabled for your account, or the key lacks the manage permission | service (SERVICE_NOT_ENABLED) |
503 / 10007 | The service or the price calculation is temporarily unavailable. Nothing is charged. | none |
Where an error path starts depends on the request. On quote and the product order, an unknown member inside inputs is reported as $.items[i].inputs.<member>, and a member beside inputs as $.items[i].<member>. The mixed POST /v1/orders reports a member inside inputs as items[i].inputs.<member>.
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.