​

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.

​

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.