Skip to main content

​
Collect payments with Monnify

MONNIFY uses a hosted checkout offering bank transfer, card, and USSD. Centipid Billing initializes a transaction, sends the payer to Monnify’s checkout page, and confirms the result on a signed webhook that is re-verified against Monnify before anything is credited. Offered in the country catalog for Nigeria (NG).

​
Before you start

  1. Complete Monnify merchant onboarding in an account owned by the ISP.
  2. From the Monnify dashboard collect the API key, the secret key, and the contract code.
  3. Decide whether you are configuring Live or Sandbox — they are different hosts, and credentials are not interchangeable.
  4. Plan the walled garden: the payer’s browser must reach Monnify’s checkout page, so a Hotspot subscriber who is not yet online cannot pay unless Monnify is reachable pre-authentication.

​
Configure the gateway

1

Open Settings → Payments → Monnify

Select Monnify from the payment marketplace.
2

Enter the API key and secret key

Both are required and stored as secrets. The secret key does double duty: it authenticates requests and signs the webhook Monnify sends back.
3

Enter the contract code

Contract code (required) identifies the contract the money settles against.
4

Choose the environment

Environment is Live or Sandbox. Live requests go to https://api.monnify.com, sandbox to https://sandbox.monnify.com.
5

Register the webhook

See Callback URLs below.
6

Run a controlled test payment

Pay a small amount from the captive portal on an unauthenticated device, and confirm the payment reaches the ledger.

​
Credentials

The API key, secret key, and contract code gate the switch; the environment does not, so check it deliberately.

​
Callback URLs

Register the webhook URL in the Monnify dashboard. The redirect is where the payer’s browser returns after checkout.
Webhooks carry an HMAC-SHA512 monnify-signature computed with your secret key. A wrong secret key means every webhook is rejected with HTTP 400, so payers are charged and never provisioned.

​
What the payer must provide

Whatever the Monnify checkout page asks for — card, bank transfer, or USSD. The payer’s name and email are sent with the request when known; when no email is available a placeholder is sent so the transaction can be initialized, so do not rely on the email shown in Monnify to identify a subscriber. The currency is your account’s configured currency, defaulting to NGN.
Amounts are sent in naira, not kobo. Monnify does not use the smallest unit here, so the ledger amount and the Monnify amount should match exactly — a factor-of-100 difference means something is wrong, not a unit convention.

​
How a payment completes

1

Initialize

Centipid Billing authenticates, initializes the transaction with the amount, reference, and contract code, and receives a checkout URL. A pending row is written against the payment reference.
2

Payment

The payer completes the payment on Monnify’s page.
3

Confirmation

Monnify posts the signed webhook. The signature is validated, the result is then re-verified against the Monnify API, and only then is the payment recorded and the package applied. Repeated webhooks are ignored rather than double-credited.

​
Troubleshooting

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