Overview This page provides comprehensive information about transaction response codes, AVS (Address Verification System) codes, and CVV (Card Verification Value) response codes returned by the payment gateway.
Understanding response codes is essential for proper error handling and transaction management.
All transaction responses are returned in query string format:
response=1&responsetext=SUCCESS&transactionid=123456789&amount=99.99
Response Code The response variable indicates the overall transaction result:
Code Status Description Action 1Approved Transaction successful Complete order 2Declined Transaction declined Request alternative payment 3Error Processing error occurred Review error details, retry if appropriate
Response Text The responsetext variable provides a human-readable description:
Approved (response=1)
Declined (response=2)
Error (response=3)
Common approval messages: Response Text Meaning SUCCESSStandard approval APPROVEDTransaction approved HONOR WITH IDApproved, ID required PARTIAL APPROVALPartially approved (amount_authorized < requested)
Common decline messages: Response Text Meaning Customer Action DECLINEGeneric decline Use different card INSUFFICIENT FUNDSNot enough balance Add funds or use different card CALL FOR AUTHORIZATIONManual authorization needed Call issuer PICK UP CARDCard reported lost/stolen Contact issuer DO NOT HONORIssuer declined Use different card INVALID CARD NUMBERCard number invalid Verify card number INVALID EXPIRATION DATEExpired card Update expiration date CARD TYPE NOT ACCEPTEDCard brand not supported Use different card DUPLICATE TRANSACTIONDuplicate detected Wait before retrying CARD EXPIREDCard past expiration Use current card
Common error messages: Response Text Meaning Resolution INVALID SECURITY KEYAuthentication failed Verify API key MISSING REQUIRED FIELDRequired parameter missing Add required fields INVALID AMOUNTAmount format incorrect Use x.xx format TRANSACTION NOT FOUNDTransaction ID invalid Verify transaction ID PROCESSOR ERRORGateway/processor issue Retry or contact support CONFIGURATION ERRORAccount setup issue Contact support
AVS Response Codes Address Verification System (AVS) compares billing address with issuer records:
Standard AVS Codes Code Description Recommendation XExact match - Address and 9-digit ZIP ✅ Accept YExact match - Address and 5-digit ZIP ✅ Accept AAddress match only ⚠️ Review W9-digit ZIP match only ⚠️ Review Z5-digit ZIP match only ⚠️ Review NNo match ⛔ Decline/Review UAddress unavailable ⚠️ Review RRetry - System unavailable 🔄 Retry EAVS error ⚠️ Review SService not supported - N/A GGlobal non-verifiable - N/A
International AVS Codes Code Description Recommendation BStreet match, postal code not verified ⚠️ Review CStreet and postal code not verified ⚠️ Review DStreet and postal code match (international) ✅ Accept IAddress information not verified ⚠️ Review MStreet and postal code match (international) ✅ Accept PPostal code match, street not verified ⚠️ Review
Configure AVS rules based on your risk tolerance. Overly strict rules may decline legitimate transactions.
CVV Response Codes Card Verification Value (CVV) response codes:
Code Description Recommendation MCVV match ✅ Accept NCVV does not match ⛔ Decline PNot processed ⚠️ Review SCVV should be on card but was not indicated ⚠️ Review UIssuer not certified or not provided ⚠️ Review XNo response from card association ⚠️ Review
Always request CVV for card-not-present transactions to reduce fraud and improve approval rates.
Handling Response Codes Decision Flow
Check Response Code
First, check the response variable if ( $result [ 'response' ] == '1' ) { // Approved } elseif ( $result [ 'response' ] == '2' ) { // Declined } else { // Error }
Verify AVS
For approved transactions, check AVS $acceptable_avs = [ 'X' , 'Y' , 'A' , 'Z' , 'W' ]; if ( in_array ( $result [ 'avsresponse' ], $acceptable_avs )) { // AVS acceptable }
Verify CVV
Check CVV response if ( $result [ 'cvvresponse' ] == 'M' ) { // CVV match } else { // CVV mismatch - flag for review }
Take Action
Process accordingly based on all checks
Implementation Example <? php function handleTransactionResponse ( $result ) { // Check primary response if ( $result [ 'response' ] != '1' ) { if ( $result [ 'response' ] == '2' ) { // Declined return [ 'success' => false , 'message' => 'Payment declined: ' . $result [ 'responsetext' ], 'retry' => in_array ( $result [ 'responsetext' ], [ 'CALL FOR AUTHORIZATION' ]) ]; } else { // Error return [ 'success' => false , 'message' => 'Payment error: ' . $result [ 'responsetext' ], 'retry' => true ]; } } // Transaction approved - check AVS $avs_acceptable = [ 'X' , 'Y' , 'A' , 'Z' , 'W' , 'D' , 'M' ]; $avs_match = in_array ( $result [ 'avsresponse' ], $avs_acceptable ); // Check CVV $cvv_match = ( $result [ 'cvvresponse' ] == 'M' ); // Fraud score check $needs_review = ! $avs_match || ! $cvv_match ; if ( $needs_review ) { // Flag for manual review flagForReview ( $result [ 'transactionid' ], [ 'avs' => $result [ 'avsresponse' ], 'cvv' => $result [ 'cvvresponse' ] ]); } return [ 'success' => true , 'transaction_id' => $result [ 'transactionid' ], 'needs_review' => $needs_review , 'message' => 'Payment successful' ]; } ?>
Partial Approvals Some transactions may be partially approved:
response=1 responsetext=PARTIAL APPROVAL amount_authorized=50.00 partial_payment_balance=49.99
Response Variables:
amount_authorized - Approved amount (less than requested)partial_payment_balance - Remaining balance
Handling: if ( $result [ 'responsetext' ] == 'PARTIAL APPROVAL' ) { $approved = $result [ 'amount_authorized' ]; $remaining = $result [ 'partial_payment_balance' ]; // Option 1: Accept partial amount completeOrderWithPartial ( $approved ); // Option 2: Request additional payment requestAdditionalPayment ( $remaining ); // Option 3: Void and request full amount elsewhere voidTransaction ( $result [ 'transactionid' ]); requestFullPayment ( $originalAmount ); }
EMV Response Codes For EMV chip transactions:
Code Description 00Approved 01Refer to card issuer 03Invalid merchant 04Pick up card 05Do not honor 12Invalid transaction 13Invalid amount 14Invalid card number 51Insufficient funds 54Expired card 55Incorrect PIN 57Transaction not permitted 58Transaction not permitted to terminal 61Exceeds withdrawal amount limit 62Restricted card 63Security violation 65Exceeds withdrawal frequency limit
ACH Return Codes Common ACH return codes:
Code Description Type R01Insufficient Funds NSF R02Account Closed Account R03No Account/Unable to Locate Account R04Invalid Account Number Account R05Unauthorized Debit to Consumer Account Authorization R06Returned per ODFI Request Authorization R07Authorization Revoked Authorization R08Payment Stopped Stop Payment R09Uncollected Funds NSF R10Customer Advises Not Authorized Authorization R11Check Truncation Entry Return Entry R12Account Sold to Another DFI Account R13Invalid ACH Routing Number Routing R14Representative Payee Deceased Account R15Beneficiary Deceased Account R16Account Frozen Account R20Non-Transaction Account Account R29Corporate Customer Advises Not Authorized Authorization
Certain ACH return codes (R01, R09) allow retry after 30 days. Others (R02, R03, R04) should not be retried.
Chargeback Reason Codes Visa Reason Codes Code Description Category 10.1EMV Liability Shift Counterfeit Fraud Fraud 10.2EMV Liability Shift Non-Counterfeit Fraud Fraud 10.3Other Fraud - Card Present Environment Fraud 10.4Other Fraud - Card Absent Environment Fraud 10.5Visa Fraud Monitoring Program Fraud 11.1Card Recovery Bulletin Authorization 11.2Declined Authorization Authorization 11.3No Authorization Authorization 12.1Late Presentment Processing 12.2Incorrect Transaction Code Processing 12.3Incorrect Currency Processing 12.4Incorrect Account Number Processing 12.5Incorrect Amount Processing 13.1Merchandise Not Received Consumer Dispute 13.2Cancelled Recurring Consumer Dispute 13.3Not as Described Consumer Dispute
Mastercard Reason Codes Code Description Category 4837No Cardholder Authorization Fraud 4840Fraudulent Processing of Transaction Fraud 4841Cancelled Recurring Transaction Consumer Dispute 4842Late Presentment Processing 4853Cardholder Dispute Consumer Dispute 4854Cardholder Dispute (US Region Only) Consumer Dispute 4855Non-Receipt of Merchandise Consumer Dispute 4859Services Not Rendered Consumer Dispute 4860Credit Not Processed Consumer Dispute
Testing Response Codes Test Card Numbers Card Number AVS Response CVV Response Result 4111111111111111XMApproved 4000000000000002NNDeclined (AVS/CVV fail) 4000000000000010YMApproved 4000000000000028- - Declined (Insufficient Funds) 4000000000000036- - Declined (Do Not Honor) 4000000000000044- - Declined (Expired Card)
Test Amounts Use specific amounts to trigger responses:
Amount Response x.00Approved x.01Declined x.02Error x.05Approved with AVS=N x.10Partial approval ($50.00)
Best Practices
Log All Responses Store complete response data for troubleshooting and compliance
Display User-Friendly Messages Translate technical codes to customer-friendly language
Implement Fraud Rules Configure AVS/CVV rules based on your risk profile
Handle Retries Gracefully Implement appropriate retry logic for specific errors
Error Message Examples Convert technical responses to customer-friendly messages:
function getCustomerMessage ( $responsetext ) { $messages = [ 'DECLINE' => 'Your card was declined. Please use a different payment method.' , 'INSUFFICIENT FUNDS' => 'Your card has insufficient funds. Please use a different card.' , 'INVALID CARD NUMBER' => 'The card number you entered is invalid. Please check and try again.' , 'CARD EXPIRED' => 'Your card has expired. Please use a different card.' , 'DO NOT HONOR' => 'Your card was declined. Please contact your bank or use a different card.' , 'CALL FOR AUTHORIZATION' => 'Please contact your card issuer to authorize this transaction.' , ]; return $messages [ $responsetext ] ?? 'Payment processing failed. Please try again or use a different payment method.' ; }
Next Steps 
