# Payment error codes (/en/integrate/errors/payment-error-codes) Every value of `lastPaymentError.code`, grouped by domain. Each entry's URL is the value of `lastPaymentError.docUrl`. This page is the destination of every `lastPaymentError.docUrl` whose code came from `PaymentErrorCode`. Anchors here match the `code` value, so `https://docs.xpay.app/integrate/errors/payment-error-codes#card_declined` lands directly on the row below. For the issuer's specific decline reason on a card payment (`lastPaymentError.declineCode`), see [Decline codes](/integrate/errors/decline-codes). For the model and the handler pattern, see [Payment errors](/integrate/errors/payment-errors). ## Card validation [#card-validation] The customer entered card details that don't pass basic validation. `paymentMethodType: "card"`. Advice: `confirm_card_data` (have the customer re-enter their details). ### `invalid_number` [#invalid_number] The card number isn't in a valid format (wrong length, fails Luhn check, etc.). ### `invalid_expiry_month` [#invalid_expiry_month] The expiration month isn't a valid value. ### `invalid_expiry_year` [#invalid_expiry_year] The expiration year isn't a valid value. ### `invalid_cvc` [#invalid_cvc] The CVC/CVV isn't in a valid format (wrong length). ### `incorrect_number` [#incorrect_number] The card number passed format validation but the issuer says it's wrong. ### `incorrect_cvc` [#incorrect_cvc] The CVC/CVV doesn't match what the issuer has on file. ### `incorrect_zip` [#incorrect_zip] The postal code doesn't match the billing address on file with the issuer. ### `expired_card` [#expired_card] The card expired. The customer needs a different card. ## Processing [#processing] Errors that came back during the actual charge attempt. Mix of card errors and processor outcomes. ### `card_declined` [#card_declined] The issuer declined the charge without a more specific reason. Pair with `lastPaymentError.declineCode` for the issuer-level reason when present. ### `processing_error` [#processing_error] An error occurred during processing, but the issuer didn't reject the charge outright. Often transient. Advice: `try_again_later`. ### `authentication_required` [#authentication_required] The issuer requires additional authentication (3D Secure) to complete the payment. The customer needs to re-attempt and complete the challenge. ## Account and balance [#account-and-balance] ### `insufficient_funds` [#insufficient_funds] The customer's card doesn't have enough available balance for the charge. ### `card_velocity_exceeded` [#card_velocity_exceeded] The card has been used too many times in a short window. Advice: `try_again_later`. ## Fraud and risk [#fraud-and-risk] The issuer rejected the charge for risk reasons. Advice: `do_not_try_again` for all three. ### `fraudulent` [#fraudulent] The issuer (or XPay's own risk signals) flagged the payment as fraudulent. Don't retry; this attempt is logged on the issuer's side. ### `stolen_card` [#stolen_card] The card was reported stolen. Don't retry. Notify your support team if the rate is unusual. ### `lost_card` [#lost_card] The card was reported lost. ## Processor [#processor] ### `issuer_not_available` [#issuer_not_available] XPay couldn't reach the card's issuing bank. Advice: `try_again_later`. ### `processor_timeout` [#processor_timeout] The payment processor didn't respond in time. The request may have succeeded on their side; check the dashboard before retrying. Advice: `try_again_later`. ### `processor_declined` [#processor_declined] The processor declined the charge for a reason that didn't translate into a more specific code. ## Request [#request] ### `amount_too_large` [#amount_too_large] The charge amount exceeds the maximum allowed for this payment method. ### `amount_too_small` [#amount_too_small] The charge amount is below the minimum required for this payment method. ### `currency_not_supported` [#currency_not_supported] The currency isn't supported by this payment method. ### `duplicate_transaction` [#duplicate_transaction] The processor detected a similar transaction recently. Wait, then retry. ## Refund [#refund] ### `charge_already_refunded` [#charge_already_refunded] You tried to refund a charge that's already been fully refunded. ### `charge_disputed` [#charge_disputed] You tried to refund a charge that's currently under dispute. Disputed charges are out of your control until the dispute resolves. ### `refund_disputed_payment` [#refund_disputed_payment] You tried to refund a payment that's been disputed. Same rule. ## Non-card payment methods [#non-card-payment-methods] ### `payment_declined` [#payment_declined] A non-card payment method (BNPL, kiosk, wallet, bank transfer) declined the payment. Specifics depend on the provider; check the dashboard for details. ## Generic [#generic] When the processor or issuer doesn't return a specific reason, XPay falls back to one of these. ### `generic_decline` [#generic_decline] The payment was declined without a specific reason. ### `do_not_honor` [#do_not_honor] The issuer returned "do not honor", which usually means the customer should contact their bank. Advice: `try_again_later`. ### `call_issuer` [#call_issuer] The issuer told the customer to call them. Show the customer a clear "contact your bank and try again" prompt. ## Where to next [#where-to-next] The issuer's decline reason in `lastPaymentError.declineCode`. More granular than the codes on this page. The model: how `lastPaymentError` is shaped and how to handle it. The other reference: codes returned in `error.code` on a failed API call. The synchronous API error envelope. Back to the top. The two-surfaces map.