There are many reasons why a credit card will fail. Handling more error types means better customer facing error messaging and improved card handling. Imagine the difference between telling a customer "your credit card was declined, check the number and try again" versus "your credit card is perfectly valid, but has a restriction that prevents it from being used with us. Please try a different card." Clear error message eliminate the customer confusion and follow up support.

Recurly handles declined cards differently depending on when they occur: during signup or at renewal. Offering the customer guidance for every unique error code at signup can dramatically improve the customer signup experience. At renewal, it's also very important to properly categorize these errors and treat them appropriately to increase customer retention, which leads to greater revenue over the lifetime of your customers.

The errors returned by your gateway will vary, but can be broken down into a few common categories. For the curious, Recurly distinctly handles over 60 error types. Generally, these fall into 5 categories within our system:

  • Soft Decline - The card number is probably valid but was denied by the issuing bank. If a soft decline occurs on a renewal, retrying the card at a later date may work.

  • Hard Decline - The credit card was declined by the issuing bank or card processor. Retrying the card number will never work. If a hard decline occurs on a renewal, retrying the card at a later date will never work.

  • Fraud Prevention - The transaction was prevented because the transaction could be fraudulent.

  • Communication - There was an issue communicating with the payment gateway, the gateway was too busy, or the gateway did not return a response in time.

  • Misconfiguration or Merchant Error - The customer's card type is not accepted by the merchant or gateway, the currency unit is bad, or the gateway credentials are no longer valid. These issues are fixable or avoidable, so they are surfaced to Recurly support.

We regularly review all the failed transactions going through Recurly to proactively reach out to merchants and help them fix any issues. Next week, we're rolling out new code to proactively notify us about errors from the misconfiguration category. It's our mission to handle all these complexities so you can focus on developing your service.