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

# Payment troubleshooting

> Diagnose configuration, initiation, callback, status, duplicate, and settlement problems.

# Trace the payment lifecycle

Determine the failing stage before changing credentials:

1. **Readiness:** required fields saved and gateway selected.
2. **Initiation:** application/provider accepts the request.
3. **Customer authorization:** prompt or hosted checkout completes.
4. **Callback/verification:** provider result reaches and passes signature checks.
5. **Ledger:** payment reaches correct status with unique reference.
6. **Entitlement:** subscriber/package/invoice updates.
7. **Receipt/notification:** customer communication is generated.
8. **Settlement:** provider funds reconcile externally.

## Credential form will not save

Read field-level errors. Common causes are missing required values, test/live mismatch, malformed URL/currency/country, invalid paybill/till format, or a secret entered in the wrong field. Compare [Credential reference](/billing/payment-gateways/credentials-reference).

## Request is rejected immediately

Check account activation, environment endpoints, merchant/product/service code, credential revocation, amount/currency, phone format, and provider availability. Do not repeatedly send the same request while rate-limited.

## Customer receives no phone prompt

Confirm the gateway actually uses a phone prompt, phone country/format, provider account permissions, shortcode/till/paybill, and provider request status. Hosted-checkout providers require browser redirect rather than STK.

## Captive device cannot reach checkout

Check router DNS/internet, gateway domain, walled-garden rules, and whether the configured endpoint is correct for the environment. Use **Sync walled garden** rather than opening unrestricted internet access.

## Payment remains pending

Search by provider reference/receipt, inspect the provider dashboard, and check callback/return status. Browser return is not final verification. Do not create a manual payment until the provider transaction is conclusively failed/unmatched.

## Callback rejected

Likely causes include wrong signing secret, wrong environment, provider callback URL drift, missing merchant activation, timestamp/body mismatch, or duplicate reference. Preserve sanitized request ID, HTTP status, provider event/reference, and timestamp. Never log or share full secrets.

## Duplicate payment or credit

Compare receipt/provider reference, amount, subscriber, and time. Preserve both records while investigating. Reverse/delete only through an approved reconciled process; avoid changing subscriber expiry first and explaining the ledger later.

## Successful payment but wrong subscriber

Stop further entitlement changes. Verify account-number/phone/receipt mapping, identify the intended payer, and use supported reassignment/correction with an audit trail. Do not solve it by creating another subscriber/payment.

## Successful payment but no access

Check entitlement stage: subscriber association, package, expiry, pause/block, device limit, active session, NAS/RADIUS state, and invoice linkage. The payment gateway is no longer the likely fault once ledger and entitlement update are confirmed.

## Settlement differs from ledger

Reconcile provider fees, reversals/refunds, pending transactions, manual methods, date/timezone cutoffs, and wallet eligibility. The application ledger is operational evidence, not a substitute for provider/bank settlement records.

## Escalation evidence

Provide gateway code/environment, the ISP account, amount/currency, masked phone/account, application payment ID, provider reference, timestamps/timezone, stage reached, sanitized error, and actions tried. Exclude API keys, passkeys, private keys, passwords, OTPs, and full callback payloads containing secrets/personal data.