Gateway API

Bill Payment API

Pay utilities and subscriptions with PARTNER_PAY_BILL_PAYMENT.

Development / sandbox: use -sandbox endpoints

On https://dev-api.rukapay.net (dev), do not call the production paths. Use the full sandbox URLs below — same request body, simulated responses, no real money movement.

Validate beneficiary: https://dev-api.rukapay.net/api/v1/gateway/validate-beneficiary-sandbox
Process transfer: https://dev-api.rukapay.net/api/v1/gateway/process-transfer-sandbox

Environments — full examples →

Overview

Bill payments use billerCode (e.g. NWSC, UMEME, URA) and customer accountNumber. Aliases biller_code and account_number are accepted.

Two-step flow

Validate — call POST /validate-beneficiary with billerCode and accountNumber to confirm the account and retrieve beneficiary.name, customerType (UMEME), or area (NWSC).
Pay — call POST /process-transfer with the amount, customerName (from validate), a real Uganda phoneNumber, and any biller-specific fields echoed from the validate response.

Biller examples

Select a biller to see validate and pay request examples. Each biller has different required fields on the pay step.

UMEME — Uganda Electricity Distribution Company · Sandbox test account: 1111222233

Step 1 — Validate account

Production

curl -X POST https://api.rukapay.net/api/v1/gateway/validate-beneficiary \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "transactionMode": "PARTNER_PAY_BILL_PAYMENT",
  "billerCode": "UMEME",
  "accountNumber": "1111222233"
}'

On sandbox use validate-beneficiary-sandbox instead.

Step 2 — Pay bill

Production

curl -X POST https://api.rukapay.net/api/v1/gateway/process-transfer \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "transactionMode": "PARTNER_PAY_BILL_PAYMENT",
  "amount": 50000,
  "currency": "UGX",
  "billerCode": "UMEME",
  "accountNumber": "1111222233",
  "customerName": "Mary Nakato",
  "phoneNumber": "256770123456",
  "narration": "UMEME bill payment",
  "partnerReference": "BILL-UMEME-001",
  "customerType": "PREPAID"
}'

Required fields for UMEME

customerName — from validate response beneficiary.name
phoneNumber — real Uganda MSISDN (256XXXXXXXXX)
customerType — customerType must be PREPAID or POSTPAID — use the value returned by validate-beneficiary (beneficiary

Sandbox validate example

Sandbox

curl -X POST https://dev-api.rukapay.net/api/v1/gateway/validate-beneficiary-sandbox \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "transactionMode": "PARTNER_PAY_BILL_PAYMENT",
  "billerCode": "UMEME",
  "accountNumber": "1111222233"
}'

https://api.rukapay.net/api/v1/gateway/process-transfer

Request body

transactionModeRequired

string

PARTNER_PAY_BILL_PAYMENT

amountRequired

number

Amount in UGX (minimum 100).

currencyRequired

string

Currency code. Default UGX.

narrationRequired

string

Transfer description shown in records.

partnerReferenceRequired

string

Unique partner reference for idempotency and tracking.

billerCodeRequired

string

Biller code: NWSC, UMEME, URA, DSTV, GOTV, or STARTIMES. Alias: biller_code.

accountNumberRequired

string

Customer account or meter number. Alias: account_number.

customerNameRequired

string

Account holder name from validate-beneficiary (beneficiary.name). Aliases: accountName, recipientName.

phoneNumberRequired

string

Uganda MSISDN 256XXXXXXXXX. Dummy numbers such as 256700000000 are not allowed. Aliases: customer_phone, customerPhone.

customerType

string

Required for UMEME: PREPAID or POSTPAID (from validate). Aliases: area, meterNumber.

area

string

Required for NWSC: service area (e.g. Kampala). Valid values: Kampala, Entebbe, Jinja, Mukono, Iganga, Lugazi, Kawuku, Kajjansi, Others. Aliases: customerType, meterNumber.

walletType

string

ESCROW or COMMISSION. Default ESCROW.

metadata

object

Custom data returned in partner callback.

