Payment error codes

This page is the destination of every lastPaymentError.docUrl whose code is a payment error code. Anchors here match the code value, so https://docs.xpay.app/integrate/errors/payment-error-codes#card_declined lands directly on the row below.

code tells you what kind of failure it was. For the bank's specific reason on a decline (lastPaymentError.declineCode), see Decline codes. For the model and the handler pattern, see Payment errors.

Declines

The payment reached the bank or the payment provider, and it said no. declineCode carries the specific reason and adviceCode tells you what to do next.

card_declined

A card payment was declined. type: card_error. Read declineCode for the reason.

payment_declined

A non-card payment (Valu, Fawry) was declined. type: payment_method_error. declineCode carries the reason when the provider gave one.

Not completed by the customer

payment_abandoned

The customer left before finishing a required step: the 3D Secure challenge, the provider's payment page, or paying a Fawry reference before it expired. Nothing was charged. The customer can pay again on the same Checkout Session.

Rejected before reaching the bank

type: processor_error. No card was charged and no bank declined anything. Advice: do_not_try_again. For the first three codes retrying fails the same way, whatever the customer pays with, so contact XPay support with the chargeId. processor_risk_blocked is different: the screening is per card and per transaction, so another card can go through.

processor_request_rejected

The payment provider rejected the payment request before it reached the card network.

local_processor_rejected

The same failure for a non-card method: the provider rejected the request before a payable reference was created.

merchant_config_incomplete

Your account's setup for this payment method is incomplete, so the payment was not sent.

processor_risk_blocked

Risk screening blocked this card for this transaction before it reached the bank. Suggest a different card to the customer.

Provider did not answer

type: processor_error. Advice: try_again_later. A plain retry with the same card is the right next step.

processor_unavailable

The payment provider could not service the request (busy or failing). Nothing was charged. Retrying shortly works.

processor_session_expired

The payment session expired before the charge was submitted. Nothing was charged. A retry opens a fresh session.

processor_no_response

The attempt ended with no answer from the provider, and XPay confirmed nothing was charged.

processor_error

The provider returned an error XPay could not classify, or could not be reached. Read merchantMessage for what happened.

Where to next