What is a Payment Gateway Error/Decline Code?

A payment gateway decline (or error) code represents a standard type of response from a card issuer or payment processor during a transaction that cannot be completed. These codes offer an explanation for the result of a transaction, such as if a card has expired, a processing pause occurs, or there are certain requirements set by the bank. Merchants look at these codes to better understand payment results and choose their next steps. Within subscription services, these codes help guide how billing systems approach payment attempts and retries.

Payment error codes represent a range of scenarios, so approaching each one the same way doesn’t provide the most suitable response.

A soft decline generally means the event is temporary, such as when an account doesn’t have available funds at the moment, the bank has temporarily held the payment, or the card issuer’s system requires another attempt. In many instances, resubmitting the transaction after some time may allow it to proceed.

Alternatively, a hard decline reflects a separate category – for instance, if an account has been updated, a card has reached expiration, or an issuer’s system sends a message to indicate a different handling is needed. For these types, further retries are generally not conducted, and the payment processor notes the decline result before moving on. 

Recognizing the category of each error code helps payment systems choose whether to schedule another attempt or, when appropriate, notify the customer to update their payment information.

For organizations working with recurring payments, renewal cycles regularly require analyzing decline codes. Involuntary churn can arise from payment outcomes, even in cases where there has been no direct cancellation. Looking at decline codes allows companies to assess whether another payment attempt or a payment information update request is appropriate as part of their billing process.

Decline codes also give information on fraud prevention and occasionally reveal patterns, like repeated declines with stolen cards. Reviewing the patterns of hard declines provides businesses with criteria for determining if further investigation of certain payment activities is needed.

Usage tips:

• Start by sorting each decline code into a soft or hard type to provide a better overview for retry logic.
• Allow for some time between retries; trying payment methods again after a few days can present new outcomes compared to back-to-back attempts.
• Adjust the timing of retries in line with the customer’s likely payday or billing routines.
• Limit retries to a reasonable number, such as three or four, to stay consistent with issuer recommendations.
• Include clear customer communication with automated retries, suggesting a card update if needed.

Account Updater services are used to handle instances where card details stored on file are no longer up to date, which can sometimes occur with attempted transactions. When a new card is issued for a customer (for example, after an expiration, replacement, or security update), the older card information is removed from active use. In these cases, Account Updater tools are set up to communicate with card brands like Visa and Mastercard and provide updates to saved account information, and this process typically operates independently of customer involvement.

Card networks such as Visa and Mastercard publish rules for how often a merchant can retry declined payments. Repeated attempts beyond these suggested thresholds, including with hard declines, can lead the networks to review activity or adjust standard charges. Following these rules when planning retries for soft declines is a way for businesses to stay within general industry practices. This is why SaaS companies choose a Merchant of Record to help manage retry approaches so that they reflect updated requirements.

Reviewing a few considerations can be useful before making any adjustments to your approach:

• Are you able to identify what share of your failed payments are soft compared to hard declines?
• Is it possible to locate and measure involuntary churn within your revenue data?
• Do you vary your retry process based on decline type, or follow the same pattern for each attempt?

Decision factors:

• How many transactions occur, and the share of involuntary churn in the context of your results
• The way your payment setup organizes decline information, and if different decline types are distinguished
• Whether automated card updater services are accessible for your business
• The current level of in-house engineering capacity available to set up or update retry logic
• Regulatory and card scheme obligations and limits that apply to your business activities