Skip to main content

​
Collect payments with Relworx

RELWORX collects mobile money through the Relworx aggregator. Centipid Billing posts a request, the payer authorizes it on their handset, and Relworx confirms the result on a signed webhook. Offered in the country catalog for Kenya (KE) and Tanzania (TZ).

​
Before you start

  1. Complete Relworx merchant onboarding in an account owned by the ISP.
  2. From the Relworx dashboard collect the account number (shown as account_no), the API key, and the webhook signing key.
  3. Confirm your workspace has a public HTTPS domain — Relworx must reach the callback, and the callback is what completes a payment.

​
Configure the gateway

1

Open Settings → Payments → Relworx

Select Relworx from the payment marketplace.
2

Enter the account number

Relworx account number (required) is the account_no from your dashboard, not your merchant name.
3

Enter the API key

Relworx API key (required) authenticates outgoing payment requests.
4

Enter the webhook signing key

Webhook signing key (required, stored as a secret) verifies callbacks. Get it exactly right — see the warning below.
5

Run a controlled test payment

Pay a small amount from the captive portal and confirm both halves: the prompt arrives, and the payment appears in the ledger. A prompt that succeeds while the ledger stays empty means the webhook is being rejected.

​
Credentials

​
Callback URLs

Settings → Payments shows https://<your-host>/api/payments/relworx/callback. Register it in your Relworx dashboard.
Every callback must carry a valid Relworx-Signature. Centipid Billing recomputes an HMAC-SHA256 over the URL, the timestamp, and the reference and status fields, using your webhook signing key, and rejects the callback with HTTP 400 if it does not match — or if its timestamp is more than 10 minutes from now.A wrong signing key therefore fails silently in the worst possible way: payers are charged and never provisioned, because every confirmation is rejected. If test payments prompt but never land, suspect this key first.

​
What the payer must provide

A mobile money number. It is normalized to international format using your account’s country before it is sent — numbers that cannot be normalized are refused before any request reaches Relworx. The currency is taken from the payment, then your configured currency, then your country (UG → UGX, KE → KES, TZ → TZS). If none resolves to a three-letter code, the request is refused rather than sent in the wrong currency.

​
How a payment completes

1

Request

Centipid Billing posts the request to the Relworx API (v2), with a short timeout and two retries.
2

Authorization

The payer approves on their handset. The local transaction stays in progress.
3

Confirmation

Relworx calls the signed webhook. The signature is verified, the transaction matched on its customer or internal reference, and the payment recorded.

​
Troubleshooting

For every gateway’s fields in one place, see the credential reference.