Response Code Breakdown
The acquirer.responseCode field provides the raw code detailing why a transaction failed. It is crucial to understand that the meaning of the code depends entirely on its source. The source is the system layer that issued the decline.
The response code can originate from three main sources:
- Card Networks / Issuing Banks (ISO 8583 Codes): The industry standard for transaction messaging.
- NAPS (QPAY Codes): Specific codes related to the NAPS payment method.
- Fraud Management Tool: Codes generated by our risk engine before the bank is contacted.
1. Internal Fraud Management Tool Codes
These codes are generated by our internal risk engine when a transaction is blocked before it is sent to the card network.
| Response Code | Internal Reason (Merchant Admin View) | Trigger Scenario |
|---|---|---|
| 4001 | RISK_GEO_MISMATCH | Card Country Block. The BIN Country does not match the IP Country, or the card is from a restricted country. |
| 4002 | RISK_VELOCITY_IP | Velocity Block. Too many requests from this IP address. |
| 4003 | RISK_VELOCITY_PAN | Velocity Block. Too many attempts with this specific Card Number (PAN) across different IPs. |
| 4004 | RISK_HIGH_SCORE | Generic Fraud Block. The transaction scored above the acceptable threshold. |
| 4005 | RISK_BLOCKLIST | The User ID, Email, or Card Fingerprint is on your internal "Deny List." |
| 4006 | RISK_AMT_LIMIT | Transaction amount exceeds the allowed maximum for this merchant category or card type. |
| 4007 | RISK_VELOCITY_USER | Velocity Block. Too many attempts for this specific user. |
2. Local Acquirer / Network Codes (QPAY)
These codes are generated by the local payment network (QPAY) and typically relate to local risk rules, timeouts, or customer actions during the payment initiation process.
| Response Code | Description | Actionable Insight |
|---|---|---|
| 2799 | Fraud validation error | Transaction failed due to validation error on fraud parameters sent from the merchant side. |
| 2992 | Payment Status-Time out. | Transaction did not complete due to network timeouts. Retry using a different transaction ID is required. |
| 2994 | Payment method selected | Customer did not complete the payment after selecting a method. |
| 2996 | Canceled before payment method selection | Customer cancellation before payment method was selected. |
| 2997 | Canceled before login | Customer cancellation after selecting a payment method but before authentication/login. |
| 3000 | Payment Failed. | General payment failure, often preceding an issuer rejection (like insufficient funds). |
| 4003 | Payment Failed, please refer to PG administrator. | Transaction failed due to a blacklist operation. Cannot be submitted again. |
| 4004 | Payment Failed, please refer to PG administrator. | Transaction failed due to a blacklist operation. Cannot be submitted again. |
| 4100 | Payment has been rejected | Transaction failed due to Payment Gateway Risk Rule violation. |
3. Card Networks and Issuing Banks (ISO 8583 Codes)
If a transaction successfully passes through our system and the local network, it reaches the customer's Issuing Bank. The bank returns a standardized ISO 8583 response code. These codes are the most common source of declines and relate directly to the card or account status.
| Code | Description | Category / Recommended Retry |
|---|---|---|
| 01 | Refer to card issuer | Soft Decline - Advise the user to contact their bank. |
| 03 | Invalid merchant | Hard Decline - Error with Merchant ID configuration. |
| 04 | Capture card | Hard Decline - Card is suspected fraudulent. Do not retry. |
| 05 | Do not honor | Hard Decline - Bank decline for unspecified reason. Do not retry. |
| 08 | Honor with ID | Soft Decline - Bank wants verification. |
| 10 | Partial Approval | Conditional Success - Only part of the amount was authorized. |
| 12 | Invalid transaction | Data Error - Check data format. |
| 13 | Invalid amount | Data Error - Check amount formatting. |
| 14 | Invalid card number | Data Error - Card details invalid. |
| 15 | Invalid issuer | Data Error - Issuer configuration issue. |
| 30 | Format error | Data Error - Message not formatted correctly. |
| 33 | Expired card | Hard Decline - Card has passed its expiration date. Do not retry. |
| 41 | Lost card | Hard Decline - Card reported lost. Do not retry. |
| 43 | Stolen card | Hard Decline - Card reported stolen. Do not retry. |
| 51 | Insufficient funds/over credit limit | Soft Decline - Safe to ask user to try again later. |
| 54 | Expired card | Data Error - Advise the user to update details. |
| 55 | Invalid PIN | Data Error - Incorrect PIN (for debit/PIN transactions). |
| 57 | Transaction not permitted to issuer/cardholder | Hard Decline - Card cannot be used for this purpose. |
| 58 | Transaction not permitted by acquirer/terminal | Hard Decline - Merchant configuration issue. |
| 61 | Exceeds withdrawal amount limit | Soft Decline - Limit reached. Ask the user to retry a smaller amount. |
| 62 | Restricted card | Hard Decline - General restriction on the card. |
| 63 | Security violation | Hard Decline - Suspected security breach. |
| 65 | Exceeds withdrawal count limit | Soft Decline - Limit reached. Ask the user to retry later. |
| 70 | Contact Card Issuer | Soft Decline - Advise the user to contact their bank. |
| 75 | Allowable number of PIN tries exceeded | Hard Decline - Too many failed PIN attempts. |
| 80 | System not available | System Error - Issuing system temporary down. Safe to retry. |
| 91 | Authorization System or issuer system inoperative | System Error - Issuing system temporary down. Safe to retry. |
| 92 | Unable to route transaction | System Error - Network failure. Safe to retry. |
| 94 | Duplication transaction detected | System Error - Duplicate transaction attempt. |
| 96 | System error | System Error - General system failure at the bank. Safe to retry. |