Error codes management
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. ProcessOut uses its own set of error codes as an abstraction over these different systems. This means that you will see the same ProcessOut 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.
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 Transaction operations 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 ProcessOut 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.
It's also possible to configure transaction retries on a fallback gateway based on specific error codes returned by a prior gateway. This configuration is set at the routing rule level and can be disabled or enabled based on your preferences.
List of error codes
There are 2 types of error code:
- Soft declines represent failed transactions that ProcessOut 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 ProcessOut returns is given below.
The list does not contain every possible error that ProcessOut 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.
| Error code | Description |
|---|---|
| Hard declines: | |
| gateway.possible-fraud | The transaction is flagged as a potential fraud risk. |
| gateway.blocked | The gateway or merchant account has been blocked or restricted. |
| card.possible-fraud | The payment was blocked for potential fraud |
| card.blacklisted | The card was blacklisted from the payment provider |
| card.stolen | The card was stolen |
| card.lost | The card was lost by its card holder |
| card.security-violation | The transaction represented a security threat during its processing and was declined |
| card.keep-card | The card needs to be kept or retained. |
| card.authorization-revoked | The authorization for the card transaction has been revoked. |
| 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.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.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 |
| 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.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.acquirer-not-found | The acquirer or payment processor was not found or recognized. |
| card.already-blocked | The card is already blocked or restricted. |
| card.already-captured | The card transaction has already been captured or completed. |
| card.already-refused | The card transaction has already been refused. |
| card.approve-after-identification | The card transaction requires additional identification for approval. |
| card.canceled-by-client | The card transaction was canceled by the client. |
| card.cannot-verify-pin | The PIN for the card cannot be verified. |
| card.contact-acquirer | The cardholder needs to contact the acquirer or payment processor for further assistance. |
| card.couldnt-3ds | The 3D Secure authentication for the card transaction could not be performed. |
| card.eci-conflict | There is a conflict with the Electronic Commerce Indicator (ECI) for the card transaction. |
| card.exceeded-maximum-amount | The card transaction amount has exceeded the maximum allowed amount. |
| card.exceeded-pin-attempts | The number of PIN attempts for the card has been exceeded. |
| card.exemption-declined | The exemption for the card transaction has been declined. |
| card.failed-3ds-technical | There was a technical failure with the 3D Secure authentication for the card transaction. |
| card.formatting-error | There was an error with the formatting of the card transaction. |
| card.high-risk | The card transaction is flagged as high risk. |
| card.holder-not-authorized | The cardholder is not authorized for the card transaction. |
| card.inactive | The card is inactive and cannot be used for the transaction. |
| card.invalid-amount | The specified amount for the card transaction is invalid. |
| card.invalid-avs | The Address Verification Service (AVS) for the card is invalid. |
| card.invalid-bank-country-code | The country code of the card's issuing bank is invalid. |
| card.invalid-brand | The card brand or type is invalid or not supported. |
| card.invalid-cvc | The Card Verification Code (CVC) or Card Security Code (CSC) for the card is invalid. |
| card.invalid-eci | The Electronic Commerce Indicator (ECI) for the card transaction is invalid. |
| card.invalid-merchant | The merchant for the card transaction is invalid. |
| card.invalid-pares | The Payment Authentication Response (PARES) for the card transaction is invalid. |
| card.invalid-scheme | The card scheme or network is invalid or not supported. |
| card.invalid-transaction | The card transaction is invalid. |
| card.invalid-ucaf | The Universal Cardholder Authentication Field (UCAF) for the card transaction is invalid. |
| card.invalid-vpas | The Verified by Visa (VbV) or Mastercard SecureCode (MSC) validation for the card transaction is invalid. |
| card.issuer-maintenance | The issuer or bank of the card is currently undergoing maintenance. |
| card.issuer-malfunction | The issuer or bank of the card is experiencing a malfunction. |
| card.law-violation | The card transaction violates laws or regulations. |
| card.missing-avs | The Address Verification Service (AVS) data is missing. |
| card.missing-name | The cardholder name is missing. |
| card.missing-pin | The PIN (Personal Identification Number) is missing for the card transaction. |
| card.no-cheque-account | No cheque account is associated with the card. |
| card.no-credit-account | No credit account is associated with the card. |
| card.no-savings-account | No savings account is associated with the card. |
| card.not-found | The card information or account was not found. |
| card.pending | The card transaction is pending or in progress. |
| card.physical-authentication-error | There was an error with the physical authentication of the card. |
| card.pin-not-changed | The PIN for the card cannot be changed. |
| card.possible-counterfeit | The card transaction is flagged as a possible counterfeit. |
| card.reauthorization-not-allowed | Reauthorization is not allowed for the card transaction. |
| card.region-not-authorized | The card transaction is not authorized in the specified region. |
| card.restricted | The card is restricted and cannot be used for the transaction. |
| card.surcharge-not-allowed | Surcharge fees are not allowed for the card transaction. |
| card.surcharge-not-supported | Surcharge fees are not supported for the card transaction. |
| card.terminal-not-allowed | The card is not allowed at the terminal or point of sale. |
| card.terminal-not-found | The card terminal was not found or recognized. |
| card.terminal-not-initialized | The card terminal is not initialized and cannot be used. |
| card.timeout | The card transaction timed out. |
| card.transaction-not-processed | The card transaction was not processed. |
| card.unsupported-3ds2 | The 3D Secure 2 authentication is not supported for the card transaction. |
| customer.cancelled | The customer has canceled the transaction. |
| customer.disputed | The transaction is disputed by the customer. |
| customer.invalid-address | The address of the customer is invalid. |
| customer.invalid-city | The city of the customer is invalid. |
| customer.invalid-country-code | The country code of the customer is invalid. |
| customer.invalid-email | The email address for the customer is invalid. |
| customer.invalid-firstname | The first name of the customer is invalid. |
| customer.invalid-ip-address | The IP address of the customer is invalid. |
| customer.invalid-lastname | The last name of the customer is invalid. |
| customer.invalid-legal-document | The legal document of the customer is invalid. |
| customer.invalid-name | The name of the customer is invalid. |
| customer.invalid-phone-number | The phone number of the customer is invalid. |
| customer.invalid-state | The state of the customer is invalid. |
| customer.invalid-zip | The ZIP code of the customer is invalid. |
| gateway.configuration-error | There is an error or issue with the gateway configuration. |
| gateway.duplicate | The transaction is a duplicate or has already been processed in the gateway. |
| gateway.expired | The transaction or authorization has expired in the gateway. |
| gateway.forbidden | Access to the gateway is forbidden or not allowed. |
| gateway.internal-error | An internal error occurred in the gateway. |
| gateway.invalid-billing-address | The billing address provided is invalid in the gateway. |
| gateway.invalid-credentials | The provided credentials for the gateway are invalid. |
| gateway.invalid-merchant | The merchant or account in the gateway is invalid. |
| gateway.invalid-repeat | The repeat transaction or request is invalid in the gateway. |
| gateway.invalid-state | The state or status of the transaction is invalid in the gateway. |
| gateway.limit-exceeded | A limit or threshold has been exceeded in the gateway. |
| gateway.maintenance | The gateway is currently undergoing maintenance. |
| gateway.network-error | There was a network error in the gateway. |
| gateway.not-allowed | The requested action or method is not allowed in the gateway. |
| gateway.not-found | The requested resource or endpoint was not found in the gateway. |
| gateway.rate-limit-exceeded | The rate limit for the gateway has been exceeded. |
| gateway.retry | The transaction or request should be retried in the gateway |
| gateway.timeout | The request to the gateway timed out. |
| gateway.transaction-not-found | The requested transaction was not found in the gateway. |
| gateway.transaction-pending | The transaction is pending or in progress in the gateway. |
| gateway.unknown-error | An unknown error occurred in the gateway. |
| gateway.unsupported-country-code | The requested country code is not supported in the gateway. |
| gateway.unsupported-currency | The requested currency is not supported in the gateway. |
| gateway.validation-error | There was an error validating the request in the gateway. |
| request.transaction-blocked | The transaction has been blocked by ProcessOut for compliance reasons |
Updated 7 months ago