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
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