Troubleshooting

Cause: the customer has not completed checkout, or the terminal status has not propagated.

Fix: poll Transaction Status with backoff and rely on the webhook. If still INITIATED after a timeout, reconcile later; do not assume success.

Cause: gateway is still processing or the customer abandoned.

Fix: wait for the webhook; a terminal DROP indicates abandonment. Create a new attempt for the order if needed.

Cause: the upstream gateway did not respond in time.

Fix: the payment may still be processing — check Transaction Status before retrying so you do not double-charge. Routing/failover can reduce recurrence.

Cause: the computed hash does not match — usually amount formatting, field order, or the wrong salt/environment.

Fix: recompute using the exact per-endpoint formula (see Authentication) and send the identical string values.

Cause: missing/unknown API key or missing headers.

Fix: send X-API-Key and Hash; confirm the key is active and belongs to the environment you are calling.

Cause: the account is not active or not approved for this environment.

Fix: complete onboarding/KYC and production approval, or contact support to reactivate.

Cause: the module is not enabled, or your IP is not whitelisted.

Fix: enable the module via support, or add your server egress IPs to the whitelist. The response message tells you which.

Cause: the selected gateway is degraded or in maintenance.

Fix: retry with backoff; configure failover/alternate gateways so traffic reroutes automatically.

Cause: the issuing/acquiring bank is temporarily unavailable.

Fix: retry later; use bank-based routing/failover to shift to a healthier path. Communicate transient failures to customers gracefully.

Cause: URL not configured/public, non-200 responses, TLS issues, or firewall blocking.

Fix: ensure a public HTTPS URL that verifies the signature and returns 200 fast; reconcile with Transaction Status meanwhile. See Webhooks.

Cause: refunds settle asynchronously at the gateway/bank.

Fix: poll Refund Status until refund_completed_at is set.

Cause: the gateway could not complete the refund.

Fix: inspect the reason, retry the refund, and if it persists contact support with the refund_id and transaction_id.

Cause: reusing a merchant_transaction_id that must be unique.

Fix: generate a unique order id per attempt; reconcile retries on your side.

Cause: retries and network conditions deliver the same event more than once.

Fix: deduplicate by transaction_id + event type and make processing idempotent.

Cause: the transaction routed to an unexpected gateway, or no rule matched.

Fix: review your routing rules and amount bands; a 400 "No Routing Rule found for this amount." means no active rule covers the request.

Cause: settled amounts differ from expected due to fees, timing or missed events.

Fix: reconcile transactions against settlement data, account for fees, and investigate any missing webhooks/timeouts.