Handle error codes on payment failures
When a payment fails, it can be useful to retrieve the error code returned by the customer’s bank, the payment network or the payment processor. Such token can be used to determine the potential cause of the failure, and give valuable insights to your customer success teams.
Error codes
Error codes are normalized by ProcessOut to provide a convinient and general
error mapping, regardless of which payment processor was used to process the
transaction. While ProcessOut aims to return all the available information,
payment providers and banks sometime simply don’t, and return generic error codes such as
card.do-not-honor. In this cases, ProcessOut uses machine learning on all
the transactions analyzed on the network to pin-point possible reasons, which
can be used by both your finance teams to improve your global authorization rates,
and by your customer success to follow up with recoverable customers. Find more
about it directly in your Dashboard ↗.
On a transaction failure, the error code is stored in the error_code field
of a Transaction ↗, as well as in the error_code
field of the Operation ↗ that lead to the error.
Codes are splitted in two distinct categories: soft and hard declines. Soft declines represent errors that can be retried at a later date, while hard declines represent transactions that shouldn’t be retried at all.
| Soft declines: | |
payment.declined |
The payment was declined, but no further information was returned |
gateway.declined |
The gateway that attempted to process the payment returned a generic decline. This can be caused by validation errors, fraud prevention tool or other specific errors. |
card.needs-authentication |
The card requires a 3DS authentication to be performed, for example in the scope of 3DS2/SCA |
card.declined |
Similarly to payment.declined, the card payment was declined with no further information |
card.do-not-honor |
Do Not Honor is the default error code sent by bank, without any additional information |
card.no-action-taken |
No action was done by the payment provider, and should be retried |
card.please-retry |
The payment should be retried |
card.security-violation |
The transaction represented a security threat during its processing and was declined |
card.acquirer-failed |
The acquirer used by the payment processor failed to process the transaction |
card.issuer-failed |
The card holder bank failed to process the transaction |
card.processing-error |
The processing failed at the acquirer or card holder bank level |
card.issuer-down |
The card holder bank could not process the payment |
card.maximum-attempts |
The card maximum payment attempts were reached- the customer should contact its bank |
card.contact-bank |
The card holder bank declined the payment, and should be contacted by your customer |
card.exceeded-limits |
The card limits were reached (ex: amounts, transactions volume) and the customer should contact its bank |
card.exceeded-withdrawal-limit |
The card withdrawal limit was reached, the customer should contact its bank |
card.exceeded-activity-limits |
The card activity limit was reached, the customer should contact its bank |
card.no-money |
The card has no money left in its bank account, the customer should add more funds |
card.possible-fraud |
The payment was blocked for potential fraud |
card.duplicate |
The transaction had high chances of being a duplicate, and was declined |
card.issuer-not-found |
The payment provider could not find the card issuer bank |
card.network-failed |
The payment provider failed to contact the card network to process the transaction |
card.not-supported |
The card is not supported by the payment provider |
card.currency-unsupported |
The currency is not supported by this card |
card.type-not-supported |
The card type was not supported by the payment provider |
card.not-activated |
The card was not activated yet by the card holder or its bank |
| Hard declines: | |
card.expired |
The card was expired |
card.invalid |
The card was invalid (invalid number/expiration date/CVC) |
card.invalid-number |
The card has an invalid number |
card.invalid-pin |
The card PIN was invalid. This error code does not apply for online payments |
card.invalid-name |
The name on the card was invalid (potential AVS failure) |
card.invalid-expiry-date |
The card expiration date was invalid |
card.invalid-expiry-month |
The card expiration month was invalid |
card.invalid-expiry-year |
The card expiration year was invalid |
card.invalid-zip |
The card holder ZIP code was invalid (potential AVS failure) |
card.invalid-address |
The card holder address was invalid (potential AVS failure) |
card.missing-cvc |
The card CVC was missing, but needed to process the payment |
card.missing-expiry |
The card expiry date was missing, but needed to process the payment |
card.missing-number |
The card number was missing |
card.missing-3ds |
The card 3DS verification process was missing but needed to process the payment |
card.failed-cvc |
The card CVC check failed |
card.failed-avs |
The card AVS check failed |
card.failed-avs-postal |
The card AVS check failed on the postal code |
card.unsupported-3ds |
The card does not support 3DS authentication (but a 3DS authentication was requested) |
card.failed-3ds |
The card 3DS check failed |
card.expired-3ds |
The card 3DS check expired and needs to be retried |
card.failed-avs-address |
The card AVS check failed on the address |
card.failed-cvc-and-avs |
Both the card CVC and AVS checks failed |
card.bad-track-data |
The track data of the card was invalid (expiration date or CVC) |
card.not-authorized |
The card is not authorized to make the payment |
card.not-registered |
The card was not yet registered and can therefore not process payments |
card.stolen |
The card was stolen |
card.lost |
The card was lost by its card holder |
card.dont-retry |
The payment should not be retried |
card.invalid-account |
The card bank account was invalid, the customer should contact its bank |
card.revoked |
The card was revoked |
card.revoked-all |
All the card holder cards were revoked |
card.test |
The card was a test card and can’t be used to process live transactions |
card.blacklisted |
The card was blacklisted from the payment provider |