Collect physical addresses and phone numbers
Learn how to collect addresses and phone numbers during one-off payment flows.
To collect complete addresses for billing or shipping, use the Address Element. You might need to collect a full billing address to calculate taxes, for example. The Payment Element only collects the billing address details required to complete the payment, but you can configure it to collect other billing details.
Other reasons you might want to use the Address Element:
- To collect customer phone numbers
- To enable autocomplete
- To prefill billing information in the Payment Element by passing in a shipping address
Stripe combines the collected address information and the payment method to create a PaymentIntent.
First, create a Stripe account or sign in.
Use our official libraries to access the Stripe API from your application:
You can retrieve the address details by listening to the change event. The change
event triggers whenever your customer updates a field in the Element.
Alternatively, you can use getValue.
In a single-page checkout flow with the Payment Element, the Address Element automatically passes the shipping or billing information when you confirm the PaymentIntent or SetupIntent.
In a multi-page checkout flow, you can manually update the PaymentIntent or update the Customer object with the address details received from the change
event or getValue
method before moving to the next step.
You can configure the Address Element to suit your needs.
Autocomplete
The Address Element has a built-in address autocomplete feature that uses the Google Maps API Places Library. By default, the autocomplete is enabled with a Stripe-provided Google Maps API key if any of the following conditions are met:
- In a single page checkout flow where the Payment Element is mounted in the same Elements group as the Address Element.
- In a checkout flow that uses the Address Element in an active Link session.
To enable autocomplete in the Address Element for all other scenarios, you can use the autocomplete option with mode
set to google_
. Set the apiKey
to your own Google Maps API key that’s configured to allow the Places API usage. Your Google Maps API key is only used when the Stripe-provided Google Maps API key isn’t available.
Note
If you’ve deployed a CSP and want to enable autocomplete with your own Google Maps API key, include https://maps.
as a connect-src
and script-src
directive. Refer to the Google Maps API official guide for the most updated CSP requirement.
Prefill address form
The Address Element accepts defaultValues, which lets you prefill the address form when the page loads. An Address Element with all values prefilled looks similar to:
Other options
Refer to Stripe.js for the complete list of options in detail.
Stripe provides a few ways to validate completeness of an address and trigger errors to display on any incomplete individual address fields. For example, “This field is incomplete.”
If you use the Address Element with a PaymentIntent or SetupIntent, use stripe.confirmPayment or stripe.confirmSetup, respectively to complete the Intent. Validation errors, if any, appear in the Address Element.
For other use cases, such as a multi-page checkout flow, use getValue to trigger validation errors to display in the Address Element.
After you add the Address Element to your page, you can customise the appearance to fit with the design of the rest of your page. See the Appearance API page for more information.
