# Utility bill payments (/docs/products/utility)

## What you can sell [#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 [#the-flow]

<Steps>
<Step>
### Search [#search]

[`GET /v1/utility/search`](/docs/api-reference/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}`](/docs/api-reference/utility/get-biller) returns one biller in the shape search returns.
- [`GET /v1/utility/catalog`](/docs/api-reference/utility/get-catalog) walks every biller in id order, page by page with a cursor. `countryCode` is 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`).
</Step>

<Step>
### Quote [#quote]

[`POST /v1/utility/quote`](/docs/api-reference/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.
</Step>

<Step>
### Order [#order]

[`POST /v1/utility/order`](/docs/api-reference/utility/create-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}`](/docs/api-reference/orders/get-by-id). See [Idempotency](/docs/idempotency) and [Orders](/docs/orders).
</Step>
</Steps>

You can also pay bills together with other products through [`POST /v1/orders`](/docs/api-reference/orders/create-order), where each item adds `productType: "utility"`.

## Search [#search-1]

```bash
curl "https://api.sandbox.openroam.com/v1/utility/search?countryCode=AZ" \
  -H "X-Partner-Key: $OPENROAM_API_KEY"
```

```json
{
  "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 [#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 [#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 [#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 [#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 `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]

Quote and order take the same body. The fixed offer below is bought without a value, and the range offer at 50 AZN:

```json
{
  "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" }
      }
    }
  ]
}
```

```bash
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:

```json
{
  "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 [#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.

```json
{
  "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}`](/docs/api-reference/orders/get-by-id). The [`order.fulfillment.updated` webhook](/docs/api-reference/webhooks/order-fulfillment-updated) carries the same `result`. See [Webhooks](/docs/webhooks) and [Orders](/docs/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 [#testing-in-sandbox]

Use [Sandbox](/docs/environments) 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 [#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. |

```bash
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 [#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:

| 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 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 [#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`](/docs/api-reference/account/get-services). Idempotency errors are shared across products; see [Idempotency](/docs/idempotency). For the common error format, see [Errors](/docs/errors).

## Next steps [#next-steps]

- [Quickstart](/docs/quickstart) for your first order.
- [Authentication](/docs/authentication) and [Environments](/docs/environments) for keys and hosts.
- [Orders](/docs/orders) for order and item status.
- [Webhooks](/docs/webhooks) for signing and retries.