RukaPay
RukaPay

Gateway API

Bank Transfer API

Bank payouts via PARTNER_SEND_BANK — ABC or Pegasus routing.

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

Send funds from your partner wallet to Ugandan bank accounts. Required fields: accountNumber, bankCode, accountName.

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_SEND_BANK",
    "amount": 500000,
    "currency": "UGX",
    "accountNumber": "9030012345678",
    "bankCode": "STANBIC",
    "accountName": "John Doe",
    "narration": "Vendor payment",
    "partnerReference": "VENDOR-PAY-88"
  }'
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_BANK",
  "amount": 50000,
  "currency": "UGX",
  "narration": "Payment description",
  "partnerReference": "PARTNER-REF-123456",
  "accountNumber": "1234567890",
  "bankCode": "STANBIC",
  "accountName": "John 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

Bank transfer initiated.

400

Bad Request

Invalid bank details or insufficient balance.

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.