RukaPay
RukaPay

Gateway API

Transaction Status

Query transaction status by RukaPay ID, partnerReference, reference, or externalReference.

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

Use callbacks (callbackUrl) for real-time updates. Poll status when you need to reconcile or recover from missed webhooks.

Status values

SUCCESS

Transaction completed successfully.

PENDING

Awaiting customer approval or provider processing.

FAILED

Transaction failed. See failureReason or callback errorMessage.

PROCESSING

Transaction is being processed by the payment network.

Example response

Status response
{
  "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"
  }
}
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.

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": "256700000000",
  "mnoProvider": "MTN",
  "recipientName": "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

Transfer accepted (may be PENDING for async flows).

400

Bad Request

Validation error, insufficient balance, or duplicate partnerReference.

401

Unauthorized

Invalid or missing x-api-key.

429

Too Many Requests

Rate limit exceeded.