Skip to content

RukaPay

Collect payments with RukaPay

RUKAPAY collects by wallet push. The payer enters their number on the portal, a PIN prompt appears on their phone, and they approve it there. They never leave the portal page.

Offered in the country catalog for Uganda (UG), in Ugandan shillings, for MTN and Airtel numbers and payments of UGX 100 or more. An ISP that prices in another currency is refused at checkout, so a USD 10 plan is never charged as UGX 10.

Centipid Billing uses two calls from RukaPay’s Gateway API:

  1. POST /process-transfer (PARTNER_COLLECT_MNO) sends the PIN prompt.
  2. GET /transactions/{partnerReference}/status reports whether it was paid.

Nothing is credited until the status reads SUCCESS.

Configure the gateway

  1. Get a live API key from RukaPay

    Open a RukaPay partner account and copy the live API key from the partner dashboard. Use the live key: Centipid talks only to RukaPay’s live host.

  2. Open Settings → Payments → RukaPay in Centipid

    Enter the API key. There is no URL to paste into RukaPay: Centipid sends its callback URL with each payment.

  3. Run a controlled test payment

    Pay UGX 500 from the captive portal, approve the prompt on the phone, and confirm the payment reaches the ledger.

Credentials

Field Required Notes
API key Yes Sent in the x-api-key header from Centipid’s servers only.

Callback

Each payment carries /api/rukapay/callback on the ISP’s domain as its callback URL, so a domain change needs nothing in RukaPay. RukaPay does not sign its callbacks, so Centipid never credits from one: the callback only makes Centipid ask RukaPay for the payment’s status sooner. Centipid also checks the status every 5 seconds for about 3 minutes after the prompt is sent.

Troubleshooting

  • “Unable to send the RukaPay payment prompt”: RukaPay refused the request, usually because the API key is wrong or revoked. Its exact response is in the application log.
  • “Enter a Ugandan mobile number”: the number is not an MTN or Airtel 2567… number.
  • “RukaPay takes payments of UGX 100 or more”: the plan costs less than RukaPay’s minimum.
  • “RukaPay bills in UGX here”: the ISP’s prices are in another currency. Contact Centipid support to change it.