Each Israeli gateway has its own response field and code dictionary. How to read a decline, why copied code tables are dangerous, and what is worth retrying.
Key takeaways
- The code alone is not enough. Always store the description string that came back with it.
- Code dictionaries are not shared between providers. The same number at two gateways is not the same meaning.
- Never copy a code table from a blog. The provider is the source, and the table changes with processing routes and transaction types.
- The split that drives behaviour is retryable versus not retryable, not how the message is worded.
- A customer should never see a code. They should see what to do next.
A declined payment comes from one of three places - your own validation, the gateway, or the card issuer - and each calls for a different action. Cardcom's v11 interfaces return a ResponseCode where 0 means success, alongside a Description. Tranzila's response field is three characters, where 000 means approved.
Three sources for the same word "declined"
Before interpreting any code, you need to know who wrote it:
- Your own code. A missing field, an invalid amount, an unsupported currency, a card number that failed a Luhn check before anything left your server. That is not a gateway decline at all.
- The gateway. An unconfigured terminal, wrong credentials, a duplicate transaction, a failed 3-D Secure authentication. The problem is yours or your configuration's, and the customer cannot fix it.
- The card issuer. Insufficient funds, a blocked card, an expired card, a refusal that requires the cardholder to call their bank. This is the only layer where the customer can act.
The usual mistake is routing all three to one error screen. The result is a customer being asked to try a different card because a terminal was set up wrong.
Where the code actually lives at each provider
| Cardcom | Tranzila | |
|---|---|---|
| Primary response field | ResponseCode | A three-character response field |
| Success value | 0 | 000 |
| Accompanying text | Description | A message string alongside the code |
| Source of the dictionary | Cardcom documentation | Tranzila documentation |
| What not to do | Rely on fields from the older interfaces | Assume a number matches another provider |
That last row is the point. Two integrations written by the same developer for the same shop will return different numbers for the same real-world condition. Collapsing them into one dictionary copied off the internet produces wrong decisions silently.
Which declines are actually worth retrying?
That is the only question your code cares about. Classify every response into one of four categories and give each category exactly one behaviour:
| Category | Example condition | Action | Retry |
|---|---|---|---|
| Success | Approved | Continue the flow | Not applicable |
| Transient failure | Network fault, timeout | One delayed retry | Yes |
| Issuer decline | Refusal, funds, expiry | Ask for another payment method | Not on the same card |
| Configuration failure | Terminal, credentials, parameter | Alert the team, not the customer | No |
The simple rule: if the decline describes a condition at the customer's end, retrying the same card a second later changes nothing. If it describes an infrastructure fault, one retry with a delay is reasonable. Retrying an issuer refusal in a loop looks like suspicious behaviour.
What should the customer see?
Not the code. They need one sentence telling them what happens now, not a number they cannot act on.
- Infrastructure failure: "We could not complete this right now, please try again in a moment."
- Issuer decline: "The payment was not approved. Try another card or contact your card issuer."
- Configuration failure: a generic message to the customer and an immediate alert to the team with the full detail.
- In every case: a short transaction reference the customer can read out to support.
What is never acceptable: asking a customer to send a screenshot of their card, to read out the security code, or to dictate a full card number over the phone. Even when it resolves the incident, it creates a larger problem.
Why a recurring charge declines differently from a checkout
When a charge runs with the customer in front of the screen, the decline reaches them and they can react immediately. On a recurring charge against a stored token at three in the morning, nobody is there. That turns the same category of code into a completely different process problem.
- An expired card is the most common recurring failure, and it is knowable in advance. You can warn before the charge date instead of failing on it.
- An issuer decline on a recurring charge needs a communication channel to the customer, not just a log line. Without outreach, the subscription simply stops paying.
- Retries on a recurring charge belong on a schedule measured in days, not seconds. The common cause - available funds - changes with time rather than with another attempt.
- Count consecutive failed cycles per customer. After a threshold you set in advance, the subscription goes to a human rather than to another attempt.
- In flows that include an authentication step before the charge, a failure at that step is not a gateway decline. Classify it separately, or your decline report is measuring two different things at once.
Building the decision layer once
- Define a mapping table in the database: provider, code, category, retryable, what the customer is shown.
- Populate it from each provider's own documentation separately. There is no shared default.
- Add an "unknown" category that alerts the team instead of guessing. A new code will appear one day.
- Store per attempt: the provider's transaction identifier, time, amount, currency, operation type, and the full code plus description.
- Never store a full card number, security code or authentication data. Keep the last four digits and the card type.
- Produce a weekly report of codes by frequency. One or two usually explain most failures, and those are the ones worth fixing.
That logging is also what lets you answer the question that always gets asked: did the decline rate go up, or did volume simply grow?
This is a technical description of how to handle gateway responses, not financial advice. Binding code meanings come from the provider's documentation and your acquiring agreement.
Related: integrating with the Cardcom API, integrating with the Tranzila API, Israeli payment gateways compared.
Sources
Frequently asked questions
Can I use one code table for both providers?
No. Each provider has its own response field and its own dictionary, and the same number at both does not necessarily describe the same condition. Your table needs a composite key of provider plus code, not the code alone, or the decision breaks the moment you add a provider.
Which value indicates success at each of them?
With Cardcom's v11 interfaces you check that `ResponseCode` equals 0, and read `Description` whenever it is non-zero. With Tranzila the response field is three characters, and 000 indicates an approved transaction. Any other value has to be classified against that provider's own dictionary.
How many times may a declined transaction be retried?
That depends on the category, not on a number. An infrastructure failure justifies a single delayed retry. An issuer decline justifies no retry on the same card at all, because nothing about the cause has changed. Looping retries can look like anomalous behaviour and put the merchant account at risk.
What must never go into the log?
A full card number, the security code on the back of the card, and any cardholder authentication data. Store the last four digits, the card type, the provider's transaction identifier, the code and the description. That is entirely sufficient to diagnose a decline and open a support ticket.
Keep reading
Related service
Business Automation
I build custom automations that remove repetitive work end to end.
About the author
Yehonatan Saadia
Freelance automation, web & MVP developer
I'm Yehonatan Saadia, a senior developer who builds business automation, custom websites, and MVPs for small and mid-sized companies across the US, Europe, and Israel. These guides come from real client work, not theory.
Work with meHave a project like this?
Tell me what you're trying to automate or build. I reply within 24 business hours with a few targeted questions, then we walk through it on a free 30-minute call, with no commitment. You come away with a scope, a timeline and a fixed price - or a straight answer that it isn't worth building.