Error and Timeout Handling

Error and Decline Handling

Gateway Connect distinguishes between system errors (provider server unavailable, timeout) and business declines (bank declined card, insufficient funds).

Important rule: Gateway always returns HTTP 200, even if transaction is declined. Transaction status is determined by the JSON response content, not the HTTP code.

---

Scenario 1: System Error (provider returned HTTP 4xx / 5xx)

If provider is unavailable or returned an error, Gateway logs it in logs and returns HTTP 200 with result: false:

{
  "result": false,
  "error": "Provider returned HTTP 502 – Bad Gateway",
  "logs": [...]
}

Transaction remains in “processing” status. Final status will be received later via POST /callback or POST /status.

---

Scenario 2: Network Timeout

Provider request timeout: 15 seconds by default.

Configurable individually for each method in gateway_settings.methods.<method>.response_timeout (see Settings and Statuses).

When timeout is exceeded, Gateway returns HTTP 200 with result: false and code: 408.

---

Scenario 3: Soft Decline (HTTP 200, business decline)

Business Service determines decline if any of the following three conditions are found in Gateway response:

1. result: false
2. status: "declined"
3. Presence of error key in response root

Decline Reason (declination_reason)

Business Service extracts reason text from one of the response fields in the following order:

1. declination_reason
2. details
3. reason
4. error

Message is saved with prefix gateway response error:.

Example of business decline (bank declined):

{
  "result": true,
  "status": "declined",
  "details": "Insufficient funds",
  "logs": [...]
}

Example of system decline (error in Gateway):

{
  "result": false,
  "error": "Card token validation failed inside gateway",
  "logs": [...]
}