Error codes

When a payment fails, the customer’s bank, the payment network or the payment processor returns an error code. The code gives an indication of what went wrong during the payment, which can help you to identify problems in your payment handling.

Different payment processors and banks generate different error codes when payments fail. Smart Router uses its own set of error codes as an abstraction over these different systems. This means that you will see the same Smart Router code for a particular type of error, regardless of which code the bank or provider originally returned.

Some banks and providers return just a single generic error code (such as for all failures. This confirms that the transaction failed but does not give you much help when you try to identify the problem. In cases like these, Smart Router uses machine learning on all the available data from the transaction to find the reason why it failed and make the error code as useful as possible.

Use the error_code field of a Transaction object to retrieve the code returned after an authorization or capture. The operations field of the Transaction object contains a list of Operation objects that also have their own error_code fields. The sequence of operations in a transaction can give you more detail about what went wrong along the way and what Smart Router did to correct the errors.

ProcessOut may automatically block a transaction to comply with scheme rules. For example, an authorization will return request.transaction-blocked if Mastercard sends a 03: Do Not Retry Merchant Advice Code. Future transactions on the same gateway with the same card and amount will be blocked for 30 days to avoid compliance fees.

List of error codes

There are 2 types of error code:

  • Soft declines represent failed transactions that Smart Router can attempt again. An example of a soft decline is a transaction where there were transient technical issues, such as server downtime at the issuing bank. Another example is where 3DS authentication is required for a transaction.
  • Hard declines represent fatal errors that immediately end a transaction. An example of a hard decline is a transaction using details for a card that has been reported as lost or stolen. Another example is a payment from an account that was once active but has now been closed.

The list of error codes that Smart Router returns is given below.

Note: The list does not contain every possible error that Smart Router can generate. This is because banks and providers update their error code schemes from day to day without notice. We strongly recommend that you design your code to treat unfamiliar error codes as payment declines.

Soft declines:
The payment was declined, but no further information was returned
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.
The card requires a 3DS authentication to be performed, for example in the scope of 3DS2/SCA
Similarly to payment.declined, the card payment was declined with no further information
Do Not Honor is the default error code sent by bank, without any additional information
No action was done by the payment provider, and should be retried
The payment should be retried
The transaction represented a security threat during its processing and was declined
The acquirer used by the payment processor failed to process the transaction
The card holder bank failed to process the transaction
The processing failed at the acquirer or card holder bank level
The card holder bank could not process the payment
The card maximum payment attempts were reached- the customer should contact its bank
The card holder bank declined the payment, and should be contacted by your customer
The card limits were reached (ex: amounts, transactions volume) and the customer should contact its bank
The card withdrawal limit was reached, the customer should contact its bank
The card activity limit was reached, the customer should contact its bank
The card has no money left in its bank account, the customer should add more funds
The payment was blocked for potential fraud
The transaction had high chances of being a duplicate, and was declined
The payment provider could not find the card issuer bank
The payment provider failed to contact the card network to process the transaction
The card is not supported by the payment provider
The currency is not supported by this card
The card type was not supported by the payment provider
The card was not activated yet by the card holder or its bank
Hard declines:
The card was expired
The card was invalid (invalid number/expiration date/CVC)
The card has an invalid number
The card PIN was invalid. This error code does not apply for online payments
The name on the card was invalid (potential AVS failure)
The card expiration date was invalid
The card expiration month was invalid
The card expiration year was invalid
The card holder ZIP code was invalid (potential AVS failure)
The card holder address was invalid (potential AVS failure)
The card CVC was missing, but needed to process the payment
The card expiry date was missing, but needed to process the payment
The card number was missing
The card 3DS verification process was missing but needed to process the payment
The card CVC check failed
The card AVS check failed
The card AVS check failed on the postal code
The card does not support 3DS authentication (but a 3DS authentication was requested)
The card 3DS check failed
The card 3DS check expired and needs to be retried
The card AVS check failed on the address
Both the card CVC and AVS checks failed
The track data of the card was invalid (expiration date or CVC)
The card is not authorized to make the payment
The card was not yet registered and can therefore not process payments
The card was stolen
The card was lost by its card holder
The payment should not be retried
The card bank account was invalid, the customer should contact its bank
The card was revoked
All the card holder cards were revoked
The card was a test card and can’t be used to process live transactions
The card was blacklisted from the payment provider
The transaction has been blocked by ProcessOut for compliance reasons