RukaPay
RukaPay

Gateway API

Payout API

Send money to MTN and Airtel wallets using PARTNER_SEND_MNO. Routed via ABC integration.

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

Payouts debit your partner ESCROW or COMMISSION wallet and credit the recipient's mobile money account. Minimum amount: 100 UGX.

Validate the recipient first with POST validate-beneficiary using the same transactionMode.

Example request

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

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_SEND_MNO",
  "amount": 25000,
  "currency": "UGX",
  "phoneNumber": "256700000001",
  "mnoProvider": "AIRTEL",
  "recipientName": "Jane Doe",
  "narration": "Salary payout",
  "partnerReference": "PAYROLL-042"
}'
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_SEND_MNO",
  "amount": 50000,
  "currency": "UGX",
  "narration": "Payment description",
  "partnerReference": "PARTNER-REF-123456",
  "phoneNumber": "256700000001",
  "mnoProvider": "AIRTEL",
  "recipientName": "Jane Doe"
}

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

Payout submitted.

400

Bad Request

INSUFFICIENT_BALANCE or validation error.

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

Request body

transactionModeRequired
string

PARTNER_SEND_MNO, PARTNER_SEND_BANK, PARTNER_PAY_BILL_PAYMENT, or PARTNER_PAY_AIRTIME.

phoneNumber
string

256XXXXXXXXX for MNO or airtime modes.

mnoProvider
string

MTN or AIRTEL.

accountNumber
string

Bank or bill account number.

bankCode
string

Required for PARTNER_SEND_BANK.

billerCode
string

Required for PARTNER_PAY_BILL_PAYMENT (e.g. NWSC).

Request example

JSON
{
  "transactionMode": "PARTNER_SEND_MNO",
  "phoneNumber": "256700000000",
  "mnoProvider": "MTN"
}

Response example

JSON
{
  "success": true,
  "message": "Beneficiary validated",
  "beneficiary": {
    "name": "John Doe",
    "phoneNumber": "256700000000",
    "provider": "MTN",
    "isValid": true
  }
}

Status codes

200

OK

Validation result returned.

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.