Error handling 🧼

PAYSTRAX Gateway offers many kinds of errors. They can reflect external events like declined payments and network interruptions, or code problems, like invalid API calls.

Parse error data

Catch exceptions

Monitor webhooks

Get infos about failure

🧼🧶 Handling payments failures, pending, and unknown status

For the full set of statuses and how payments evolve per flow, see Payment status transitions. This section covers the edge cases specifically — the requests that don't resolve cleanly. These aren't covered by the happy-path guides and should be handled with retry logic or error mapping.

Failed payments

A failed payment means the processor rejected the operation — the request itself was valid, but the transaction wasn't approved.

Field	Description
status	Always fail.
failure.code	System- or processor-specific error code.
failure.reason	Localised, human-readable reason.
failure.retry_possible	Whether a retry is recommended.

A hard decline — don't retry:

{
  "id": "<id>",
  "status": "fail",
  "failure": {
    "code": "AVS_DECLINED",
    "reason": "AVS check failed",
    "retry_possible": false
  }
}

A soft decline — safe to retry, or to fall back to the next configured processor:

[TODO]

{
  "id": "<id>",
  "status": "fail",
  "failure": {
    "code": "PROCESSOR_TIMEOUT",
    "reason": "Processor did not respond in time",
    "retry_possible": true
  }
}

Pending transactions

A pending status means the request was accepted but the outcome isn't final yet — usually seen with:

• 3D Secure flows
• Transfers awaiting downstream capture
• Third-party processors with asynchronous confirmation

[TODO]

{
  "id": "<id>",
  "status": "pending",
  "object_type": "transfer",
  "original_response": {
    "resultCode": "Received",
    "note": "Waiting for confirmation from bank"
  }
}

Transfers are often asynchronous even though authorisations are synchronous — don't treat pending as a failure. Confirm the final outcome with a follow-up GET or by listening for a webhook.

Unknown state

Rare, but it happens — typically a processor timeout or interrupted processing. [TODO]

{
  "id": "<id>",
  "status": "unknown",
  "original_response": {
    "note": "Timeout from downstream processor"
  }
}

info

Retry is not recommended for unknown responses unless verified through logs or processor support.

🧼 Retry logic and processor fallback (TODO!!! Check if the Gateway is able to handle this)

PAYSTRAX Gateway supports retry and fallback based on the failure.retry_possible flag and the processor routing list in your request.

info

Delayed retry — deciding when and how to retry after time has passed —is currently the integrator's own responsibility; see Ailalta pagina for how to handle that without native idempotency keys.

Scenario	retry_possible	Recommendation
Soft processor decline	true	Retry using the next processor in your list.
AVS mismatch or fraud block	false	Do not retry — request new input from the shopper.
3DS failed or user cancelled	false	Abort and escalate.
Network timeout	true	Retry with the same payload (idempotent).

If you supply multiple processors and the first fails with retry_possible: true, PAYSTRAX automatically retries with the next processor in sequence until one succeeds, all fail, or a retry_possible: false response is returned.

If only one processor is configured and a payment fails with retry_possible: true, that's a soft decline — you can safely retry with the same payload.