Payment troubleshooting

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:

• missing required values;
• test/live mismatch;
• malformed URL/currency/country;
• invalid paybill/till format;
• a secret entered in the wrong field.

Compare Credential reference.

Request is rejected immediately

Check:

• account activation;
• environment endpoints;
• merchant/product/service code;
• credential revocation;
• amount/currency and phone format;
• 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. Then check the 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, the gateway domain and walled-garden rules. Confirm 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:

• wrong signing secret;
• wrong environment;
• provider callback URL drift;
• missing merchant activation;
• timestamp/body mismatch;
• 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 and identify the intended payer. Then use supported reassignment/correction with an audit trail. Do not solve it by creating another subscriber/payment.

Successful payment but no access

Check the entitlement stage:

• subscriber association and package;
• expiry and pause/block;
• device limit and active session;
• NAS/RADIUS state;
• 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 and pending transactions. Also check 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 and the ISP account;
• amount/currency and masked phone/account;
• application payment ID and provider reference;
• timestamps/timezone and the stage reached;
• the sanitized error and actions tried.

Exclude API keys, passkeys, private keys, passwords and OTPs. Also exclude full callback payloads containing secrets/personal data.