Decline Codes

A declined payment surfaces an ISO 8583 response code in decline_code on the payment.failed webhook payload and in the merchant dashboard. The Genius Checkout platform also resolves a buyer-facing message for each code — a short, customer-actionable line we render at checkout and pass to storefront plugins in the buyer_message field.

How the buyer-facing message resolves

1. ISO 8583 code first — the table below.
2. If the code is 97 and the gateway message mentions 3DS, the 3DS-specific text wins (PowerTranz returns 97 for both card-verification and 3DS-authentication failures; we disambiguate by the message text).
3. If we have no mapping for the code, we fall back to the gateway's own ResponseMessage.
4. If neither is available, we use the locale's decline.default.

The active locale is picked per request by the SetBuyerLocale middleware: session locale → Accept-Language header → en. Plugin webhook payloads and order notes receive the resolved text in the merchant's buyer locale — no client-side mapping needed in WC / Give / Ecwid.

Codes & buyer-facing text

The table covers every code we explicitly map. Storefront plugins and the hosted checkout all use the same lookup.

05 (and 14) — Issuer declined

Locale	Text
en	Your card was declined by the issuer. Please try a different card or contact your bank.
es	Tu tarjeta fue rechazada por el emisor. Prueba con otra tarjeta o contacta a tu banco.
fr	Votre carte a été refusée par l'émetteur. Essayez une autre carte ou contactez votre banque.
pt-BR	Seu cartão foi recusado pelo emissor. Tente outro cartão ou entre em contato com o seu banco.

12 — Invalid transaction

Locale	Text
en	The payment was rejected by your bank. Please try a different card.
es	El pago fue rechazado por tu banco. Prueba con otra tarjeta.
fr	Le paiement a été refusé par votre banque. Essayez une autre carte.
pt-BR	O pagamento foi recusado pelo seu banco. Tente outro cartão.

51 — Insufficient funds

Locale	Text
en	Insufficient funds on this card. Try a different payment method.
es	Fondos insuficientes en esta tarjeta. Prueba con otro método de pago.
fr	Solde insuffisant sur cette carte. Utilisez un autre moyen de paiement.
pt-BR	Saldo insuficiente neste cartão. Use outro método de pagamento.

54 — Expired card

Locale	Text
en	The card has expired. Please use a valid card.
es	La tarjeta está vencida. Por favor usa una tarjeta vigente.
fr	La carte a expiré. Utilisez une carte valide.
pt-BR	Cartão vencido. Use um cartão válido.

57 — Transaction not permitted on this card

Locale	Text
en	This card cannot be used for online purchases. Try a different card.
es	Esta tarjeta no se puede usar para compras en línea. Prueba con otra tarjeta.
fr	Cette carte ne peut pas être utilisée pour les achats en ligne. Essayez une autre carte.
pt-BR	Este cartão não pode ser usado em compras online. Tente outro cartão.

61 (and 65) — Exceeds withdrawal / activity limit

Locale	Text
en	You have exceeded the limit on this card today. Try again later or use a different card.
es	Has superado el límite de esta tarjeta hoy. Inténtalo más tarde o usa otra tarjeta.
fr	Vous avez dépassé la limite de cette carte aujourd'hui. Réessayez plus tard ou utilisez une autre carte.
pt-BR	Você excedeu o limite deste cartão hoje. Tente mais tarde ou use outro cartão.

91 — Issuer or switch unavailable

Locale	Text
en	Your bank is temporarily unreachable. Please try again in a few minutes.
es	Tu banco no está disponible temporalmente. Inténtalo de nuevo en unos minutos.
fr	Votre banque est temporairement indisponible. Réessayez dans quelques minutes.
pt-BR	Seu banco está temporariamente indisponível. Tente novamente em alguns minutos.

96 — System malfunction at the processor

Locale	Text
en	The payment processor had a temporary issue. Please try again in a few minutes.
es	El procesador de pagos tuvo un problema temporal. Inténtalo de nuevo en unos minutos.
fr	Le processeur de paiement a rencontré un problème temporaire. Réessayez dans quelques minutes.
pt-BR	O processador de pagamentos teve um problema temporário. Tente novamente em alguns minutos.

97 — 3-D Secure authentication failed

This variant fires when the gateway message mentions 3DS.

Locale	Text
en	Card verification failed. Your bank could not authenticate this card for 3-D Secure. Try another card or contact your bank.
es	La verificación de la tarjeta falló. Tu banco no pudo autenticar la tarjeta con 3-D Secure. Prueba con otra tarjeta o contacta a tu banco.
fr	La vérification de la carte a échoué. Votre banque n'a pas pu authentifier la carte pour 3-D Secure. Essayez une autre carte ou contactez votre banque.
pt-BR	A verificação do cartão falhou. Seu banco não conseguiu autenticar o cartão via 3-D Secure. Tente outro cartão ou entre em contato com o seu banco.

97 — Card verification (generic)

Used when the gateway message doesn't mention 3DS.

Locale	Text
en	The card details could not be verified. Please double-check the card number, expiry, and security code.
es	No pudimos verificar los datos de la tarjeta. Revisa el número, la fecha de vencimiento y el código de seguridad.
fr	Impossible de vérifier les détails de la carte. Vérifiez le numéro, la date d'expiration et le code de sécurité.
pt-BR	Não foi possível verificar os dados do cartão. Confira o número, a validade e o código de segurança.

Fallbacks

Key	en	es	fr	pt-BR
default	Payment was declined.	El pago fue rechazado.	Le paiement a été refusé.	O pagamento foi recusado.
network_error	Your payment could not be processed. Please try again or use a different payment method.	No pudimos procesar tu pago. Inténtalo de nuevo o usa otro método de pago.	Votre paiement n'a pas pu être traité. Veuillez réessayer ou utiliser un autre moyen de paiement.	Não foi possível processar seu pagamento. Tente novamente ou use outro método de pagamento.

Where you see the decline code

• Webhook — payment.failed payload carries decline_code (the ISO 8583 code, e.g. "05"), error_message (the gateway's raw message), and buyer_message (the localized text above).
• Hosted checkout — the buyer sees buyer_message on the Failed page.
• Storefront plugins — WC, Give, Magento, OpenCart, PrestaShop, Ecwid all use buyer_message in their order-notes and customer-facing failure surfaces.
• Merchant dashboard — the full gateway response (ISO code, AVS, CVV) shows on the transaction detail page; the merchant sees the raw mapping plus the buyer-facing copy.

Other ISO 8583 codes

The platform handles every ISO 8583 code — codes outside the table above fall through to the gateway's own message (which is itself trimmed and de-duplicated punctuation-wise), then to the locale's default text. The full ISO 8583 catalog is on Wikipedia: ISO 8583 response codes.

Next

• Webhooks — payment.failed payload carries decline_code + buyer_message
• Error Handling — HTTP error envelopes (vs payment declines)