Skip to Content
OpenRoam Docs

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

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:

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

  • id is the biller's opaque token, starting with biller_. It names the biller, not something to buy. Quote and order take an offer's publicId. Sending a biller id, or any malformed id, as a publicId gives 400 / 11004.
  • countryCode is the biller's ISO 3166-1 alpha-2 country and is never null.
  • category is one of the values above. A category OpenRoam does not map is other.
  • details.serviceType is prepaid or postpaid. details.deliveryType is token or directCredit.
  • billers/{id} returns 404 / 10004 for an unknown id, an id that does not start with biller_, and a biller without an orderable offer. Search does not list such billers either.
  • A search page holds fewer billers than limit when some billers on it cannot be priced. pagination.totalCount counts 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.

  • publicId is an opaque token starting with utility_. 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.
  • name is the stored label of a package or fixed amount when one exists, for example Local tier. Otherwise it is built from the biller and the value, such as Fixed postpaid 40 AZN or Range prepaid 20–200 AZN.
  • value is in the currency the biller is paid in: { type: "fixed", amount, currency } or { type: "range", min, max, step, currency }. A range's max is 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.
  • price is indicative and in the requested currency. A range's price is { min, max, currency }, the price of its minimum and maximum value, and price.max is null when value.max is. 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 min is the lowest minimum and its max the highest maximum. An amount must be on the published range and step. An amount on that grid that none of the underlying ranges sells gives 409 / 11003 at items[i]. An amount outside the published range gives 400 / 10001 (INVALID_VALUE).

Required inputs

requiredInputs lists the customer inputs an offer takes. Each listed input is required.

nametypeListed when the biller needs
accountNumbertextThe customer's account or meter number.
mobileNumberphoneThe customer's mobile number with the biller.
beneficiaryMobileNumberphoneThe mobile number of the person who receives the payment.
invoiceIdtextThe 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 phone value must be an international number starting with + or 00. Spaces, hyphens and brackets are removed, and 00 becomes +. Bare digits such as 994501234567 are rejected with INVALID_VALUE at items[i].inputs.mobileNumber (or beneficiaryMobileNumber), because OpenRoam does not guess the country.
  • A listed input the item leaves out is REQUIRED at items[i].inputs.<name>. An input the offer does not list is NOT_ALLOWED at the same path, before any purchase is attempted.
  • An offer can list no inputs, for example a PIN product. inputs may then be omitted, unless the offer is a range, which needs inputs.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.json

Quote 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. quantity must be 1.
  • currency is 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.
  • referenceId is your own reference. Quote validates it and ignores it.
  • publicId in 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 REQUIRED at items[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) at items[i].inputs.value.amount. A value in another currency is CURRENCY_MISMATCH at items[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 with 409 / 11002 at items[i].inputs.maxPrice and 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:

deliveryTypefulfillment.status becomes fulfilled whenresult.details.token
tokenThe payment is confirmed and a usable token is returned, such as a prepaid meter token or a PIN.The token
directCreditThe 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:

  • name is the purchase name. countryCode is the biller's country. logoUrl is always null on the item, so read the logo from the biller. value is the amount paid to the biller.
  • inputs echoes accountNumber, mobileNumber, beneficiaryMobileNumber and invoiceId, and an input the item did not store is null. Masking:
    • accountNumber and invoiceId are masked as *** followed by the last four characters. A value of four characters or fewer is shown as ***.
    • mobileNumber and beneficiaryMobileNumber are masked as a plus sign, the country code, *** and the last four digits.
    • value and maxPrice are not echoed. The amount is purchasedProduct.value.
  • details has serviceType and deliveryType. It reads unknown for items bought before the delivery type was stored.

fulfillment.result:

  • deliveredValue is the amount confirmed as received by the customer. It is null until confirmed and is never copied from purchasedProduct.value. A later confirmation sends another order.fulfillment.updated webhook with a higher fulfillmentVersion.
  • details.token is the token of a token biller 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:

ValueResult
Omitted or successConfirmed delivery. A directCredit item has no token. A token item returns a code starting with SANDBOX-NONREDEEMABLE-, which cannot pay a real bill.
fulfillment.rejectedA definitive rejection, with no delivered value and no token. The item 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/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 success are equivalent. The same key with a different scenario returns 409.
  • 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 returns 400 / 10001 (INVALID_VALUE).
  • 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, during which GET /v1/orders/{id} shows the item as pending.
  • 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: 001234567
  • mobileNumber and beneficiaryMobileNumber: +994501234567. A value such as 00 994 (50) 123-45-67 normalizes to the same number.

Azerbaijan has test billers that cover each delivery shape:

BillerCategory / service typeDeliveryOffersRequired input
AZ Electricity (fixed)electricity / postpaiddirectCreditseven fixed valuesaccountNumber
AZ Electricity (range)electricity / postpaiddirectCreditone rangemobileNumber
AZ Water (fixed)water / prepaidtokenseven fixed valuesbeneficiaryMobileNumber
AZ Water (range)water / prepaidtokenone rangeaccountNumber
AZ Gasgas / postpaiddirectCreditseven fixed values and one rangeaccountNumber and mobileNumber
AZ Internet PINinternet / prepaidtokenseven fixed packages and one rangenone
  • 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 both accountNumber and mobileNumber. 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 only inputs.value required. A successful order issues a test token.
  • Invoice payment flows are not enabled in Sandbox. An input an offer does not list, including invoiceId, is NOT_ALLOWED.

Errors

Paths below are for the items[] bodies. They are prefixed with items[i]. on quote, order and the shared order.

Status / codeWhenPath (reason)
400 / 10001A listed input is missing, not allowed, or malformedinputs.<name> (REQUIRED, NOT_ALLOWED or INVALID_VALUE)
400 / 10001A range offer without inputs.valueinputs.value (REQUIRED)
400 / 10001inputs.value outside the published range, off its step, or not the fixed offer's amountinputs.value.amount (INVALID_VALUE)
400 / 10001inputs.value in another currency than the offer'sinputs.value.currency (CURRENCY_MISMATCH)
400 / 10001inputs.maxPrice in another currency than the order'sinputs.maxPrice.currency (CURRENCY_MISMATCH)
400 / 10001An amount not above 0 or with too many decimals, or a currency that is not three lettersinputs.value.amount, inputs.maxPrice.amount, inputs.value.currency, inputs.maxPrice.currency (INVALID_VALUE)
400 / 10001quantity other than 1, or no items or more than 5quantity (INVALID_VALUE), items
400 / 10001A value or maxPrice beside inputs, or any unknown memberthe field path (INVALID_VALUE)
400 / 10001Unknown query parameter, invalid filter, or a catalog cursor issued for other filters or another currencythe parameter
400 / 11004Unknown or malformed publicId, a biller id, or an offer of another productitems[i] (EXPIRED_OR_INVALID)
409 / 11003The offer cannot be sold now, or no range sells an amount on a combined rangeitems[i] (UNAVAILABLE)
409 / 11002The current price is above inputs.maxPriceinputs.maxPrice (PRICE_CHANGED)
404 / 10004billers/{id} with an unknown id, an id that does not start with biller_, or a biller with no orderable offernone
403 / 10003Utility is not enabled for your account, or the key lacks the manage permissionservice (SERVICE_NOT_ENABLED)
503 / 10007The 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

On this page