Vodacom M-Pesa

Vodacom M-Pesa

VODACOM_MPESA collects through Vodacom’s M-Pesa Open API in the Democratic Republic of the Congo and Tanzania: a customer-to-business request is pushed to the payer’s M-Pesa wallet, the payer approves it on their handset, and Vodacom’s callback records the payment.

The country catalog offers it for the Democratic Republic of the Congo (CD) and Tanzania (TZ). Your account’s country picks the Vodacom market: DRC requests go to vodacomDRC, Tanzanian requests to vodacomTZN.

Before you start

1. Create an application on the Vodacom M-Pesa Open API portal under an account owned by the ISP, for your market (DRC or Tanzania).
2. Collect the API key, the public key, and the merchant code (the service provider code money is collected into).
3. DRC only: decide the currency subscribers pay in, Congolese franc (CDF) or US dollar (USD). Tanzania always settles in Tanzanian shillings (TZS).

Configure the gateway

1. Open Settings → Payments → Vodacom M-Pesa

   Select Vodacom M-Pesa from the payment marketplace.

2. Enter the merchant code

   Merchant code (required) is the service provider code payments are collected into.

3. Enter the API key and public key

   Both are required and stored as secrets. Leave a stored key blank when editing to keep it.

4. Choose the currency (DRC only)

   Currency is CDF unless you choose USD. Tanzanian ISPs don’t see this field; prompts are in TZS.

5. Register the callback URL

   Copy the callback URL shown on the page into your application on the Vodacom portal.

6. Run a controlled test payment

   Pay a small amount from the captive portal and confirm the prompt reaches the handset and the payment reaches the ledger.

Credentials

Field	Required	Notes
Merchant code	Yes	The service provider code money is collected into.
API key	Yes	Secret. From the Vodacom M-Pesa Open API portal.
Public key	Yes	Secret. Used to encrypt the session key on every request.
Currency	No	DRC only: CDF or USD; CDF when not set. Tanzania uses TZS.

The merchant code, API key, and public key gate the switch.

Callback URLs

The payment request carries no callback address, so register this one on the Vodacom portal:

https://<your ISP domain>/api/vodacom-mpesa/callback

It is shown on the gateway page, built from your primary domain. It is not updated by Centipid Billing after a domain change, so update it on the portal yourself.

How a payment completes

1. Session

   Centipid Billing fetches a session key and encrypts it with the configured public key.

2. Request

   A customer-to-business payment is pushed to the payer’s M-Pesa number, normalized to 243… (DRC) or 255… (Tanzania), for the merchant code.

3. Authorization

   The payer approves the prompt on their handset.

4. Confirmation

   Vodacom calls the callback URL, and the payment is recorded and the package applied. A repeated callback for the same transaction is ignored.

Requests go to Vodacom’s production Open API host for your market. There is no sandbox switch.

Troubleshooting

Symptom	What it means	What to do
“Vodacom M-Pesa credentials are incomplete. Please update the payment settings.”	The API key, public key, or merchant code is missing.	Complete all three in Settings → Payments → Vodacom M-Pesa.
“Unable to authenticate with Vodacom M-Pesa. Please try again.”	The session key could not be obtained.	Re-enter the API key; a rotated key is the usual cause.
“Vodacom M-Pesa session encryption failed.”	The stored public key could not encrypt the session key.	Paste the public key again in full; it is malformed or truncated.
“Unable to connect to Vodacom M-Pesa. Please try again later.”	The request could not connect.	Check outbound connectivity from the application host, then retry.
The payer approved but no payment appears	The callback did not arrive.	Confirm the callback URL on the Vodacom portal matches the one on the gateway page.

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