HomeDocumentationAPI Reference
Documentation

Error handling

Understand error messages and what you can do in response

Receiving error messages from the processor, acquirer, or issuer is just one of those unavoidable aspects of the payments landscape. How you handle those errors is crucial to your relationship with both internal and external clients.

Checkout API and error messaging

Error messages are currently being returned in the synchronous response to /checkout (e.g., Card Expired, CVV Invalid, Card Number Invalid, etc.). For the rest, the generic response “PaymentAuthorizationFailed” is returned.

PaymentAuthorizationFailed is a catch-all response for many errors that come back from the acquiring channel. If you receive a PaymentAuthorizationFailed response, then /query may be used to dig deeper and determine the error that way. The reason field returned by /query will be as specific as possible; however, since Reach doesn’t receive any other information from the acquiring channel, the message may be somewhat vague (e.g., Processor system error, Processor error unrecognized).

If the reason for the error remains unclear, display a generic error message instructing the customer to verify their payment information or contact their bank.

Reach caution sign

Types of error messages and suggested responses

Below is a list of payment failure errors that can appear in the Reach Admin. Each error message is accompanied by an explanation and a suggested response message to display to the shopper. If you require assistance, please reach out to the Reach support team at [email protected].

Error message

Explanation

Suggested shopper messaging

Processing error from payment processor unrecognized

This is an unrecognized error message from our downstream processor. For further details on the error and why it happened, reach out to [email protected].

We are sorry. We are unable to process your payment at this time. Please try again or use another payment method.

Action Declined; Do Not Honor

The processing channel declined the payment attempt, but Reach did not receive a reason. The error may be due to insufficient funds, a restricted card, or the card being reported as lost or stolen, among other reasons. There is no way to determine the cause.

We are sorry we can’t process your payment right now. Please contact your bank.

Action Declined; Pick Up Card

If the card has been stolen, lost, reissued, or the account has been closed, any attempt to process a transaction will fail. The 'Pick Up Card' indication is an outdated error message that doesn't make much sense in the current online ecommerce world.

We are sorry we can’t process your payment right now. Please contact your bank.

Declined by Issuing Bank

The customer’s bank account has rejected the transaction. Reach did not receive a reason for this error. The best course of action is for the shopper to inquire at their bank.

Please check with your bank to make sure there are no restrictions on your card.

Amount exceeds shopper account limit.

The card submitted for payment has a per-transaction amount limit associated with it, and the payment attempt exceeds that limit.

Please check with your bank to make sure there are no restrictions on your card.

Invalid Card Number

The card number submitted is not a valid card number on file with the banks. It may be an old card associated with an expired or closed account.

Is that the correct number on your card? Please try entering the number again.

Restricted Card

The card submitted for the payment attempt has some restrictions on it, likely related to the currency or online nature of the payment attempt.

Please check with your bank to make sure there are no restrictions on your card.

Suspected Fraud

The payment processing channel has identified this transaction as a potential fraud attempt and has declined to process the payment.

It is important that this error reason is not provided to anyone claiming to be the cardholder, either online, via phone, or via text.

If you have further questions, please contact our fraud team at [email protected].

We are sorry. This payment cannot be processed at this time.

Insufficient Funds

The customer’s account does not have sufficient funds to complete the transaction. For a credit card, this may mean they would reach their credit card limit if the transaction were allowed to proceed.

We are unable to process this payment with the card data provided. Please try with a different card.

Invalid Address Input

The address information submitted with the payment was invalid. This usually means that one of the address fields (such as street address, city, etc.) was blank, non-alphabetic, or otherwise unreadable.

Unfortunately, we were unable to process this payment with the information provided. Please check your address information and try again.

Processing not permitted/authorized.

Payment authorization was not allowed, possibly due to restrictions on the card. Reach did not receive a reason for this error.

Please check with your bank to make sure there are no restrictions on your card.

CVV/CID invalid

The CVV or CID code was not the correct code for the submitted card number. The card may have been reissued with a different CVV or CID code.

Please submit the correct security number. The security code is the 3-digit (for Visa/Mastercard) or 4-digit (for American Express) number located on the back of your card.

Card has been reported lost or stolen

The payment processing channel has identified the submitted card as being lost or stolen and cannot authorize the payment.

It is important that this error reason is not provided to anyone claiming to be the cardholder, either online, via phone, or via text.

If you have further questions, please contact our fraud team at ([email protected]).

We are sorry. This payment cannot be processed at this time.

Card Expired

The expiry date associated with the card has passed. The customer may have submitted a future card expiry date, but the processing channel identified the actual expiry date for the card as being in the past.

We are unable to process your payment. Please check the expiry date on the card submitted or try another card.

Refused by processor

The processor has refused to authorize the payment with the payment information provided.

Please check the payment information submitted or try an alternative payment method.

Processor System Error

