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 | Outcome / Recommended Action |
|---|---|---|
| 01 | Refer to card issuer | Soft Decline – Cardholder should contact their bank |
| 03 | Invalid merchant | Hard Decline – Merchant not recognized for this transaction |
| 04 | Capture card | Hard Decline – Card flagged for security reasons |
| 05 | Do not honor | Soft Decline – Authorization not approved |
| 06 | Error | Soft Decline – Temporary processing issue, retry may succeed |
| 07 | Pick up card, special condition | Hard Decline – Card blocked for security reasons |
| 08 | Honor with identification | Soft Decline – Additional verification required |
| 12 | Invalid transaction | Hard Decline – Transaction type not supported |
| 14 | Invalid card number | Hard Decline – Card number not recognized |
| 15 | Invalid issuer | Hard Decline – Issuer not recognized |
| 19 | Re-enter transaction | Soft Decline – Retry recommended |
| 30 | Format error | Hard Decline – Message validation failed |
| 33 | Expired card | Hard Decline – Card expired |
| 36 | Restricted card | Hard Decline – Card usage restricted |
| 41 | Lost card | Hard Decline – Card reported lost |
| 43 | Stolen card | Hard Decline – Card reported stolen |
| 46 | Closed account | Hard Decline – Account closed |
| 51 | Insufficient funds / over credit limit | Soft Decline – Insufficient available balance |
| 54 | Expired card | Soft Decline – Expiration date invalid; advise update |
| 55 | Invalid PIN | Hard Decline – PIN verification failed |
| 57 | Transaction not permitted to cardholder | Hard Decline – Transaction not allowed for this card |
| 58 | Transaction not permitted by terminal | Hard Decline – Transaction not permitted in this context |
| 59 | Suspected fraud | Hard Decline – Transaction blocked due to risk assessment |
| 61 | Exceeds withdrawal amount limit | Soft Decline – Amount exceeds permitted limit |
| 62 | Restricted card | Hard Decline – Card restricted |
| 63 | Security violation | Hard Decline – Security requirements not met |
| 65 | Exceeds withdrawal count limit | Soft Decline – Usage frequency limit exceeded |
| 70 | Contact card issuer | Soft Decline – Cardholder action required |
| 72 | PIN not changed | Hard Decline – PIN update required |
| 75 | Allowable PIN tries exceeded | Hard Decline – PIN retry limit exceeded |
| 78 | No account | Hard Decline – Account not found |
| 79 | Already reversed | Soft Decline – Transaction previously reversed |
| 80 | System not available | Soft Decline – Retry may succeed when service restored |
| 81 | Domestic debit transaction not allowed | Hard Decline – Transaction not permitted domestically |
| 82 | CVV validation failure | Hard Decline – Security code mismatch |
| 83 | Cannot verify PIN | Soft Decline – Retry possible once verification available |
| 91 | Authorization service unavailable | Soft Decline – Retry recommended |
| 92 | Unable to route transaction | Soft Decline – Retry recommended |
| 93 | Transaction cannot be completed | Hard Decline – Transaction not permitted |
| 96 | Authorization processing unavailable | Soft Decline – Retry recommended |
| 99 | Unknown response | Soft Decline – Retry or contact bank |
| 5C | Card verification failed | Hard Decline – Verification unsuccessful |
| C0 | Transaction not permitted | Hard Decline – Not permitted under card rules |
| N7 | CVV2 mismatch | Hard Decline – Security code invalid |
| R1 | Stop payment order | Hard Decline – Payment stopped per account instructions |