Search billers
Searches the billers of a country and returns them with their offers, one page at a time.
Searches the billers of a country and returns them with their offers, one page at a time.
Returns { items, pagination }. countryCode is required; category, serviceType and
q select billers. Utility has no value or price filter. Pages count billers that still have an offer,
and prices are indicative, in currency. Quote and order take an offer's publicId, never the
biller's id. An invalid or unknown parameter gives 400 / 10001; an unsupported currency gives
404 / 10004.
PartnerApiKeyX-Partner-Key<token>Partner API Key (X-Partner-Key)
countryCode*stringRequired ISO 3166-1 alpha-2 country code of the billers, in either case.
category?stringKeep the billers of this category, for example electricity.
"other""electricity""water""television""internet""gas""toll""voip""landline"serviceType?stringKeep prepaid or postpaid billers.
"prepaid""postpaid"q?stringText in the biller name, case-insensitive; at most 100 characters, without control characters.
currency?stringPrice currency, three letters in either case; the API key's currency when omitted. An unsupported code gives 400 / 10001 at currency, reason NOT_SUPPORTED.
page?integerPage number, from 1; default 1.
int32limit?integerPage size, 1 to 100; default 10.
int32OK
- response
A page of billers; pagination.totalCount counts billers that still have an offer after filtering.
items*array<>pagination*Paging of a list response.
curl -X GET 'https://api.sandbox.openroam.com/v1/utility/search?countryCode=AZ&category=other&serviceType=prepaid¤cy=USD&page=1&limit=10'{ "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." }, { "name": "invoiceId", "type": "text", "required": true, "description": "The ID of the bill to pay, as the biller issued it." } ] } ], "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 }}Quote utility payments POST
Prices the order body with current prices, without placing an order. Takes the same body as order, with offer public IDs; a biller's own ID is not an offer (400 / 11004). Each item is priced on its own, in request order; the first failing item aborts the quote and is named at `items[i]`, for example 409 / 11002 at `items[i].inputs.maxPrice` when the current price is above it. A quote reserves nothing, does not expire, submits no payment and does not check the customer's account with the biller.
Order gift cards POST
Places a gift card 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. Order with the `publicId` a quote returned. Every price is recalculated: a current price above `inputs.maxPrice` gives 409 / 11002 at `items[i].inputs.maxPrice` before anything is charged. Each card of an item's `quantity` becomes its own order item; read the codes from 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.