> ## Documentation Index
> Fetch the complete documentation index at: https://docs.centipidbilling.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Kopo Kopo

> Configure Kopo Kopo STK collections into your Kopo Kopo till.

# 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

<Steps>
  <Step title="Open Settings → Payments → Kopo Kopo">
    Select Kopo Kopo from the payment marketplace.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="Save and switch">
    All four fields must be present to switch. Switching gateways may require an
    OTP confirmation.
  </Step>

  <Step title="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.
  </Step>
</Steps>

## 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.
</Note>

## 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

<Steps>
  <Step title="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.
  </Step>

  <Step title="Authorization">
    The payer enters their M-Pesa PIN.
  </Step>

  <Step title="Confirmation">
    Kopo Kopo posts the outcome to the callback, which records the payment and
    applies the subscriber's package asynchronously.
  </Step>
</Steps>

## 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](/billing/payment-gateways/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](/billing/payment-gateways/credentials-reference).