The processing channel has returned a system-level error to the Reach system. These errors tend to be temporary; however, our operations team has been notified and will investigate the issue. Feel free to email [email protected] to inquire about the investigation.

Unfortunately, we've encountered a system error. Please try checking out again.

Invalid National Identifier

For some countries, such as Brazil (CPF), a national tax or citizenship identifier is required for processing online payments. This error indicates that the national identifier submitted was invalid.

Please check the national identifier value submitted and try again.

Invalid birthday input

For some countries, such as Brazil, the customer's birthday is required for processing an online payment. This error indicates the birthday submitted was invalid.

Please check the birthday value submitted and try again.

Contract not found

This error indicates that the contract (i.e., card tokenization) that was submitted with the payment is invalid. This is usually an issue with the supplier's system and should be investigated. We are happy to help you investigate, please reach out to [email protected].

We are sorry. We are unable to process your payment at this time.

Cancelled at payment provider or bank

The bank or payment provider has cancelled this payment for an unknown reason.

Please check the payment information submitted or try an alternative payment method. If the problem persists, please contact your bank to inquire about the status of your account.

Invalid amount

The payment amount was invalid for an unspecified reason. It could be due to restrictions on the card regarding minimum or maximum amounts and/or online payments.

This issue may also be related to the supplier's system and the way the amount was submitted. Feel free to contact [email protected] for assistance.

Unfortunately, we cannot process your payment at this time. Please check with your bank to make sure there are no restrictions on your card.

Processor does not support currency or method.

The processing channel used to attempt payment authorization does not support the currency and/or payment method submitted. This may be an issue with Reach's configuration. Our operations team will investigate. Feel free to email [email protected] to inquire about the investigation.

Unfortunately, we cannot process your payment at this time. We are investigating the issue.

Referral requested; not enough information.

The processing channel declined to authorize the payment due to a lack of information from the customer. This is an error carried over from offline retail, where the supplier could make a phone call to the card issuer to provide additional information and facilitate payment authorization. In an online environment, this is not an option.

We are sorry. We can’t process your payment right now. Please contact your bank.

Declined by acquiring bank

The acquiring bank has declined to process the payment. Reach did not receive a reason for this error.

Please check the payment information submitted or try an alternative payment method.

Phone number required for currency/country.

For some countries, a phone number associated with the payment method is required to process an online payment. This error indicates that the phone number was missing. This could be an issue with the supplier's system not collecting or properly verifying the phone number.

Please check the phone number submitted and try checking out again.

Postal code is invalid or is missing, but is required.

In most countries, a postal/zip code associated with the payment method is required for processing an online payment. This error indicates that the provided postal code was missing or invalid. This could be an issue with the supplier's system not collecting or properly verifying the postal code.

Please check the postal code submitted and try checking out again.

Invalid State/Province

The province or state submitted with the payment attempt was not valid.

Please check the state or province submitted with the payment attempt and try checking out again.

Invalid Phone Number

For some countries and/or currencies, a phone number associated with the payment method is required to process an online payment. This error indicates that the submitted phone number is invalid. This could be an issue with the supplier's system not collecting or properly verifying the phone number.

Please check the phone number or try an alternative payment method.

Invalid Customer Data

Some portion of the customer data submitted with the payment attempt was invalid. Reach does not receive any further information about what was invalid. This is likely due to the customer name and/or address not matching what is on file with the banks.

Please check the payment information submitted and try checking out again.

Cardholder name missing

The cardholder's name is required for processing the payment, but was not submitted with the payment. This could be an issue with the supplier's system improperly submitting the payment information.

Please check the payment information submitted or try an alternative payment method.

Cardholder account not valid credit account

The account associated with the card data submitted is not a valid credit account for online payments.

We are sorry we can’t process your payment right now. Please contact your bank.

Processor does not support country.

The processing channel used to attempt payment authorization does not support the country associated with the payment. This is typically an issue with Reach's configuration, and our operations team will be investigating. Please email our support team at [email protected].

Unfortunately, we cannot process your payment at this time. We are investigating the issue.

Invalid instalments

In Mexico and Brazil, shoppers can pay in instalments. The number of instalments available depends on the shopper's country. This error indicates that the number of instalments submitted with the payment attempt was invalid for the shopper's country. This could be an issue with the supplier's system improperly displaying the installment options for the shopper's country.

We're sorry. We are unable to process your payment at this time.

Invalid refund amount

The amount submitted for refund against this payment was invalid. There is likely an existing refund posted against the payment. Feel free to email [email protected] for assistance.

Unfortunately, we are not able to process the refund at this time. Our team is investigating and will get back to you as soon as possible.

Refund refused by processor

The payment processor refused to process a refund against this payment. There may be an existing refund or a chargeback associated with the payment. Feel free to email [email protected] for assistance.

Unfortunately, we are not able to process the refund at this time. Our team is investigating and will get back to you as soon as possible.

Cancel refused by processor

The payment processor cannot cancel the payment. This may be due to the payment already being cancelled or captured. Feel free to email [email protected] for assistance.

