Skip to Content
OpenRoam Docs
Utility

Get a biller

Returns one biller with its offers, in the item shape that search returns.

GET
/v1/utility/billers/{id}

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.

Authorization

PartnerApiKey
headerX-Partner-Key<token>

Partner API Key (X-Partner-Key)

Path Parameters

id*string

The biller's opaque id from search or the catalog, for example biller_3jx4….

Query Parameters

currency?string

Price currency, three letters in either case; the API key's currency when omitted. An unsupported code gives 400 / 10001 at currency, reason NOT_SUPPORTED.

Response Body

OK

  1. 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*string
name*string
countryCode*string
category*string

The kind of bill a biller collects.

Value in"other""electricity""water""television""internet""gas""toll""voip""landline"
logoUrl?string|null
description?string|null
offers*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.

Example Request
curl -X GET 'https://api.sandbox.openroam.com/v1/utility/billers/biller_3jx464dkw4ekdjgj4qxuib5wki?currency=USD'
Example Response
{  "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.