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

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:

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.

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:

• 14 Invalid Card Number and 82 CVV 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:

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