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 codeDescription
Hard declines:
gateway.possible-fraudThe transaction is flagged as a potential fraud risk.
gateway.blockedThe gateway or merchant account has been blocked or restricted.
card.possible-fraudThe payment was blocked for potential fraud
card.blacklistedThe card was blacklisted from the payment provider
card.stolenThe card was stolen
card.lostThe card was lost by its card holder
card.security-violationThe transaction represented a security threat during its processing and was declined
card.keep-cardThe card needs to be kept or retained.
card.authorization-revokedThe authorization for the card transaction has been revoked.
Soft declines:
payment.declinedThe payment was declined, but no further information was returned
gateway.declinedThe 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-authenticationThe card requires a 3DS authentication to be performed, for example in the scope of 3DS2/SCA
card.declinedSimilarly to payment.declined, the card payment was declined with no further information
card.do-not-honorDo Not Honor is the default error code sent by bank, without any additional information
card.no-action-takenNo action was done by the payment provider, and should be retried
card.please-retryThe payment should be retried
card.acquirer-failedThe acquirer used by the payment processor failed to process the transaction
card.issuer-failedThe card holder bank failed to process the transaction
card.processing-errorThe processing failed at the acquirer or card holder bank level
card.issuer-downThe card holder bank could not process the payment
card.maximum-attemptsThe card maximum payment attempts were reached- the customer should contact its bank
card.contact-bankThe card holder bank declined the payment, and should be contacted by your customer
card.exceeded-limitsThe card limits were reached (ex: amounts, transactions volume) and the customer should contact its bank
card.exceeded-withdrawal-limitThe card withdrawal limit was reached, the customer should contact its bank
card.exceeded-activity-limitsThe card activity limit was reached, the customer should contact its bank
card.no-moneyThe card has no money left in its bank account, the customer should add more funds
card.duplicateThe transaction had high chances of being a duplicate, and was declined
card.issuer-not-foundThe payment provider could not find the card issuer bank
card.network-failedThe payment provider failed to contact the card network to process the transaction
card.not-supportedThe card is not supported by the payment provider
card.currency-unsupportedThe currency is not supported by this card
card.type-not-supportedThe card type was not supported by the payment provider
card.not-activatedThe card was not activated yet by the card holder or its bank
card.expiredThe card was expired
card.invalidThe card was invalid (invalid number/expiration date/CVC)
card.invalid-numberThe card has an invalid number
card.invalid-pinThe card PIN was invalid. This error code does not apply for online payments
card.invalid-nameThe name on the card was invalid (potential AVS failure)
card.invalid-expiry-dateThe card expiration date was invalid
card.invalid-expiry-monthThe card expiration month was invalid
card.invalid-expiry-yearThe card expiration year was invalid
card.invalid-zipThe card holder ZIP code was invalid (potential AVS failure)
card.invalid-addressThe card holder address was invalid (potential AVS failure)
card.missing-cvcThe card CVC was missing, but needed to process the payment
card.missing-expiryThe card expiry date was missing, but needed to process the payment
card.missing-numberThe card number was missing
card.missing-3dsThe card 3DS verification process was missing but needed to process the payment
card.failed-cvcThe card CVC check failed
card.failed-avsThe card AVS check failed
card.failed-avs-postalThe card AVS check failed on the postal code
card.unsupported-3dsThe card does not support 3DS authentication (but a 3DS authentication was requested)
card.failed-3dsThe card 3DS check failed
card.expired-3dsThe card 3DS check expired and needs to be retried
card.failed-avs-addressThe card AVS check failed on the address
card.failed-cvc-and-avsBoth the card CVC and AVS checks failed
card.bad-track-dataThe track data of the card was invalid (expiration date or CVC)
card.not-authorizedThe card is not authorized to make the payment
card.not-registeredThe card was not yet registered and can therefore not process payments
card.dont-retryThe payment should not be retried
card.invalid-accountThe card bank account was invalid, the customer should contact its bank
card.revokedThe card was revoked
card.revoked-allAll the card holder cards were revoked
card.testThe card was a test card and can't be used to process live transactions
card.acquirer-not-foundThe acquirer or payment processor was not found or recognized.
card.already-blockedThe card is already blocked or restricted.
card.already-capturedThe card transaction has already been captured or completed.
card.already-refusedThe card transaction has already been refused.
card.approve-after-identificationThe card transaction requires additional identification for approval.
card.canceled-by-clientThe card transaction was canceled by the client.
card.cannot-verify-pinThe PIN for the card cannot be verified.
card.contact-acquirerThe cardholder needs to contact the acquirer or payment processor for further assistance.
card.couldnt-3dsThe 3D Secure authentication for the card transaction could not be performed.
card.eci-conflictThere is a conflict with the Electronic Commerce Indicator (ECI) for the card transaction.
card.exceeded-maximum-amountThe card transaction amount has exceeded the maximum allowed amount.
card.exceeded-pin-attemptsThe number of PIN attempts for the card has been exceeded.
card.exemption-declinedThe exemption for the card transaction has been declined.
card.failed-3ds-technicalThere was a technical failure with the 3D Secure authentication for the card transaction.
card.formatting-errorThere was an error with the formatting of the card transaction.
card.high-riskThe card transaction is flagged as high risk.
card.holder-not-authorizedThe cardholder is not authorized for the card transaction.
card.inactiveThe card is inactive and cannot be used for the transaction.
card.invalid-amountThe specified amount for the card transaction is invalid.
card.invalid-avsThe Address Verification Service (AVS) for the card is invalid.
card.invalid-bank-country-codeThe country code of the card's issuing bank is invalid.
card.invalid-brandThe card brand or type is invalid or not supported.
card.invalid-cvcThe Card Verification Code (CVC) or Card Security Code (CSC) for the card is invalid.
card.invalid-eciThe Electronic Commerce Indicator (ECI) for the card transaction is invalid.
card.invalid-merchantThe merchant for the card transaction is invalid.
card.invalid-paresThe Payment Authentication Response (PARES) for the card transaction is invalid.
card.invalid-schemeThe card scheme or network is invalid or not supported.
card.invalid-transactionThe card transaction is invalid.
card.invalid-ucafThe Universal Cardholder Authentication Field (UCAF) for the card transaction is invalid.
card.invalid-vpasThe Verified by Visa (VbV) or Mastercard SecureCode (MSC) validation for the card transaction is invalid.
card.issuer-maintenanceThe issuer or bank of the card is currently undergoing maintenance.
card.issuer-malfunctionThe issuer or bank of the card is experiencing a malfunction.
card.law-violationThe card transaction violates laws or regulations.
card.missing-avsThe Address Verification Service (AVS) data is missing.
card.missing-nameThe cardholder name is missing.
card.missing-pinThe PIN (Personal Identification Number) is missing for the card transaction.
card.no-cheque-accountNo cheque account is associated with the card.
card.no-credit-accountNo credit account is associated with the card.
card.no-savings-accountNo savings account is associated with the card.
card.not-foundThe card information or account was not found.
card.pendingThe card transaction is pending or in progress.
card.physical-authentication-errorThere was an error with the physical authentication of the card.
card.pin-not-changedThe PIN for the card cannot be changed.
card.possible-counterfeitThe card transaction is flagged as a possible counterfeit.
card.reauthorization-not-allowedReauthorization is not allowed for the card transaction.
card.region-not-authorizedThe card transaction is not authorized in the specified region.
card.restrictedThe card is restricted and cannot be used for the transaction.
card.surcharge-not-allowedSurcharge fees are not allowed for the card transaction.
card.surcharge-not-supportedSurcharge fees are not supported for the card transaction.
card.terminal-not-allowedThe card is not allowed at the terminal or point of sale.
card.terminal-not-foundThe card terminal was not found or recognized.
card.terminal-not-initializedThe card terminal is not initialized and cannot be used.
card.timeoutThe card transaction timed out.
card.transaction-not-processedThe card transaction was not processed.
card.unsupported-3ds2The 3D Secure 2 authentication is not supported for the card transaction.
customer.cancelledThe customer has canceled the transaction.
customer.disputedThe transaction is disputed by the customer.
customer.invalid-addressThe address of the customer is invalid.
customer.invalid-cityThe city of the customer is invalid.
customer.invalid-country-codeThe country code of the customer is invalid.
customer.invalid-emailThe email address for the customer is invalid.
customer.invalid-firstnameThe first name of the customer is invalid.
customer.invalid-ip-addressThe IP address of the customer is invalid.
customer.invalid-lastnameThe last name of the customer is invalid.
customer.invalid-legal-documentThe legal document of the customer is invalid.
customer.invalid-nameThe name of the customer is invalid.
customer.invalid-phone-numberThe phone number of the customer is invalid.
customer.invalid-stateThe state of the customer is invalid.
customer.invalid-zipThe ZIP code of the customer is invalid.
gateway.configuration-errorThere is an error or issue with the gateway configuration.
gateway.duplicateThe transaction is a duplicate or has already been processed in the gateway.
gateway.expiredThe transaction or authorization has expired in the gateway.
gateway.forbiddenAccess to the gateway is forbidden or not allowed.
gateway.internal-errorAn internal error occurred in the gateway.
gateway.invalid-billing-addressThe billing address provided is invalid in the gateway.
gateway.invalid-credentialsThe provided credentials for the gateway are invalid.
gateway.invalid-merchantThe merchant or account in the gateway is invalid.
gateway.invalid-repeatThe repeat transaction or request is invalid in the gateway.
gateway.invalid-stateThe state or status of the transaction is invalid in the gateway.
gateway.limit-exceededA limit or threshold has been exceeded in the gateway.
gateway.maintenanceThe gateway is currently undergoing maintenance.
gateway.network-errorThere was a network error in the gateway.
gateway.not-allowedThe requested action or method is not allowed in the gateway.
gateway.not-foundThe requested resource or endpoint was not found in the gateway.
gateway.rate-limit-exceededThe rate limit for the gateway has been exceeded.
gateway.retryThe transaction or request should be retried in the gateway
gateway.timeoutThe request to the gateway timed out.
gateway.transaction-not-foundThe requested transaction was not found in the gateway.
gateway.transaction-pendingThe transaction is pending or in progress in the gateway.
gateway.unknown-errorAn unknown error occurred in the gateway.
gateway.unsupported-country-codeThe requested country code is not supported in the gateway.
gateway.unsupported-currencyThe requested currency is not supported in the gateway.
gateway.validation-errorThere was an error validating the request in the gateway.
request.transaction-blockedThe transaction has been blocked by ProcessOut for compliance reasons