Get a biller
Returns one biller with its offers, in the item shape that search returns.
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.
PartnerApiKeyX-Partner-Key<token>Partner API Key (X-Partner-Key)
id*stringThe biller's opaque id from search or the catalog, for example biller_3jx4….
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.
OK
- response
One biller as search, the one-biller route and the catalog return it. id is the biller's opaque
public token; an order names one of its offers by public ID. Prices are indicative; quote
recalculates them.
id*stringname*stringcountryCode*stringcategory*stringThe kind of bill a biller collects.
"other""electricity""water""television""internet""gas""toll""voip""landline"logoUrl?string|nulldescription?string|nulloffers*array<>details*Biller facts outside the item keys every partner service shares: serviceType is prepaid or
postpaid, and deliveryType says what a paid bill delivers, a token (such as a prepaid
meter token or a PIN) or a directCredit to the biller.
curl -X GET 'https://api.sandbox.openroam.com/v1/utility/billers/biller_3jx464dkw4ekdjgj4qxuib5wki?currency=USD'{ "id": "string", "name": "string", "countryCode": "string", "category": "other", "logoUrl": "string", "description": "string", "offers": [ { "publicId": "string", "name": "string", "description": "string", "value": { "amount": 0, "currency": "string", "type": "fixed" }, "price": { "amount": 0, "currency": "string" }, "requiredInputs": [ { "name": "string", "type": "text", "required": true, "description": "string", "fields": [ {} ] } ] } ], "details": { "serviceType": "prepaid", "deliveryType": "unknown" }}Pay utility bills POST
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.
Utility catalog GET
Returns every biller with its offers, page by page, for partner inventory. Returns `{ items, nextCursor }`, ordered by biller ID, with the search filters except `q`. Continue with `nextCursor` as `cursor`, the same filters and the same `currency` until it 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. The walk is not a frozen snapshot: update your copy by biller `id`, and remove a biller only when a complete walk did not return it. On 429, wait for `Retry-After` and request the same page again.