Gateway Response Codes – Part I: How They Work

January 22, 2021 by: Jeffrey Pauletto

Gateway response codes are multi-digit codes identifying whether a transaction is declined or approved. These codes will indicate what action needs to be taken, if any, to retry the transaction.

Why are response codes difficult to handle?

Handling the response codes you get from your gateway may sound easy at first, until you start seeing them yourself. A gateway first needs to map the response codes from all the different banks into unified response codes. Annoyingly, this can make for a lot of response codes – the average gateway has a little over 100, and each of them means something different, and you need to handle them differently.

The problem gets worse if you use multiple gateways. Not only will you have twice as many response codes to deal with, but they may not behave the same. Remember how the gateway maps the bank’s response codes to their own? Well, let’s imagine an example response code from Bank A says, “Generic Bank Decline – Do Not Honor.” Gateway A might look at that and map it to their code, “Bank Decline.” Gateway B might look at that same response and map it to “Do Not Honor.” Now you’re treating two gateway response codes differently, even though they’re the same. Worse yet, you can have the same response codes from two different gateways that mean very different things because the codes are bundled together.

Why isn’t this standardized?

Well, it is, and it isn’t. Back in 1987, ISO (International Organization for Standardization) came out with their version, ISO 8583:1987, and it uses a 2-digit code for all possible responses to a transaction attempt. This was revised in 1993 by ISO 85834:1993, amended in 1999 with ISO 8583:1993/COR 1:1999, and further revised into ISO 8583-1:2003, ISO 8583-2:1998 & ISO 8583-3:2003. And the fun continues, as ISO/AWI 8583 is currently under development and will probably be released around 2024.

A FlexPay analysis found that 18% of our integrated gateways conform to the 1987 version of the standard, 29% conform to one of the revised versions, and the remaining 53% have their own way of doing things. Unfortunately, that means you’re largely on your own for figuring out how to handle each appropriately. Here at FlexPay, we use machine learning models, and massive datasets to handle each decline appropriately, but here are some tips if you’re going to run with this on your own. 

Types of Response Codes

Generally, response codes will be split into five major categories:

Approvals

You’d think this would just be 1 code, but most merchants have many types of approval. We won’t go into what each of them means, but here’s an example list from 1 gateway:

As you can tell, the gateway is approving these, with the expectations that you’re logging in to the gateway platform and manually reviewing the transactions to ensure they’re legitimate – that’s not normal practice for most business owners. But if you know how many of these there are, it may indeed be worth it for you to look at them and see what can prevent these issues from happening in the future.

In FlexPay, these declines always start with a 1 (ex. 10000 – Approved).

Soft Declines

This is where the bulk of your transaction response codes will be grouped. A Soft Decline means it’s a transaction that the bank declined, but they’re explicitly allowing you to send it again later. Most of the soft declines will either be “Insufficient Funds,” “Do Not Honor,” or “Bank Decline.” Generally, the way to approve these is simply to retry them. That may sound simple, but picking the right day of the week, day of the month and time is critical to maximizing recoveries. Unfortunately, the way to find these best days and times is by leveraging a large dataset to come up with a system to best pick how to retry. You can go deeper and develop better rules that make decisions by BIN or go high-tech and build a machine learning model to make the decisions for you.

In FlexPay, these declines always start with a 2 (ex. 20003 – Do Not Honor).

Hard Declines

These are the declines you don’t want to have! Hard declines cannot be retried and are simply going to be lost customers unless you get a new credit card. VISA & Mastercard are very strict about this. Retrying a hard decline may cost you your merchant account. This is because Hard Declines tend to be reasons like “The bank has requested that you retrieve the card from the cardholder,” “Restricted Card – Pick Up,” or “Invalid Card Number.” If you retry those, you could, very occasionally, get a recovery, but 95%+ of the time you won’t, and it’ll send a red flag up that you’re doing something you shouldn’t.

In FlexPay, these declines always start with a 3 (ex. 30012 – Invalid Card Number).

Gateway Messages

These are declines that didn’t make it to the bank – your gateway denied your attempt to process it for some fundamental reason. These are for two very specific reasons: either the CVV is required and is incorrect or missing, or the gateway has blocked and blacklisted that customer (their card, IP address, shipping country, or some other attribute). The only thing you can do is fix the CVV issue. If you’re doing recurring billing, you need to ensure that the ‘recurring’ flag is set for those transactions, so you don’t get the gateway to reject the transaction for missing a CVV when it isn’t needed.

In FlexPay, these declines always start with a 4 (ex. 40003 – Gateway declined – CVV is missing or incorrect).

System Errors

These are the simplest to fix and are generally indicative of a bug in an integration. Examples include “Name required,” “Invalid Billing Address,” “Validation Error.” These are typically caught by whatever system your CRM is calling – either your gateway, FlexPay, or some other external system. Once the error is fixed, you shouldn’t see these any longer.

In FlexPay, these declines always start with a 5 (ex. 50000 – Validation error.).

The response groups above are the most common; as we mentioned earlier, the average gateway has over 100 codes. You are likely starting to understand the complexity of these codes and the time it would take if you were to handle these yourself. You can learn more about how to deal with common response codes here.