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. |
TNS Host Simulator - Sandbox & UAT
The TNS Host Simulator lets you build and test your integration with TNS Payment Orchestration without connecting to a real acquirer. It works with Hosted Checkout, Rest API's and Terminal API's. The simulator sends back correctly structured responses, so you can check how your application handles approvals, declines, errors and slow responses.
Note: The simulator is only available in sandbox & UAT environments. It can't be used in production.
Getting started
Within the sandbox environment, your merchant account will be setup with the simulator with a default mode where the response code returned is based on the transaction amount.
When creating a Developer Hub Project for test case generation, you can override the response codes.
Default mode: response set by the transaction amount
In Default mode, the cents part of the amount decides the result. For example, a transaction for 1.51 comes back as Insufficient Funds.
Each response includes two codes:
- hostResponseCode: the code returned by the simulated host (acquirer). It's for information only.
- tnsResponseCode: the standard TNS response code. It's the same across every acquirer TNS supports. Your application should make decisions based on this code.
.00 | 1.00 | 00 | 00 | Approved | Approved |
.08 | 1.08 | 08 | H08 | Approved | Approved with identification |
.51 | 1.51 | 51 | H51 | Declined | Insufficient funds |
.55 | 1.55 | 55 | H55 | Declined | Incorrect PIN |
.65 | 1.65 | 65 | H65 | Declined | Additional authentication required |
.91 | 1.91 | 91 | H91 | Declined | Issuer unavailable |
.96 | 1.96 | 96 | H96 | Declined | System error |
Any other value | 1.23 | Varies | H05 | Declined | Host decline |
Run most of your tests in Default mode. Because you choose the result through the amount, you can run your whole test set without changing any settings.
Always approve (or always return one specific response)
To get the same result every time, whatever the amount, you can set your account to auto-approve regardless of the cent value.
If you use the Dev Hub within the Sandbox Developer Portal, open your project and go to Response Simulation and pick a code from the Response Code Simulation list (for example, 00 – Approve or 051 – Decline Insufficient Funds).
Important: While this mode is set, the transaction amount is ignored. To go back to amount-based responses, go to Response Code Simulation and set back to Default.
Simulating a delayed response (timeouts)
To test how your application copes with a slow or timed-out host, set the response mode simulation to the timeout you want to set.
Things to test with this setting:
- Your application's client-side timeout and retry behaviour.
- Reversal handling, where your application doesn't get a response in time.
- Messages shown to the cardholder or operator while waiting.
To stop the delay, set the Timeout Delays back to Default.
Things to remember
- These settings apply to all transcations for the specific mercahnt id. Anyone else testing with the same merchant will see the same forced responses or delays.
- Always set things back to Default when you finish a specific test case.
- If you need help setting up the simulator, contact TNS Support.
On this page
- Response Codes