Handle API errors and uncertain responses

Handle both the HTTP result and the API response body in your integration. Save enough non-secret context to locate the affected local order, PayerOne order ID and refund ID. Do not log Merchant Tokens, Private Keys or full customer payloads.

Correct the request first

For a missing or invalid required field, fix that field and retry the intended operation. Standard checkout requires a supported currency and a public HTTPS IPN URL. An order lookup returning **Order Not found** needs the PayerOne order ID and the correct merchant account; your own `custom_id` cannot replace it.

If account access is refused, sign in to the PayerOne dashboard and follow the returned account or email verification instruction. Repeating an unchanged rejected request is unlikely to resolve an account problem.

Slow down on rate limits

HTTP `429` means the request rate is too high. Respect `Retry-After` when it is supplied and use a delayed retry with backoff. If PayerOne reports temporary unavailability, keep your local operation pending and retry later rather than treating it as a completed payment.

A timeout is an uncertain outcome

A network timeout does not establish that the request failed before reaching PayerOne. Keep the operation record and reconcile what happened. For an existing order ID, perform an authenticated lookup. For a refund, keep the original `idempotency_key` and look up the recorded refund before submitting a different request.

Order `custom_id` is a reference and does not document create-order deduplication. Avoid automatic unlimited retries of checkout creation. Refund requests should always use a stable idempotency key for the same intended refund; generate a new key only for a new refund.

Escalate with useful details

Send support the approximate time and time zone, API operation, HTTP status or safe error message, and relevant order or refund reference. Remove customer data that is not needed and redact all credentials. Do not mark an order paid solely to clear an integration error.