What an AVS test is
An AVS test is a payment authorization run with known test card data to confirm that your checkout page sends billing address fields to the processor and that your system reads the Address Verification System response correctly. The test does not move real money. It validates plumbing: field mapping, gateway configuration, and the logic you use to accept, hold, or decline an order based on the match result.
What the test checks
AVS compares the numeric portion of the street address and the ZIP code you submit against the records the issuing bank holds for that card. The issuer returns a single letter code, and your gateway passes it back. A test confirms three things: that your form captures the fields, that the values reach the processor without truncation, and that your code branch for each letter behaves as intended.
- Street address numeric match
- Five-digit ZIP match
- Full nine-digit ZIP match where supported
- Handling of missing or unsupported address data
- Behavior for international issuers
Prerequisites
- Sandbox or test account credentials for your gateway
- Published test card numbers from the gateway documentation
- Access to request logs for the authorization call
- A written list of expected response codes for each scenario
How to run an AVS test
- Open your gateway sandbox and confirm that test mode is active.
- Copy the test card number that maps to the AVS scenario you want, such as full match or no match.
- Enter a billing street address and ZIP code pair that matches the expected outcome for that card.
- Submit an authorization through your own checkout flow, not a direct API call, so the form logic is exercised.
- Capture the raw gateway response and locate the AVS result field.
- Compare the returned letter against your expected code for that scenario.
- Repeat for every pair you planned: street match only, ZIP match only, no match, and unsupported.
- Test a missing ZIP field and an international card to confirm graceful handling.
- Log the pass or fail result for each case and fix any field mapping errors before moving to production.
Reading the response codes
Most processors use a shared letter set. Y means street address and five-digit ZIP both match. A means the street matches and the ZIP does not. Z means the ZIP matches and the street does not. N means neither matches. U means the issuer could not supply data. S means the card type does not support AVS. G and R signal a non-US issuer or a retry request. Write your rules against this set, not against a single success letter.
Common failures
- ZIP code sent as an integer, which drops a leading zero
- Address lines concatenated into one field, so the numeric part is lost
- A test card applied to a live endpoint, which returns no test codes
- Rules that auto-decline on A or Z when your policy allows a manual review
Repeat after any change
Re-run the full matrix after you change the checkout form, upgrade the gateway SDK, or switch processors. AVS behavior follows the acquirer and the card network, so a configuration that passed last quarter can return different letters after an update.