Request example

JSON

{
  "transactionMode": "PARTNER_PAY_BILL_PAYMENT",
  "amount": 50000,
  "currency": "UGX",
  "billerCode": "UMEME",
  "accountNumber": "1111222233",
  "customerName": "Mary Nakato",
  "phoneNumber": "256770123456",
  "narration": "UMEME bill payment",
  "partnerReference": "BILL-UMEME-001",
  "customerType": "PREPAID"
}

Response example

JSON

{
  "success": true,
  "message": "Transfer processed successfully",
  "transaction": {
    "transactionId": "cm5abc123xyz",
    "reference": "RKP-20260521-001",
    "amount": 50000,
    "fee": 1000,
    "totalCharged": 51000,
    "status": "SUCCESS",
    "recipient": {
      "name": "John Doe",
      "account": "256700000000",
      "provider": "MTN"
    },
    "createdAt": "2026-05-21T10:30:00.000Z"
  },
  "walletBalance": {
    "walletId": "wal_partner_escrow",
    "walletType": "ESCROW",
    "balanceBefore": 1000000,
    "balanceAfter": 949000,
    "currency": "UGX"
  }
}

Status codes

200

Bill payment processed or pending.

https://api.rukapay.net/api/v1/gateway/validate-beneficiary

Request body

transactionModeRequired

string

PARTNER_PAY_BILL_PAYMENT

billerCodeRequired

string

Biller code: NWSC, UMEME, URA, DSTV, GOTV, or STARTIMES. Alias: biller_code.

accountNumberRequired

string

Customer account or meter number. Alias: account_number.

Request example

JSON

{
  "transactionMode": "PARTNER_PAY_BILL_PAYMENT",
  "billerCode": "UMEME",
  "accountNumber": "1111222233"
}

Response example

JSON

{
  "success": true,
  "message": "Beneficiary validated successfully",
  "beneficiary": {
    "billerCode": "UMEME",
    "accountNumber": "1111222233",
    "name": "Mary Nakato",
    "customerType": "PREPAID",
    "area": "PREPAID",
    "isValid": true
  }
}

Status codes

200

Account validated.

https://api.rukapay.net/api/v1/gateway/transactions/{transactionIdOrReference}/status

Path parameters

transactionIdOrReferenceRequired

string

Transaction ID or your partnerReference.

Response example

JSON

{
  "success": true,
  "message": "Transaction found",
  "transaction": {
    "id": "cm5abc123xyz",
    "partnerReference": "PARTNER-REF-123456",
    "mnoId": "MTN-FIN-987654",
    "mnoTransactionId": "MTN-FIN-987654",
    "amount": 50000,
    "fee": 1000,
    "totalAmount": 51000,
    "currency": "UGX",
    "status": "SUCCESS",
    "destinationType": "MNO",
    "destination": { "phoneNumber": "256700000000", "provider": "MTN" },
    "createdAt": "2026-05-21T10:30:00.000Z",
    "completedAt": "2026-05-21T10:30:45.000Z"
  }
}

Status codes

200

Transaction found.

404

Not Found

TRANSACTION_NOT_FOUND.

Supported billers

Pass the biller code in billerCode. There is no list-billers endpoint — use the codes below.

Code	Biller	Extra pay fields	Sandbox account
`UMEME`	Uganda Electricity Distribution Company	`customerType`	`1111222233`
`NWSC`	National Water and Sewerage Corporation	`area`	`123456789`
`URA`	Uganda Revenue Authority	—	`2222333344`
`DSTV`	DSTV Pay-TV subscription	—	`3333444455`
`GOTV`	GOtv Pay-TV subscription	—	—
`STARTIMES`	StarTimes Pay-TV subscription	—	—

Bill Payment API

Overview

Two-step flow

Biller examples

Step 1 — Validate account

Step 2 — Pay bill

Pay bill

Request body

Request example

Response example

Status codes

Validate bill account

Request body

Request example

Response example

Status codes

Get transaction status

Path parameters

Response example

Status codes

Supported billers