Getting Started

Integrate the RukaPay Gateway API — use -sandbox endpoints in development.

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

Production: https://api.rukapay.net/api/v1/gateway/validate-beneficiary · https://api.rukapay.net/api/v1/gateway/process-transfer

Environments — full examples →

Prerequisites

Active RukaPay gateway partner account
Sandbox API key for dev; live key for production
HTTPS endpoint for callbackUrl (required for collections)

Which endpoint should I use?

Environment	Process transfer	Validate beneficiary
Development	https://dev-api.rukapay.net/api/v1/gateway/process-transfer-sandbox	https://dev-api.rukapay.net/api/v1/gateway/validate-beneficiary-sandbox
Production	https://api.rukapay.net/api/v1/gateway/process-transfer	https://api.rukapay.net/api/v1/gateway/validate-beneficiary

Dev base URL: https://dev-api.rukapay.net · Production: https://api.rukapay.net

Transaction modes

Same transactionMode values for sandbox and production — only the URL path changes in dev.

transactionMode	Product	Description
PARTNER_SEND_MNO	Mobile Money Payout	Send money to MTN or Airtel mobile money wallets.
PARTNER_COLLECT_MNO	Mobile Money Collection	Collect payment from customer MTN/Airtel. Credits partner wallet. callbackUrl required.
PARTNER_SEND_BANK	Bank Transfer	Send money to a Ugandan bank account.
PARTNER_PAY_BILL_PAYMENT	Bill Payment	Pay utility and subscription bills (NWSC, UMEME, DSTV, etc.).
PARTNER_PAY_AIRTIME	Airtime Purchase	Purchase airtime on MTN or Airtel.

Integration steps

Get sandbox API keys — API Keys
Validate beneficiary (dev) — https://dev-api.rukapay.net/api/v1/gateway/validate-beneficiary-sandbox
Process transfer (dev) — https://dev-api.rukapay.net/api/v1/gateway/process-transfer-sandbox
Handle callback — POST to your callbackUrl on SUCCESS / FAILED
Go live — swap to production paths on api.rukapay.net

First request (development)

Example collection against https://dev-api.rukapay.net/api/v1/gateway/process-transfer-sandbox. Include callbackUrl for PARTNER_COLLECT_MNO.

curl -X POST https://dev-api.rukapay.net/api/v1/gateway/process-transfer-sandbox \
  -H "x-api-key: YOUR_SANDBOX_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"
}'

Production example

After testing, use the same body against /api/v1/gateway/process-transfer:

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"
}'

Explore

Environments — full sandbox vs production guide
Collections
Payouts