Interpret payment response codes
Separate approval, decline, transaction errors and card-verification signals.
Read the result at the correct level
HTTP status describes the request exchange. The Payment API response field describes the gateway transaction result; response_code adds detail. Neither an HTTP 200 alone nor an AVS/CVV match proves a successful payment. Preserve the gateway transaction identifier with your order and handle missing or contradictory results as uncertain. response Meaning Application treatment 1 Approved Verify required result fields and persist the gateway ID 2 Declined Keep the order unpaid; provide a safe message 3 Transaction-data error or system error Inspect detailed code and request state; do not assume retry is safe
Use detailed codes to route recovery
These are selected documented codes that affect implementation decisions. Preserve the original code for support and do not display sensitive issuer guidance verbatim to every user. Code Documented meaning Recommended application action 100 Approved Record approval with the transaction ID 200 / 201 / 202 / 203 / 204 Processor decline / do not honor / insufficient funds / over limit / transaction not allowed Use the appropriate customer recovery path; no automatic repeated charge 220 / 223 / 224 / 225 Incorrect payment information / expired card / invalid expiry / invalid security code Allow correction through hosted fields 261 / 262 Stop all recurring payments / stop this recurring program Stop the applicable automated billing and review the agreement 263 / 264 Updated cardholder data available / retry in a few days Follow the specific program policy; do not immediately retry 300 Gateway rejection Inspect input and gateway details 301 Rate limit exceeded in the rate-limit guide Apply backpressure; separate from uncertain-payment recovery 410 / 411 Invalid configuration / inactive merchant Escalate account configuration 420 / 421 Communication failure / issuer communication failure Keep outcome recoverable and investigate 430 Duplicate at processor Reconcile existing payment instead of creating a replacement 460 / 461 Feature unavailable / unsupported card type Check enabled account/processor capabilities
Interpret AVS independently
AVS compares address information and is a risk signal alongside the transaction result. The source lists overlapping aliases; it even assigns B to both address-only match and unavailable. Do not invent a definitive interpretation for that ambiguous value. Confirm processor-specific handling before using it in an automated decision. Selected AVS codes Source meaning X Address and nine-character ZIP match Y, D, M Address and five-character ZIP match A Address-only match W Nine-character ZIP-only match Z, P, L Five-character ZIP-only match N, C No address or ZIP match U Address unavailable G, I Non-U.S. issuer does not participate R Issuer unavailable B Conflicting entries in source: confirm processor interpretation
Interpret CVV independently
Store only the verification result needed for your payment record, never the security code itself. A mismatch or unavailable result does not overwrite the gateway’s transaction state; apply your agreed fraud policy consistently. CVV result Meaning M Match N No match P Not processed S Merchant indicated security code not present U Issuer certification or encryption-key support unavailable
Build a stable normalization boundary
Normalize string or numeric response values without changing their meaning. Keep unknown outcomes visible to operations, use your own customer-safe messages and retain only redacted diagnostic fields. Do not treat a parsed decline as permission for background retries; customer action, token lifecycle and program rules still apply. Check transport status and validate the expected response shape. Inspect response and response_code; retain any returned transaction ID. Update the order only from a confirmed outcome. Keep authentication and AVS/CVV evidence distinct from payment approval. Reconcile unclear outcomes before another submission. Server token submission Errors and uncertainty Rate limits