Unfortunately, we are not able to cancel this payment at this time. Our team is investigating and will get back to you as soon as possible.

Contract no longer usable

This error indicates that the contract (i.e., card tokenization) that was submitted with the payment attempt is no longer available for new payments. This may be due to a previously failed authorization or an indication of fraud associated with this contract. Feel free to email [email protected] for assistance.

We are sorry. We are unable to process your payment at this time.

Instalments not supported by issuer

The issuing bank associated with the card data submitted does not support installments in Mexico and Brazil. This may be an issue with Reach's configuration. Our operations team will investigate. Please email [email protected] for further assistance.

We are sorry. We are unable to process your payment at this time.

Card is not a test card

The submitted card was a real card and not intended for use in a test environment.

N/A

Cancelled by shopper at external payment provider

The customer has explicitly cancelled the transaction at the external payment provider. For example, they may have clicked on the "Cancel and return to supplier site" link after they were redirected to PayPal. The customer will have to initiate another payment attempt.

You have cancelled this order at the external service provider (e.g., PayPal). If you still wish to complete this order, please select an alternative payment method or proceed with the payment through the external service.

Authorization expired before capture

The processor expired the authorization before the request to capture was forwarded to them. In this case, the shopper will have to authorize a new transaction.

N/A

PayPal method failed

The method (also known as the funding source) used at PayPal was unable to be charged for the PayPal payment.

Unfortunately, your PayPal funding source could not be used to complete this payment. Please select an alternative payment method or, if you still wish to proceed with PayPal, choose an alternate payment source when redirected to the PayPal website.

Card number no longer valid

The card number provided is no longer valid. Typically, this occurs with short-lived 'virtual' cards, which are generated with a 1-hour expiry time. These cards are not appropriate for recurring transactions.

The card number provided is no longer valid. Please enter an alternative card number or choose a different payment method.

Authentication Failed

The authentication process either failed due to a technical issue or the customer failed to authenticate successfully. This error may be returned for 3DS authentication or for payment method authentication.

Unfortunately authentication failed and is required for this transaction, please try again.

Errors within the Checkout API

The following errors can be recognized within Reach's Checkout API for error handling.

Note

Please note that not all error messaging is handled with error codes, as some declines do not provide a reason.

Payment Error IDTextReason Code
1Action DeclinedDo not Honor
3Declined by Issuing BankDeclinedByIssuer
6Restricted CardRestrictedCard
7Suspected FraudSuspectedFraud
8Insufficient FundsInsufficientFunds
10Processing not permitted/authorized.Unauthorized
15Refused by ProcessorRefusedByProcessor
16Processor System ErrorProcessorSystemError
21Cancelled at payment provider or bankCancelledAtBank
23Processor does not support currency or method.CurrencyNotSupported
25Referral requested; not enough information.Referral
26Declined by acquiring bankDeclinedByAcquirer
33Invalid Customer DataInvalidCustomerData
34Cardholder name missingCardholderNameMissing
37Cardholder account not valid credit accountCardholderAccountInvalid
39Processor does not support country.CountryNotSupported
47Card is not a test cardNotATestCard
49Authorization expired before captureAuthorizationExpired
50PayPal method failedPayPalMethodFailed
51Card number no longer validCardNoLongerValid
53Authentication FailedAuthenticationFailed
57Authentication RequiredSoftDecline
1058Consumer not foundConsumerNotFound
1059Invalid CurrencyInvalidCurrency
Reach checkmark

Best practices for handling errors

Errors will occur, but there are a few things you can do to reduce the number of avoidable ones.

  • Data validation is essential. Do not pass along orders with incorrect information, as they will most likely be rejected.
  • Do not display a generic error message to your customer. Brand it so that your customer's experience is seamless throughout checkout—even when there's a problem with their card.
  • Review errors often. Reviewing error reports is a great way to identify any integration or customer experience issues with easy fixes.

Increase conversion with clear messaging

Every shopper is a potential brand advocate, but first, you'll need to ensure they purchase your product. Help your customers avoid easy mistakes with clear labeling, messaging, and prompting.

When a customer makes a typo (for example, entering a five-digit CVV code), a prompt with a simple note, such as "Looks like some provided information isn't right. Please check and try again," with a highlight of the problem field, helps resolve issues quickly.

Decrease fraud with generic messages

People who commit fraud are constantly researching information and gathering data. It is important that your error messaging does not provide them with additional information.

For example, if a suspected stolen card is declined and the error message states "Insufficient funds", well, there are always cheaper things to purchase. However, if a suspected stolen card is declined and the error message states "There is a problem processing, try again with a different card," then no advantageous information has been provided.

For example

Reach recommends generic messaging. For example, the statement "Seems like there's a problem processing this card. Please try again with a different one." works well, or phrases like "It looks like there's a typo in what you submitted—maybe try a different card?" serve a similar function.