Initiate Bill Payment

POST

http://localhost:8080/api/v3/transactions/pay-bill

POST

/api/v3/transactions/pay-bill

curl -X POST http://localhost:8080/api/v3/transactions/pay-bill \
     -H "Authorization: Bearer {{accessToken}}" \
     -H "Idempotency-Key: idem-{{$guid}}" \
     -H "X-Device-Id: {{deviceId}}" \
     -H "X-Request-Id: {{requestId}}" \
     -H "X-Signature: {{signature}}" \
     -H "X-Timestamp: {{timestamp}}"

{
  "code": 200,
  "message": "Payment initiated.",
  "data": {
    "transactionId": "3c4d5e6f-7a8b-4c9d-8e0f-1a2b3c4d5e70",
    "walletId": "b1e7f6a0-9d2b-4a5b-9c3d-1a2b3c4d5e6f",
    "amount": 1250,
    "fee": 0,
    "category": "UTILITY_BILL",
    "destination": "1234567890",
    "status": "INITIATED",
    "reference": "UTL7K3M9QX",
    "timestamp": "2026-10-07 13:00:00",
    "dueAmount": 1250,
    "dueDate": "2026-10-15"
  }
}

Starts a bill payment from walletId (a PERSONAL or BUSINESS wallet). The body takes one of two shapes:

Biller from the catalogue: billProviderId + accountNumber. The biller’s payment method decides the route: CHOICE_BILL billers are paid through Choice’s bill payment service (category UTILITY_BILL, with dueAmount/dueDate from Choice), and MPESA_PAYBILL billers go out as an M-Pesa Paybill payment to the biller’s business number. category/shortCode/referenceNumber must be absent.
Manual M-Pesa Paybill/Till: no billProviderId; category is MPESA_PAYBILL (requires referenceNumber) or MPESA_TILL, and shortCode is the paybill/till number.

description is only passed to M-Pesa payments. dueAmount/dueDate are null for M-Pesa payments. Next step: Confirm Bill Payment with the returned transactionId.

Headers

Request

This endpoint expects an object.

walletIdstringOptional

amountintegerOptional

billProviderIdstringOptional

accountNumberstringOptionalformat: "utc-millisec"

Response

200 OK (Catalogue Biller, Choice Bill Payment)

codeintegerOptional

messagestringOptional

dataobjectOptional

Errors

400

Bad Request Error