Response Codes
Response codes provide a consistent, host-independent view of transaction outcomes by standardising codes returned by upstream hosts. Use the codes, human-readable messages, and practical guidance to interpret outcomes and determine how your application should respond.
Column meanings:
- tnsResponseCode - the tnsResponseCode value returned to clients.
- tnsResponseText - the human-readable text returned alongside the code
- Description - what the code means in practice and the expected client behaviour.
Codes are grouped by prefix and sorted within each group:
- Approval
- Declines
- Host-categorised declines (mapped from the acquirer/issuer decline codes)
- Fuel / Fleet-specific Declines
HTTP Response Codes:
It's important to note that HTTP status code and Response Codes answer two different questions:
- The HTTP status describes whether the API call itself was accepted and processed
- The TNS Response Codes describes the outcome of the payment itself, and is carried inside the response body.
A declined card is a perfectly successful API call. It returns HTTP 200 with a decline code in the body. The HTTP layer is not used to signal decline.
Approval
tnsResponseCode | tnsResponseText | Description |
|---|---|---|
00 | Approved | Transaction was fully approved by the issuer. |
H08 | Approved - honor with identification | Approved on condition the cardholder's identity is verified. Complete the sale after checking ID. |
H10 | Partial approval | The issuer approved only part of the requested amount. Collect the remainder via another tender or reverse. |
General Response Codes
The below response codes are generated where the transaction is declined prior to going to the upstream host.
tnsResponseCode | tnsResponseText | Description |
|---|---|---|
G03 | Invalid merchant configuration | The merchant/terminal is not configured correctly at the gateway (e.g. missing acquirer setup). Not retryable by the cardholder; requires operational/config fix. |
G04 | Card blacklisted | The card is on the gateway blacklist and was blocked before reaching the host. Do not retry with the same card. |
G12 | Invalid transaction data | The request reached the gateway but contained data that is invalid for the transaction type. Fix the request before retrying. |
G13 | Currency mismatch | The transaction currency does not match what the merchant/terminal is permitted to process. Correct the currency and retry. |
G25 | Reversal not required | A reversal was requested but is unnecessary because the original was not found or was not approved. Treat as handled; no further action needed. |
G26 | Original transaction not found | The referenced original transaction (for capture/refund/reversal) could not be located. Check the reference before retrying. |
G30 | Invalid request format | The request was malformed and could not be parsed/validated by the gateway. Fix the request structure and retry. |
G31 | Invalid host response | The host replied but the response could not be interpreted by the gateway. Outcome uncertain; treat as a host-side failure. |
G40 | Transaction not supported | The requested transaction type/function is not supported for this configuration. Do not retry as-is. |
G57 | Authorization failed | Gateway-level authorization checks failed for the request. Not approved; review request/permission. |
G58 | Operation not allowed | The operation is not permitted for this terminal/merchant. Not retryable without a config change. |
G68 | Host read timeout | Payorch connected but did not receive the host response in time. Outcome unknown; a reversal may be triggered. Do not assume approval. |
G91 | Host connection timeout | The gateway could not establish a connection to the host. Transaction did not complete; safe to retry later. |
G94 | Duplicate advice already processed | This advice message duplicates one already processed. No further action; the original outcome stands |
G95 | Duplicate transaction | A transaction with the same key was already submitted. Do not resubmit; look up the original result. |
G96 | Host response error | The host returned an error condition the gateway classified as a system/host error. Outcome uncertain; treat as failed. |
G97 | Gateway processing error | An internal error occurred in the gateway while processing. Transaction not completed; retry may be possible after investigation. |
G99 | Smart routing block | Smart routing rules blocked the transaction before it was sent to a host. Not approved; governed by routing configuration. |
Host Response Codes (Hxx)
The below standardized response codes are mapped from an upsteam host into the below format.
tnsResponseCode | tnsResponseText | Description |
|---|---|---|
00 | Approved | Transaction was fully approved by the issuer. |
H01 | Refer to card issuer - call issuer | The issuer declined and asked the merchant to contact them for authorization. Do not simply retry; follow the call-issuer process. |
H04 | Capture card - pick up | The issuer declined and instructed the terminal to retain the card. Do not return the card; do not retry. |
H05 | Host declined | Generic issuer decline (do not honour) with no more specific reason. Not approved; a different card may be needed. |
H08 | Approved - honor with identification | Approved on condition the cardholder's identity is verified. Complete the sale after checking ID. |
H10 | Partial approval | The issuer approved only part of the requested amount. Collect the remainder via another tender or reverse. |
H30 | Host invalid request | The host rejected the request as malformed/invalid. Not approved; correct the request. |
H41 | Lost card - pick up | Card reported lost; issuer instructed pickup. Retain the card; do not retry. |
H43 | Stolen card - pick up | Card reported stolen; issuer instructed pickup. Retain the card; do not retry. |
H51 | Insufficient funds | Declined because the account lacks available funds. Suggest another card/tender; retry may succeed later. |
H54 | Expired card | Declined because the card has expired. Request a valid card. |
H55 | Incorrect PIN | The PIN entered was wrong. Prompt the cardholder to re-enter the PIN and retry. |
H56 | PIN change required | The issuer requires the cardholder to change their PIN before transacting. |
H57 | Transaction not permitted to cardholder | The issuer does not permit this transaction type for this cardholder. Not approved; try a different transaction/card. |
H59 | Suspected fraud | The issuer flagged suspected fraud; the gateway auto-reverses. Do not retry with the same card. |
H61 | Exceeds withdrawal limit | Declined for exceeding the permitted amount/withdrawal limit. Retry with a lower amount or another card. |
H63 | Security violation | The issuer declined for a security-rule violation; the gateway auto-reverses. Not approved. |
H65 | Fallback required | Additional authentication is required. Depending on client capability, retry with chip, PIN, CVV, or 3DS. |
H66 | PIN required | A PIN is required to complete this transaction. Prompt for PIN and retry. |
H68 | Host suspect | The host response arrived too late, so the final state is uncertain. Do not assume approval; reconcile before retrying. |
H75 | PIN tries exceeded | The allowed number of PIN attempts was exceeded; may warrant card pickup. Do not keep retrying the PIN. |
H91 | Issuer unavailable | The issuer or switch was unreachable/inoperative. Transaction not completed; safe to retry later. |
H96 | Host error | The host reported a system malfunction. Outcome uncertain; treat as failed and retry later |
Fuel / fleet codes (Fxx)
Specific response codes for Fleet/Fuel Merchants.
Code | tnsResponseText | Description |
|---|---|---|
F01 | Invalid vehicle | Declined because the vehicle identifier supplied is not valid for the fleet card. |
F02 | Invalid driver | Declined because the driver identifier supplied is not valid for the fleet card. |
F03 | Invalid product | Declined because the fuel/merchandise product is not permitted on this card. |
F04 | Exceeds transaction total limit per product class | Declined because the transaction total exceeds the limit for that product class. |
F05 | Over daily limit | Declined because the card's daily spend/usage limit has been exceeded. |
F06 | Invalid date or time | Declined because the transaction date/time is outside the card's permitted window. |
F07 | Exceeds quantity | Declined because the requested quantity exceeds the card's permitted amount. |
F08 | Invalid prompt entry | Declined because a fuel-site prompt (e.g. odometer, ID) was answered with invalid data. |
F09 | Invalid track 2 data | Declined because the card's track 2 data is invalid or unreadable. |
F10 | Voyager ID problem | Declined due to a problem with the Voyager fleet card identification. |
F11 | Invalid odometer | Declined because the odometer reading entered is invalid. |
F12 | Invalid restriction code | Declined because a card restriction code prevents this purchase. |
F13 | Pay at pump not allowed | Declined because the card is not permitted to pay at the pump; go inside to pay. |
F14 | Over fuel limit | Declined because the fuel amount exceeds the card's fuel limit. |
F15 | Over cash limit | Declined because the cash portion exceeds the card's cash limit. |
F16 | Fuel price error | Declined due to a fuel price error/mismatch at the site. |
F17 | Over repair limit | Declined because the repair/service amount exceeds the card's limit. |
F18 | Over additive limit | Declined because the additive amount exceeds the card's limit. |
F19 | Invalid user | Declined because the user identifier supplied is not valid for the card. |
F20 | Driver's License or ID is Required | Declined because a driver's licence or ID must be supplied to proceed. |
F21 | Fuel only | Declined for non-fuel items; the card is restricted to fuel purchases only. |
F22 | Received prompts do not match expected values | Declined because the site prompt responses did not match the values the card expected. |
F23 | Extended prompting required | Declined because additional (extended) prompts must be completed before approval. |
On this page
- Response Codes