RukaPay
RukaPay

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) and customer accountNumber. Aliases biller_code and account_number are accepted on validate-beneficiary.

Example request

Authenticate with your secret API key. All requests are made over HTTPS to the RukaPay API base URL.

cURL
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": 85000,
    "currency": "UGX",
    "billerCode": "NWSC",
    "accountNumber": "04151234567",
    "narration": "Water bill",
    "partnerReference": "BILL-NWSC-001"
  }'
https://api.rukapay.net/api/v1/gateway/process-transfer

Request body

transactionModeRequired
string

Mode code e.g. PARTNER_SEND_MNO, PARTNER_COLLECT_MNO.

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.

walletType
string

ESCROW or COMMISSION. Default ESCROW.

phoneNumber
string

Uganda MSISDN 256XXXXXXXXX (MNO send/collect/airtime).

mnoProvider
string

MTN or AIRTEL. Aliases: network.

accountNumber
string

Bank or bill account number.

bankCode
string

Bank code e.g. STANBIC (bank send).

accountName
string

Account holder name (bank send).

recipientName
string

Recipient name (MNO send).

billerCode
string

Biller code e.g. NWSC, UMEME (bill payment).

callbackUrl
string

Webhook URL. Required for PARTNER_COLLECT_MNO.

metadata
object

Custom data returned in partner callback.

Request example

JSON
{
  "transactionMode": "PARTNER_PAY_BILL_PAYMENT",
  "amount": 50000,
  "currency": "UGX",
  "narration": "Payment description",
  "partnerReference": "PARTNER-REF-123456",
  "billerCode": "NWSC",
  "accountNumber": "04151234567"
}

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

OK

Bill payment processed or pending.

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

Request body

transactionModeRequired
string

PARTNER_PAY_BILL_PAYMENT

billerCodeRequired
string

e.g. NWSC, UMEME

accountNumberRequired
string

Customer account or meter number.

Request example

JSON
{
  "transactionMode": "PARTNER_PAY_BILL_PAYMENT",
  "amount": 50000,
  "currency": "UGX",
  "narration": "Payment description",
  "partnerReference": "PARTNER-REF-123456",
  "billerCode": "NWSC",
  "accountNumber": "04151234567"
}

Response example

JSON
{
  "success": true,
  "beneficiary": { "name": "Jane Customer", "accountNumber": "04151234567", "provider": "NWSC", "isValid": true }
}

Status codes

200

OK

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

OK

Transaction found.

404

Not Found

TRANSACTION_NOT_FOUND.