Physical cards address validation
Enable and manage address validation features for physical cards.
Stripe Issuing needs accurate and properly formatted shipping addresses to ensure successful delivery of physical cards to their intended recipient. Cards sent to invalid addresses get returned to Stripe, but the delivery attempt and the eventual return can take over 2 weeks to complete. Returned cards can create an operational burden, increase your overall costs, and delay your cardholders’ receipt of your physical cards.
To maximize your delivery success, Stripe’s Cards API has built-in address normalization and validation. Stripe compares the shipping address you provide to a third-party address database and identifies or fixes any issues with the address.
Address normalization
Normalization ensures that your addresses adhere to the standards of the shipment’s country while also correcting any obvious errors in your addresses.
Examples of normalization include:
Address standardization to ensure proper formatting
Address correction to apply corrections found from matching with an existing validated address
The normalized address is included in the address validation hash that is returned after successfully creating a physical card or updating a card’s shipping address with address normalization enabled.
Sample address validation
Address validation
Validation determines whether your address is deliverable by attempting to match to an existing, validated address and is done after applying normalization.
The result of this validation is included in the address validation hash. Depending on the address validation mode used this might result in an API error.
Result | Description |
---|---|
likely_ | If a partially matching or fully matching address is found in our third party database, your address is considered likely deliverable. |
likely_ | If no matching or partially matching address is found in our third party database, your address is considered likely undeliverable. |
indeterminate | The deliverability of the address couldn’t be determined. |
For example, the previous example showed the validation result of likely_
.
Managing address validation features with address validation modes
The Cards API supports three address validation modes, which can optionally be specified in the address_validation parameter when creating a physical card or updating a card’s shipment.
Mode | Description |
---|---|
validation_ | Validates and normalizes your card’s shipping address before submitting it for fulfillment. Stripe attempts to automatically apply any appropriate corrections and formatting to your address before determining deliverability. If the card’s shipping address is likely undeliverable, you get an API request error. |
normalization_ | Normalizes your card’s shipping address before submitting it for fulfillment, and applies any appropriate corrections and formatting to your address. Address deliverability isn’t enforced, and you don’t get an API request error. |
disabled | Ships your card using the address provided as-is, without applying any normalization or validating its deliverability. This is only recommended when an address is known to be correct or otherwise validated. |
Use validation_
for the address validation mode. We also provide alternate modes depending on your scenario:
disabled
: If you believe a card is incorrectly blocked.normalization only
: If you want to minimize API errors but still gain the benefits of normalization. The default isnormalization_
if not specified.only
Validation and normalization
Your card is shipped with the validated, normalized address. Address deliverability is enforced, and the API errors if the address is likely undeliverable. Stripe strongly recommends using this mode to ensure deliverability for the address.
Normalization only
Your card will be shipped with the normalized address. Address deliverability isn’t enforced, and you don’t get an API request error if the address is likely undeliverable.
Disabled
This mode ships your card using the address provided as-is, without applying normalization or validating its deliverability. A normalized address and validation result will not be returned. This is recommended only when an address is known to be correct or otherwise validated.
Integrating address validation into your card creation flow
We provide several examples on how to integrate your flow with address validation features below. These examples are not exhaustive, and are only meant to serve as ideas to help you with your integration.
Testing address validation
You can supply a magic value for line1
to trigger certain validation conditions in testing environments. You must pass in legitimate values for the city
, state
, and postal_
arguments.
Value | Type |
---|---|
address_ | Send a request using a test deliverable shipping address. |
address_ | Send a request using an test undeliverable shipping address. |