RukaPay
RukaPay

Gateway API

Collections API

Collect payments from MTN and Airtel using transactionMode PARTNER_COLLECT_MNO on POST /api/v1/gateway/process-transfer.

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

Mobile money collections debit the customer's phone and credit your partner wallet. The customer receives a USSD/push prompt to approve. You must supply callbackUrl — collections fail validation without it.

mnoProvider can be auto-detected from phoneNumber if omitted. Providers: MTN, AIRTEL.

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_COLLECT_MNO",
  "amount": 50000,
  "currency": "UGX",
  "phoneNumber": "256700000000",
  "mnoProvider": "MTN",
  "narration": "Invoice payment #1001",
  "partnerReference": "PARTNER-REF-123456",
  "callbackUrl": "https://your-app.com/webhooks/rukapay"
}'
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.

phoneNumber
string

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

mnoProvider
string

MTN or AIRTEL. Aliases: network.

callbackUrl
string

Webhook URL. Required for PARTNER_COLLECT_MNO.

metadata
object

Custom data returned in partner callback.

Request example

JSON
{
  "transactionMode": "PARTNER_COLLECT_MNO",
  "amount": 50000,
  "currency": "UGX",
  "narration": "Payment description",
  "partnerReference": "PARTNER-REF-123456",
  "phoneNumber": "256700000000",
  "mnoProvider": "MTN",
  "callbackUrl": "https://your-app.com/webhooks/rukapay"
}

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

Collection initiated (status may be PENDING until customer approves).

400

Bad Request

Missing callbackUrl or invalid phone number.

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.