Guides
Response Codes
Every Purchase, Refund and Auth/Capture response from Fat Zebra includes a response_code: a standard two-digit code, 00 to 99, from the card network describing exactly what happened to the transaction. 00 is Approved, 51 is Insufficient Funds, 05 is Do Not Honour, and so on.
Shown to a customer as-is, these codes mean nothing. "Refer to Card Issuer" doesn't tell anyone what to do next. Some codes are worse than unhelpful: they describe why a card was declined in ways that are actively risky to repeat back. Telling a customer their card was declined because it's reported lost or stolen hands that information to anyone running a stolen card through your checkout to see if it still works.
The fix is two separate mappings, built once and reused everywhere response_code reaches your UI or your support tooling:
- a customer-facing map: response code to one of a small number of safe, generic messages
- an internal map: response code to the real bank meaning, for support and reconciliation
Important
Never pass Fat Zebra's raw response_code, or the message string returned alongside it, straight through to a customer. Map it first.
Where you'll see it
response_code sits in the response object of every Purchase, Refund and Auth/Capture response, next to successful (a boolean) and message. The same code list applies across all of those, so one mapping covers your whole integration.
Fat Zebra also returns a separate merchant_advice_code on declines: a plain-English category (retry_later, do_not_retry, update_required, not_supported, cancelled, none) describing how to handle the decline. If you're building retry logic rather than customer messaging, use merchant_advice_code directly rather than re-deriving the same thing from response_code.
Step 1: Build the customer-facing message map
Don't map codes one-to-one. Group them into a handful of message buckets, and map every code into one of those buckets:
| Category | Response codes | Customer-facing message |
|---|---|---|
| Approved | 00, 08, 10, 11, 16 | Payment approved. |
| Lost, stolen or restricted card | 04, 07, 34, 35, 36, 37, 41, 43 | Your card issuer declined this payment. Please use a different card or contact your bank. |
| Temporary error, safe to retry | 19, 22, 90, 91, 92, 96 | We couldn't process that just now. Please try again in a moment. |
| Card number or security code | 14, 82 | Please check your card number and security code and try again. |
| Expired card | 33, 54 | This card has expired. Please use a different card. |
| Insufficient funds | 51 | This card was declined. Please use a different card or payment method. |
| Everything else | all other codes | Your bank declined this payment. Please use a different card or contact your bank. |
Keep that message set small. A dozen or so unique messages is plenty; anything more granular starts leaking back the detail you're trying to hide, without giving the customer anything new to act on.
Lost, stolen and restricted card codes aren't a style choice here, they're Fat Zebra's own guidance. Codes 04, 07, 34 to 37, 41 and 43 must never be shown to the customer as the real reason. Always show the generic decline instead.
Step 2: Route specific codes back to the right field
Two codes are worth handling as UI behaviour rather than a message string, because the fix is something the customer can act on immediately in the field they're already looking at:
14Invalid Card Number and 82CVV Validation Error: send focus back to the card number or security code field instead of showing a generic decline banner. The customer likely mistyped something.19, 22, 90, 91, 92, 96: these are temporary network or issuer errors, not real declines. Offer an immediate retry rather than treating them as a hard decline or asking the customer to try a different card.
Step 3: Keep a separate internal mapping for support and reconciliation
The message field Fat Zebra returns alongside most codes is generic (Declined, Approved) and isn't diagnostic on its own. Support and reconciliation need the real bank meaning behind the code, sitting right next to the transaction, so they can answer "why was this customer's card declined" without cross-referencing anything.
The full list:
| Code | Bank meaning | Successful | Recommended action |
|---|---|---|---|
00 | Approved | Yes | No action needed, the payment succeeded. |
01 | Transaction Declined | No | Ask the customer to contact their card issuer for more information. |
02 | Transaction Declined | No | Ask the customer to contact their card issuer for more information. |
03 | Merchant configuration error | No | This is a merchant setup issue, not a card problem. Contact ArtsPay support to check your merchant configuration. |
04 | Card marked as Lost or Stolen | No | Do not tell the customer their card was reported lost or stolen. Show the generic decline message and let them try a different card. |
05 | Do Not Honor | No | Ask the customer to contact their card issuer for more information. |
06 | Error, Original Not Found or similar | No | This is usually a gateway-side error rather than a card problem. Retry the request, and contact ArtsPay support if it persists. |
07 | Card marked as lost or stolen (Pick Up Card) | No | Do not tell the customer their card was reported lost or stolen. Show the generic decline message and let them try a different card. |
08 | Honour with Identification | Yes | No action needed, the payment succeeded, though the issuer may request further identification at a physical terminal. |
09 | Request in Progress (local terminal error) | No | This is a temporary local processing delay. Retry the payment. |
10 | Approved for Partial Amount | Yes | The payment succeeded for a partial amount only. Check whether that partial amount is acceptable for the order before fulfilling it. |
11 | Approved, VIP | Yes | No action needed, the payment succeeded. |
12 | Invalid Transaction Type | No | Ask the customer to confirm with their card issuer that the card supports this type of transaction. |
13 | Invalid Amount | No | If the amount looks correct on your end, ask the customer to confirm with their card issuer that they can make purchases of that amount. |
14 | Invalid Card Number | No | Send the customer back to the card number field rather than asking them to contact their card issuer. This is usually a simple typo. |
15 | No valid issuer for this card | No | The card's issuer isn't recognised by the network. Ask the customer to try a different card. |
16 | Approved, Update Track 3 | Yes | No action needed, the payment succeeded. |
17 | Declined, not used | No | Rarely returned by the network. Treat it as a generic decline and ask the customer to try a different card. |
18 | Declined, not used | No | Rarely returned by the network. Treat it as a generic decline and ask the customer to try a different card. |
19 | Re-enter last transaction | No | Retry the payment automatically. If it still fails, ask the customer to contact their card issuer. |
20 | Declined, not used | No | Rarely returned by the network. Treat it as a generic decline and ask the customer to try a different card. |
21 | Declined, not used | No | Rarely returned by the network. Treat it as a generic decline and ask the customer to try a different card. |
22 | Suspected Malfunction | No | This is usually a temporary fault at the issuer's end, so retry the payment; if it still fails, try again later. |
23 | Unacceptable Transaction Fee | No | This relates to fee configuration rather than the card. Contact ArtsPay support if you see this repeatedly. |
24 | Declined, not used | No | Rarely returned by the network. Treat it as a generic decline and ask the customer to try a different card. |
25 | Unable to Locate Record on File | No | The issuer couldn't find a record to match this transaction. Ask the customer to try a different card. |
26 | Declined, not used | No | Rarely returned by the network. Treat it as a generic decline and ask the customer to try a different card. |
27 | Declined, not used | No | Rarely returned by the network. Treat it as a generic decline and ask the customer to try a different card. |
28 | Declined, not used | No | Rarely returned by the network. Treat it as a generic decline and ask the customer to try a different card. |
29 | Declined, not used | No | Rarely returned by the network. Treat it as a generic decline and ask the customer to try a different card. |
30 | Format Error | No | This indicates a formatting problem with the request rather than the card. Contact ArtsPay support if you see this repeatedly. |
31 | Bank Not Supported by Switch/Route | No | The customer's bank isn't supported on this route. Ask them to try a different card. |
32 | Declined, not used | No | Rarely returned by the network. Treat it as a generic decline and ask the customer to try a different card. |
33 | Expired Card | No | Ask the customer to use a different card; this one has expired. |
34 | Suspected Fraud - Retain Card | No | Do not disclose the fraud suspicion to the customer. Show the generic decline message and let them try a different card. |
35 | Contact Acquirer, Retain Card | No | Do not disclose the specific reason to the customer. Show the generic decline message and let them try a different card. |
36 | Restricted Card, Retain Card | No | Do not disclose the specific reason to the customer. Show the generic decline message and let them try a different card. |
37 | Contact Acquirer Security Department, Retain Card | No | Do not disclose the specific reason to the customer. Show the generic decline message and let them try a different card. |
38 | PIN Retries Exceeded | No | Ask the customer to use a different card or payment method; PIN retries have been exceeded on this one. |
39 | No Credit Account | No | Ask the customer to contact their card issuer; this card doesn't have a credit facility available for the transaction. |
40 | Function Not Supported | No | The card issuer doesn't support this function. Ask the customer to try a different card or payment method. |
41 | Lost Card | No | Do not tell the customer their card was reported lost. Show the generic decline message and let them try a different card. |
42 | No Universal (credit-capable) account | No | Ask the customer to contact their card issuer; this card doesn't have a credit-capable account attached. |
43 | Stolen Card | No | Do not tell the customer their card was reported stolen. Show the generic decline message and let them try a different card. |
44 | No Investment Account | No | Ask the customer to contact their card issuer; this card doesn't have the account type required for the transaction. |
45 | Declined, not used | No | Rarely returned by the network. Treat it as a generic decline and ask the customer to try a different card. |
46 | Declined, not used | No | Rarely returned by the network. Treat it as a generic decline and ask the customer to try a different card. |
47 | Declined, not used | No | Rarely returned by the network. Treat it as a generic decline and ask the customer to try a different card. |
48 | Declined, not used | No | Rarely returned by the network. Treat it as a generic decline and ask the customer to try a different card. |
49 | Declined, not used | No | Rarely returned by the network. Treat it as a generic decline and ask the customer to try a different card. |
50 | Declined, not used | No | Rarely returned by the network. Treat it as a generic decline and ask the customer to try a different card. |
51 | Insufficient Funds | No | Ask the customer to use a different card or payment method; this one doesn't have sufficient funds. |
52 | No Cheque Account | No | Ask the customer to contact their card issuer; there's no cheque account attached to this card. |
53 | No Savings Account | No | Ask the customer to contact their card issuer; there's no savings account attached to this card. |
54 | Expired Card | No | Ask the customer to use a different card; this one has expired. |
55 | Incorrect PIN | No | Ask the customer to try again with the correct PIN. |
56 | No Card Record, check with issuer | No | Ask the customer to contact their card issuer to check the card is set up correctly. |
57 | Function Not Permitted to Card Holder | No | Ask the customer to confirm with their card issuer that the card supports this type of transaction. |
58 | Function Not Permitted to Terminal | No | The terminal or channel isn't permitted for this function. Contact ArtsPay support if you see this repeatedly. |
59 | Suspected Fraud | No | Do not disclose the fraud suspicion to the customer. Show the generic decline message and let them try a different card. |
60 | Merchant to Contact Acquirer | No | This requires the merchant to contact the acquirer directly. Contact ArtsPay support. |
61 | Exceeds Withdrawal Limit | No | The customer has exceeded their withdrawal limit. Ask them to try a different card or a smaller amount. |
62 | Restricted Card | No | The card is restricted for this type of transaction. Ask the customer to try a different card. |
63 | Declined, not used | No | Rarely returned by the network. Treat it as a generic decline and ask the customer to try a different card. |
64 | Declined, not used | No | Rarely returned by the network. Treat it as a generic decline and ask the customer to try a different card. |
65 | Exceeds Withdrawal Frequency | No | The customer has exceeded their withdrawal frequency limit. Ask them to try a different card or try again later. |
66 | Declined, not used | No | Rarely returned by the network. Treat it as a generic decline and ask the customer to try a different card. |
67 | Declined, not used | No | Rarely returned by the network. Treat it as a generic decline and ask the customer to try a different card. |
68 | Declined, not used | No | Rarely returned by the network. Treat it as a generic decline and ask the customer to try a different card. |
69 | Declined, not used | No | Rarely returned by the network. Treat it as a generic decline and ask the customer to try a different card. |
70 | Declined, not used | No | Rarely returned by the network. Treat it as a generic decline and ask the customer to try a different card. |
71 | Declined, not used | No | Rarely returned by the network. Treat it as a generic decline and ask the customer to try a different card. |
72 | Declined, not used | No | Rarely returned by the network. Treat it as a generic decline and ask the customer to try a different card. |
73 | Declined, not used | No | Rarely returned by the network. Treat it as a generic decline and ask the customer to try a different card. |
74 | Declined, not used | No | Rarely returned by the network. Treat it as a generic decline and ask the customer to try a different card. |
75 | PIN Tries Exceeded | No | Ask the customer to use a different card or payment method; PIN tries have been exceeded on this one. |
76 | Declined, not used | No | Rarely returned by the network. Treat it as a generic decline and ask the customer to try a different card. |
77 | Declined, not used | No | Rarely returned by the network. Treat it as a generic decline and ask the customer to try a different card. |
78 | Declined, not used | No | Rarely returned by the network. Treat it as a generic decline and ask the customer to try a different card. |
79 | Declined, not used | No | Rarely returned by the network. Treat it as a generic decline and ask the customer to try a different card. |
80 | Declined, not used | No | Rarely returned by the network. Treat it as a generic decline and ask the customer to try a different card. |
81 | Declined, not used | No | Rarely returned by the network. Treat it as a generic decline and ask the customer to try a different card. |
82 | CVV Validation Error | No | Send the customer back to the security code field rather than asking them to contact their card issuer. This is usually a simple typo. |
83 | Declined, not used | No | Rarely returned by the network. Treat it as a generic decline and ask the customer to try a different card. |
84 | Declined, not used | No | Rarely returned by the network. Treat it as a generic decline and ask the customer to try a different card. |
85 | Declined, not used | No | Rarely returned by the network. Treat it as a generic decline and ask the customer to try a different card. |
86 | Declined, not used | No | Rarely returned by the network. Treat it as a generic decline and ask the customer to try a different card. |
87 | Declined, not used | No | Rarely returned by the network. Treat it as a generic decline and ask the customer to try a different card. |
88 | Declined, not used | No | Rarely returned by the network. Treat it as a generic decline and ask the customer to try a different card. |
89 | Declined, not used | No | Rarely returned by the network. Treat it as a generic decline and ask the customer to try a different card. |
90 | Cutoff In Progress, retry allowed | No | The issuer is temporarily unavailable, but retries are explicitly allowed, so retry the payment automatically. |
91 | Host or Switch Unavailable, Signed Off or Timed Out | No | This is usually temporary. Retry the payment automatically; if it still fails, ask the customer to contact their card issuer. |
92 | Unable to Route Transaction | No | This is usually temporary. Retry the payment automatically; if it still fails, try again later. |
93 | Cannot Complete, Violation of the Law | No | Do not disclose the specific reason to the customer. Show the generic decline message. |
94 | Duplicate Transaction | No | This looks like a duplicate submission, so check whether a matching payment already exists before retrying. |
95 | Declined, not used | No | Rarely returned by the network. Treat it as a generic decline and ask the customer to try a different card. |
96 | System Error | No | This is a temporary system error, so retry the payment; if it still fails, try again later. |
99 | System Error | No | This is a temporary system error, so retry the payment; if it still fails, try again later. |
This table is complete but long by nature, a hundred codes across the financial network. If you need to work through it by category rather than scrolling the whole list, filter for Do not disclose first: that's the set of codes covered by the security guidance in Step 1.
Testing
Fat Zebra's sandbox test cards return predetermined response codes, so you can trigger any outcome without needing real card behaviour. Some cards are fixed to a single response, for example VISA 4557 0123 4567 8902 always returns 05 Declined. Others are dynamic: with a card like 4242 4242 4242 4242, the last two digits of the purchase amount become the response code, so a purchase of $50.09 returns 09 Acquirer Busy. Use this to exercise every branch of your customer-facing map, including the retry and card-entry paths, before going live.
FAQ
Should I check successful or the HTTP status code to detect a decline?
Check successful. HTTP status covers request-level problems, like a malformed request or a permissions error, while response_code and successful describe the outcome of the transaction itself. A declined payment is still a 200.
Do response codes differ between Purchase, Refund and Auth/Capture?
No. The financial network response codes and their meaning stay the same across Purchase, Refund and Auth/Capture responses, so one mapping table covers all three.
Where should the internal mapping actually live?
Wherever your support team already looks at a transaction, alongside the merchant dashboard's transaction detail view or your reconciliation exports. It only needs to be visible to staff, never to the customer-facing app.
What's the difference between response_code and merchant_advice_code?
response_code is the raw two-digit network code covered in this guide. merchant_advice_code is Fat Zebra's own category for how to handle a decline (retry_later, do_not_retry, update_required, and so on), returned alongside it. Use merchant_advice_code directly for retry logic rather than reconstructing it from response_code.
Can I show the bank meaning to a merchant, just not the customer?
Yes. The restriction in Step 1 is specifically about the customer-facing checkout experience. A merchant looking at their own dashboard, or your support team looking at a case, can see the real reason.