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

# PayPal

> Configure PayPal checkout, and understand how the settlement currency changes your dashboard.

# Collect payments with PayPal

`PAYPAL` sends the payer to PayPal's approval page, then **captures** the
approved order. Nothing is credited until the capture succeeds.

PayPal is the fallback gateway for any country without its own catalog entry, so
it is available almost everywhere: Kenya, Rwanda, Ghana, Côte d'Ivoire, South
Africa, Egypt, Tanzania, Zambia, Malawi, Benin, Burkina Faso, Cameroon, DR
Congo, Republic of the Congo, Senegal, Sierra Leone, Zimbabwe, Nigeria, and
Pakistan among them.

## Before you start

1. Create an app in the [PayPal Developer dashboard](https://developer.paypal.com)
   under a business account owned by the ISP, and collect its **client ID** and
   **client secret**.
2. Decide the **settlement currency** — see the warning below, because it
   changes more than PayPal.
3. Plan the walled garden: the payer's browser must reach PayPal, so a Hotspot
   subscriber who is not yet online cannot pay unless PayPal is reachable
   pre-authentication.

## Configure the gateway

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

  <Step title="Enter the client ID and client secret">
    Both are required. The secret is stored as a secret and is not echoed back
    into the form after saving.
  </Step>

  <Step title="Choose the settlement currency">
    **Settlement currency** (required) is searchable by name or code.
  </Step>

  <Step title="Run a controlled test payment">
    Pay a small amount from the captive portal on an unauthenticated device.
    Confirm the approval page loads, the payment is captured, and the amount in
    the ledger matches what PayPal captured.
  </Step>
</Steps>

<Warning>
  The settlement currency becomes **your dashboard's billing currency and
  symbol**, not just PayPal's. Changing it changes how amounts are displayed and
  billed across the workspace. Decide it once, deliberately, before you take
  live payments.
</Warning>

## Credentials

| Field               | Required | Notes                                                                                    |
| ------------------- | -------- | ---------------------------------------------------------------------------------------- |
| Client ID           | Yes      | From the PayPal Developer dashboard.                                                     |
| Client secret       | Yes      | Secret.                                                                                  |
| Settlement currency | Yes      | Three-letter code, chosen from the current currency list. Also drives dashboard display. |

All three gate the switch.

## Callback URLs

None to register. PayPal returns the payer to a return URL generated per order,
and a cancel URL for an abandoned checkout. PayPal webhooks are accepted and
de-duplicated, but the capture is what credits a payment.

## What the payer must provide

A PayPal account or a card, on PayPal's own page. The amount is fixed before the
payer arrives, and must be greater than zero.

## How a payment completes

<Steps>
  <Step title="Create order">
    Centipid Billing authenticates against PayPal and creates an order in the
    settlement currency, with return and cancel URLs.
  </Step>

  <Step title="Approval">
    The payer approves the order on PayPal's page and is returned.
  </Step>

  <Step title="Capture">
    The order is captured. Only a completed capture records a payment and
    applies the package — an approved but uncaptured order is not money.
  </Step>
</Steps>

A repeated capture of an order already recorded is rejected as a duplicate
rather than credited twice.

## Troubleshooting

| Symptom                                                                  | What it means                                           | What to do                                                                                                                        |
| ------------------------------------------------------------------------ | ------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| *"Payment initiation failed: PayPal credentials are not configured."*    | The client ID or secret is missing.                     | Enter both in Settings → Payments.                                                                                                |
| *"Payment initiation failed: Unable to authenticate with PayPal."*       | PayPal rejected the credentials.                        | Re-copy them. Confirm the app is live, not sandbox.                                                                               |
| *"Payment initiation failed: Invalid currency code."*                    | The settlement currency is not a three-letter code.     | Re-select it from the list.                                                                                                       |
| *"Payment initiation failed: Payment amount must be greater than zero."* | The checkout amount was zero.                           | Check the package price.                                                                                                          |
| *"PayPal did not return an approval link."*                              | PayPal accepted the order but returned no approval URL. | Retry, then raise the order id with PayPal.                                                                                       |
| *"Order has not been approved by the customer yet."*                     | Capture ran before the payer approved.                  | Have the payer complete the approval, then retry the capture.                                                                     |
| *"Order is in … state and cannot be captured."*                          | The order expired or was voided.                        | Start a fresh checkout.                                                                                                           |
| *"Payment not completed."*                                               | The capture did not complete.                           | Check the order on PayPal before recording anything by hand.                                                                      |
| The approval page never loads on a Hotspot device                        | The walled garden does not allow PayPal.                | Allow PayPal's domain pre-authentication — see [Captive device cannot reach checkout](/billing/payment-gateways/troubleshooting). |

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