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 card.do-not-honor) 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.