Pay a bill

Pay a utility, airtime or tax bill from the business wallet. This raises a payout, so everything that governs a payout governs this: the funds are reserved, the approval thresholds apply, the per-tier and per-day limits apply, and the destination is screened. A bill above the threshold comes back `awaiting_approval` and pays nobody until it is signed.

Pay a utility, airtime or tax bill from the business wallet.

This raises a payout, so everything that governs a payout governs this: the funds are reserved, the approval thresholds apply, the per-tier and per-day limits apply, and the destination is screened. A bill above the threshold comes back awaiting_approval and pays nobody until it is signed.

Authorization

OAuth2PasswordBearer

AuthorizationBearer <token>

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

idempotency_key*Idempotency Key

Your reference for this attempt. Send the same key again and you get the original bill back, not a second payment.

Length8 <= length <= 128

Example"office-power-2026-08"

service_type*Service Type

electricity, airtime, paytv or tax. From GET /bill-payments/catalog, which is the same list the consumer app sells.

Lengthlength <= 32

Example"electricity"

provider*Provider

The biller, from the catalogue — REG for electricity, MTN, Airtel or Tigo for airtime, StarTimes for pay TV, RRA for tax.

Lengthlength <= 64

Example"REG"

account_number*Account Number

What the payer types: a meter number, a phone number, a smartcard number or a declaration number, depending on the biller. Validated against the biller before anything is reserved, and the name it returns becomes the payout's recipient_name.

Length1 <= length <= 64

Example"04123456789"

amount_minor*Amount Minor

In minor units — 50,000 RWF is 5000000. Never a decimal.

Range0 < value

Example5000000

currency*Currency

ISO 4217, three letters.

Length3 <= length <= 3

Example"RWF"

product?|

Where a biller sells more than one thing.

country_code?|

ISO 3166-1 alpha-2.

Example"RW"

note?|

Yours. Kept with the bill and shown on statements.

Example"Kigali office — August"

Response Body

`application/json`

curl -X POST "https://example.com/api/b/v1/bill-payments" \  -H "Content-Type: application/json" \  -d '{    "idempotency_key": "office-power-2026-08",    "service_type": "electricity",    "provider": "REG",    "account_number": "04123456789",    "amount_minor": 5000000,    "currency": "RWF"  }'

{  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",  "payout_id": "89e4daf5-d103-4869-b9da-3d54ecc98dfe",  "service_type": "string",  "provider": "string",  "product": "string",  "account_number": "string",  "customer_name": "string",  "amount_minor": 0,  "currency": "string",  "cashback_minor": 0,  "status": "pending",  "receipt_number": "string",  "token": "string",  "failure_reason": "string",  "created_at": "2019-08-24T14:15:22Z",  "completed_at": "2019-08-24T14:15:22Z"}

Authorization

Cookie Parameters

Request Body

Response Body

201application/json

400application/json

402application/json

422application/json

503application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`