PayPal

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

1. Open Settings → Payments → PayPal

   Select PayPal from the payment marketplace.

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

3. Choose the settlement currency

   Settlement currency (required) is searchable by name or code.

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

Caution

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.

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

1. Create order

   Centipid Billing authenticates against PayPal and creates an order in the settlement currency, with return and cancel URLs.

2. Approval

   The payer approves the order on PayPal’s page and is returned.

3. Capture

   The order is captured. Only a completed capture records a payment and applies the package — an approved but uncaptured order is not money.

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.

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