Kopo Kopo

Accept customer M-Pesa payments via Kopo Kopo's Incoming Payments API and STK Till with automated bank settlement.

Collect payments with Kopo Kopo

The Kopo Kopo integration raises an M-Pesa STK prompt through Kopo Kopo's Incoming Payments API against your registered Kopo Kopo STK till.

Collected funds settle to the bank account linked to your Kopo Kopo merchant profile, typically on the next business day according to Kopo Kopo's settlement schedule.

Availability: ISPs operating in Kenya (KE).
Automated STK Prompt: Customers authorize payment via an instant M-Pesa STK push prompt.
Bank Settlement: Funds move automatically from Kopo Kopo to your designated business bank account.

Before you start

Complete merchant onboarding with Kopo Kopo in an account owned by your ISP.
From your Kopo Kopo developer dashboard, obtain your STK till number (must start with the letter K), Client ID, Client Secret, and API Key.
Confirm your Nukta workspace has a public HTTPS domain—Kopo Kopo posts transaction results back to your webhook callback.

Configuring the gateway

In your Nukta dashboard, navigate to Settings → Payments.
Select Kopo Kopo from the payment marketplace.
Configure your merchant credentials:
- STK Till Number: Required string (maximum 30 characters) that must start with K. This is your dedicated Kopo Kopo STK till, distinct from the public M-Pesa Buy Goods number displayed to retail customers.
- Client ID: Your Kopo Kopo application Client ID.
- Client Secret: Your application Client Secret (stored securely; not re-displayed after saving).
- API Key: Your Kopo Kopo REST API Key (stored securely; not re-displayed after saving).
Click Save Settings to switch the gateway live. (Switching payment gateways may request a secure action OTP).

NOTE

Access Token Caching

Nukta caches Kopo Kopo OAuth access tokens for 10 minutes. After rotating or updating credentials, allow up to 10 minutes (or a test failure) before concluding whether new keys are active.

Run a Controlled Test: Pay a small test amount from your captive portal. Confirm the STK prompt names your business and the transaction appears in Finance → Payments.

Credentials reference

Field	Required	Notes
STK Till Number	Yes	Must start with `K` (maximum 30 characters). Your Kopo Kopo STK till.
Client ID	Yes	Obtained from the Kopo Kopo merchant developer portal.
Client Secret	Yes	Stored securely. Obtained from the Kopo Kopo developer portal.
API Key	Yes	Stored securely. Generated in the Kopo Kopo API access section.

Callback URLs

The callback address is attached dynamically with every payment request, meaning there is no need to manually register endpoints in the Kopo Kopo dashboard.

Payment requests are dispatched to https://api.kopokopo.com, and results are delivered back to:

https://{subdomain}.nukta.one/api/payments/kopokopo/callback

Ensure this endpoint is not blocked by external firewalls or custom WAF inspection rules.

Customer checkout experience

Required Customer Input: The customer provides their Safaricom mobile phone number to receive the STK prompt.
Profile Accuracy: The customer's first and last name from their Nukta account are transmitted alongside the STK request, appearing on the Kopo Kopo transaction record.

How transactions complete

Customer Checkout → Nukta Authenticates with Kopo Kopo → STK Push Prompt → Customer Enters PIN → Kopo Kopo Webhook Callback → Service Activated

Request: Nukta authenticates against Kopo Kopo using OAuth, then posts an incoming payment request for your K-prefixed STK till with the customer's phone number, amount, and KES currency.
Authorization: The customer enters their M-Pesa PIN on their phone.
Settlement & Activation: Kopo Kopo posts the outcome to Nukta's webhook callback, which logs the payment and activates the customer's internet package asynchronously.

NOTE

Bank Settlement vs. Ledger

Kopo Kopo settles funds to your bank account on its own payout schedule. Always reconcile your ledger against the Kopo Kopo merchant settlement report rather than expecting instant bank deposits.

Troubleshooting

Symptom	Cause	Recommended Action
"Unable to initialize payment. Please try again later."	Kopo Kopo did not return an access token.	Double-check Client ID, Client Secret, and API Key. Verify the account is active in production, then allow 10 minutes for token cache expiration.
"Unable to process payment. Please try again later."	API authentication or the incoming payment request failed.	Verify credentials and ensure the STK till starts with `K` and is in active status.
STK prompt completes, but ledger remains empty	The webhook callback did not arrive or failed verification.	Confirm your callback URL is reachable over public HTTPS, then consult Payment Troubleshooting.
Funds visible in Kopo Kopo dashboard but not in bank	Kopo Kopo settles on its own payout cycle.	Review the Kopo Kopo settlement report in your merchant portal to verify payout dates.

For a summary of parameters across all gateways, consult the Gateway Credential Reference.