Error Handling

Getting back error messages from the processor, acquirer, or issuer is just one of those unavoidable parts of the payments landscape.

How you deal with those errors is important to your relationship with your internal and external clients.

Increase Conversion with Clear Messaging

First things first - treat your paying customers well! They're each potential brand advocates, but you have to help them get your product. Help them steer clear of avoidable mistakes. For example, in cases of typos (the credit card didn't pass a Luhn check!), data validation errors (whoops, the CVV can't be 5 digits long), or card expired (10/99 😔), you can prompt your customer with a simple note like, "It looks like some of the information you provided isn't quite right. Please check and try again." Highlighting the problem region in red is a helpful way to draw attention.

Decrease Fraud by Playing it Cool

One thing we know about fraudsters - they are always researching and gathering data, and are hard at work almost all the time. (If only they'd put their talents to use toward something more productive!) It's very important that your fraud messaging doesn't give away the farm. For example, if a fraudster is trying a card and it's declined, giving them specific information about that decline is just helping their studies. In the ecommerce world, returning "Insufficient funds" in your messaging is a good way to get a fraudster to attempt to buy something of smaller value. It's also not a great practice to tell your customer he doesn't have enough funds to purchase! We recommend generic messaging like "Hmmm... Seems like there's a problem processing this card. Please try again with a different one." Or what about - "It looks like there's a typo in what you submitted - maybe try a different card?"

For the Technical Folks:

Data validation is key! Don't send along orders with incorrect information - they'll most likely be rejected, and it's an easy fix.
Don't pass along any old 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. Looking at error reports is a great way to see if there are any integration issues or customer experience issues that are easy fixes.
Error messages are currently being returned in the synchronous response to /checkout (Card Expired, CVV Invalid, Card Number Invalid, etc) for the rest, the generic response “PaymentAuthorizationFailed” is returned.
PaymentAuthorizationFailed is a catch-all for the many errors that come back from the acquiring channel. If you receive back PaymentAuthorizationFailed, 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, but Reach doesn’t receive any other information from the acquiring channel. In this way, the message may still be somewhat vague (Processor system error, Processor error unrecognized, etc).
- If the reason for the error is still vague, display a generic error message indicating the customer to check their payment information or contact their bank as necessary.

The following is the list of payment failure errors which can show up on the Reach Admin UI. Included is extended explanation and suggested messaging for the shopper.

Error Message	Error Explanation	Suggested Shopper Messaging
Processing error from payment processor unrecognized	Whoops! We haven't quite got to defining help for this error message. Feel free to email [email protected] for further help.	n/a
Action Declined; Do Not Honor	The payment attempt was declined by the processing channel, but there we did not receive any more information forwarded regarding the reason. The error may be generated due to insufficient funds, restricted card, reported lost or stolen, etc. but there is no way to tell.	Oops! 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 indication to 'Pick Up Card' is an old error message from the banks and doesn't make much sense in the online e-commerce world of 2017.	Oops! 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. Unfortunately, we do not receive any indication of the reason for this error and 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 amount of 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. The cart may be an old card associated with an expired or closed account.	Oops! 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 restriction 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 possible fraud attempt and has refused processing of the payment. *It is very* important that this information not be provided to anyone claiming to be the cardholder, either online or via phone or 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 has insufficient 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 (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.	Authorization of the payment was not allowed possibly due to restrictions on the card. Unfortunately, no other indication of the reason is available.	Please check with your bank to make sure there are no restrictions on your card.
CVV/CID invalid	The CVV/CID code submitted was not the correct code for the card number submitted. The card may have been re-issued with a different CVV/CID code.	Please submit the correct security number. The security code is the 3 digit (Visa/Mastercard) or 4 digit (Amex) number on the bank of your card.
Card has been reported lost or stolen	The payment processing channel has identified the card submitted as having been lost or stolen and can therefore not authorize a payment. *It is very* important that this information not be provided to anyone claiming to be the cardholder, either online or via phone or 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 is in the past. Note that 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 but our operations team has been notified and will be investigating. 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 (ie card tokenization) that was submitted with the payment is invalid. This is usually an issue with the merchant's system and should be investigated. We'd be glad to help out with the investigation. Just email our tech support at [email protected] for further help.	We're 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 for to inquire about the status of your account.
Invalid amount	The amount of the payment was invalid for an unspecified reason. It could be because of restrictions on the card with respect to minimum or maximum amounts and/or online payments. This issue may also be related to the merchant's system and the way the amount was submitted. If you think this is the case, please email our tech support at [email protected] for further help.	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 authorized does not support the currency and/or payment method submitted. This is may be an issue with the Reach configuration and our operations team will be investigating. Please email our tech support at [email protected] for further help.	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 lack of information from the customer. This is another error held over from offline retail. In that environment, a phone call may have been placed by the merchant to the card issuer to provide more information, and allow authorization of the payment. In an online environment, this is unfortunately, not an option.	Oops! 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. Unfortunately we do not receive any further reasons behind the decline.	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 may be an issue with the merchant's system not collecting or properly verifying the phone number.	Please check the phone number submitted and try checking out again.
PostalCode 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 postal code provided was missing or not valid. This may be an issue with the merchant'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/state submitted with the payment attempt was not valid.	Please check the state/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 phone number submitted was invalid. This may be an issue with the merchant'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. Unfortunately, Reach doesn't receive any further information about what was actually invalid, but this is likelt be 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.
Card holder name missing	The card holder name is required for processing the payment but was not submitted with the payment. This may be an issue with the merchant's system not properly 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 useable for online payments.	Oops! 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 authorized does not support the country associated with the payment. This is typically an issue with the Reach configuration and our operations team will be investigating. Please email our tech support at [email protected] for further help.	Unfortunately, we cannot process your payment at this time. We are investigating the issue.
Invalid instalments	In Mexico and Brazil, shoppers are able to 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 not valid for the shopper's country. This may be an issue with the merchant's system not properly displaying the instalment 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, likely because there is already an existing refund posted against the payment. Feel free to email [email protected] f for further help.	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 already associated with the payment. Feel free to email [email protected] for further help.	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 further help.	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 (ie 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 indication of fraud associated with this contract. Feel free to email [email protected] for further help.	We're 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 instalments in Mexico and Brazil. This is may be issue with the Reach configuration and our operations team will be investigating. Please email our tech support at [email protected] for further help.	We're sorry. We are unable to process your payment at this time.
Card is not a test card	The card that was submitted was a real card and not meant to be used 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 merchant 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 (eg PayPal). If you still wish to complete this order please choose another payment method or complete the payment at 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 (aka funding source) used at PayPal was not able to be charged for the PayPal payment.	Unfortunately your PayPal funding source could not be used to complete this payment. Please pick another payment method or, if you still wish to checkout 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. This typically happens with short lived 'virtual' cards which are generated with a 1 hour expiry time. For this reason, these cards are not appropriate for recurring transactions.	The card number provided is no longer valid. Please enter an alternate card number or choose an alternate payment method.
Authentication Failed	The authentication process either failed due to a technical issue or the customer failed to authenticate successful. This error may be returned for 3DS authentication or payment method authentication.	Unfortunately authentication failed and is required for this transaction, please try again.