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

# DPO Pay

> Configure DPO Pay hosted checkout for cards and mobile money across Africa.

# Collect payments with DPO Pay

`DPO` uses a **hosted checkout**: Centipid Billing creates a transaction token
with DPO, sends the payer to DPO's payment page, and verifies the token before
crediting anything.

Offered in the country catalog for **Kenya, Uganda, Rwanda, Ghana, Côte
d'Ivoire, South Africa, Tanzania, Zambia, Malawi, Senegal, Zimbabwe, and
Nigeria**.

## Before you start

1. Complete DPO merchant onboarding in an account owned by the ISP.
2. In the DPO dashboard open **Settings → Company Token** and collect the
   **company token**.
3. Collect the numeric **service type** for the product you are selling. DPO
   issues it per service, and a wrong value is rejected at checkout.
4. Plan the walled garden: the payer's browser must reach
   `secure.3gdirectpay.com`, so a Hotspot subscriber who is not yet online
   cannot pay unless DPO is reachable pre-authentication.

## Configure the gateway

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

  <Step title="Enter the company token">
    **Company token** (required, stored as a secret) comes from DPO dashboard →
    Settings → Company Token.
  </Step>

  <Step title="Enter the service type">
    **Service type** (required) is the numeric service or product code from your
    DPO account.
  </Step>

  <Step title="Register the redirect and back URLs">
    See [Callback URLs](#callback-urls) below.
  </Step>

  <Step title="Run a controlled test payment">
    Pay a small amount from the captive portal on an unauthenticated device and
    confirm the payment reaches the ledger.
  </Step>
</Steps>

## Credentials

| Field         | Required | Notes                                                 |
| ------------- | -------- | ----------------------------------------------------- |
| Company token | Yes      | Secret. Identifies your DPO company on every request. |
| Service type  | Yes      | Numeric service/product code from DPO.                |

Both gate the switch.

## Callback URLs

| Name         | Path                                      |
| ------------ | ----------------------------------------- |
| Redirect URL | `https://<your-host>/tenant/dpo/callback` |
| Back URL     | `https://<your-host>/tenant/dpo/failed`   |

Set both in your DPO account. The redirect is where a completed payment returns;
the back URL is where a cancelled or failed one lands.

## What the payer must provide

Whatever DPO's payment page asks for — card or mobile money, depending on what
DPO has enabled for your account and country. The amount and the currency are
fixed before the payer arrives.

## How a payment completes

<Steps>
  <Step title="Create token">
    Centipid Billing posts an XML request to DPO's API and receives a
    transaction token.
  </Step>

  <Step title="Payment">
    The payer is redirected to DPO's payment page and completes the payment
    there.
  </Step>

  <Step title="Verification">
    On return, the token is verified against DPO. Only a verified successful
    result records a payment and applies the package; DPO's own explanation is
    stored against the transaction otherwise.
  </Step>
</Steps>

## Troubleshooting

| Symptom                                                                                              | What it means                                                    | What to do                                                                                                                                 |
| ---------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| *"Payment failed: DPO Pay is not fully configured. Please add your company token and service type."* | One of the two fields is missing.                                | Complete both in Settings → Payments.                                                                                                      |
| *"Payment failed: Unable to reach DPO Pay. Please try again later."*                                 | The API could not be reached, or its reply could not be parsed.  | Check outbound connectivity to `secure.3gdirectpay.com`, then retry.                                                                       |
| *"Payment failed: …"* with a DPO explanation                                                         | DPO declined the request and returned a reason.                  | Read the explanation. A wrong service type or an unsupported currency are the usual causes.                                                |
| The payment page never loads on a Hotspot device                                                     | The walled garden does not allow DPO.                            | Allow `secure.3gdirectpay.com` pre-authentication — see [Captive device cannot reach checkout](/billing/payment-gateways/troubleshooting). |
| *"Payment not successful"* on return                                                                 | The token verified, but DPO did not report a successful payment. | Check the transaction on the DPO dashboard. Nothing is credited.                                                                           |
| *"Payment reference not found"*                                                                      | The returned token has no matching local checkout.               | Raise it with support with the DPO transaction token.                                                                                      |

For every gateway's fields in one place, see the
[credential reference](/billing/payment-gateways/credentials-reference).