# RukaPay

> Collect Ugandan MTN and Airtel mobile money with RukaPay: the payer approves a PIN prompt on their phone. Covers the API key, the callback and the errors.

Source: https://docs.centipidbilling.com/billing/payment-gateways/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](https://developer.rukapay.co.ug/collections/):

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

#### 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.

#### 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.

#### 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.
