Kopo Kopo

Collect payments with Kopo Kopo

KOPOKOPO raises an M-Pesa STK prompt through Kopo Kopo’s Incoming Payments API, against your Kopo Kopo STK till. Money settles to the bank account attached to your Kopo Kopo account, typically the next business day.

Available to ISPs in Kenya (KE).

Before you start

1. Complete Kopo Kopo merchant onboarding in an account owned by the ISP.
2. From the Kopo Kopo dashboard collect the STK till number (it starts with K), the client ID, the client secret, and the API key.
3. Confirm your workspace has a public HTTPS domain — Kopo Kopo posts the result to a callback on it.

Configure the gateway

1. Open Settings → Payments → Kopo Kopo

   Select Kopo Kopo from the payment marketplace.

2. Enter the STK till number

   STK till number (required, maximum 30 characters) must start with K. This is the Kopo Kopo STK till, not the plain M-Pesa Buy Goods number your customers see.

3. Enter the API credentials

   Client ID, client secret, and API key are all required. The secret and the API key are stored as secrets and are not echoed back into the form after saving.

4. Save and switch

   All four fields must be present to switch. Switching gateways may require an OTP confirmation.

5. Run a controlled test payment

   Pay a small amount from the captive portal and confirm the STK prompt names your business and the payment reaches the ledger.

Credentials

Field	Required	Notes
STK till number	Yes	Must start with K, maximum 30 characters.
Client ID	Yes	From the Kopo Kopo dashboard.
Client secret	Yes	Secret.
API key	Yes	Secret.

Note

The Kopo Kopo access token is cached for 10 minutes. After rotating credentials, allow up to 10 minutes — or a controlled test failure — before concluding that new keys are not working.

Callback URLs

The callback address is sent with every payment request, so there is nothing to register in the Kopo Kopo dashboard. Requests are sent to https://api.kopokopo.com, and the result is posted back to https://<your-host>/api/kopokopo/callback. Confirm that address is not blocked by a firewall or WAF rule.

What the payer must provide

A Safaricom phone number, which receives the STK prompt. The subscriber’s first and last name are sent with the request, so keep subscriber profiles accurate — they appear on the Kopo Kopo transaction.

How a payment completes

1. Request

   Centipid Billing authenticates against Kopo Kopo, then posts an incoming payment for the STK till with the amount, the payer’s phone number, and KES as the currency.

2. Authorization

   The payer enters their M-Pesa PIN.

3. Confirmation

   Kopo Kopo posts the outcome to the callback, which records the payment and applies the subscriber’s package asynchronously.

Troubleshooting

Symptom	What it means	What to do
“Unable to initialize payment. Please try again later.”	Kopo Kopo returned no access token.	Re-check the client ID, client secret, and API key. Confirm the account is live, then allow for the 10-minute token cache.
“Unable to process payment. Please try again later.”	Authentication or the STK request failed.	Verify the credentials and that the STK till starts with K and is active.
Prompt arrives but the ledger stays empty	The callback did not arrive or did not match a checkout.	Confirm https://<your-host>/api/kopokopo/callback is publicly reachable, then see Payment troubleshooting.
Money in Kopo Kopo, not in the bank	Kopo Kopo settles to your bank on its own schedule.	Reconcile against the Kopo Kopo settlement report, not only the ledger.

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