Collect physical addresses and phone numbers
Learn how to collect addresses and phone numbers during one-time 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.
Set up StripeServer-side
First, create a Stripe account or sign in.
Use our official libraries to access the Stripe API from your application:
Collect address detailsClient-side
You’re ready to collect address details on the client with the Address Element.
Retrieve address detailsClient-side
You can retrieve the address details by listening to the change event. The change
event fires whenever the user updates any field in the Element.
In a single-page checkout flow with the Payment Element, the Address Element automatically passes the shipping or billing information when you confirm the Checkout Session.
Configure the Address ElementClient-side
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.
Prefill address form
You can use the updateBillingAddress or updateShippingAddress to prefill an address.
Validate address detailsClient-side
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, you can validate addresses by confirming the Checkout Session, which automatically validates the Address Element and displays any validation errors.
OptionalCustomize the appearanceClient-side
After you add the Address Element to your page, you can customize the appearance to fit with the design of the rest of your page. See the Appearance API page for more information.

Use the Address Element with other elements
You can collect both shipping and billing addresses by using multiple Address Elements, one of each mode, on your page.
If you need to collect both shipping and billing addresses and only want to use one Address Element, use the Address Element in shipping mode and use the Payment Element to collect only the necessary billing address details.
When you use the Address Element with other elements, you can expect some automatic behavior when confirming the PaymentIntent or SetupIntent. The Address Element validates completeness when confirming the PaymentIntent or SetupIntent, and then displays errors for each field if there are any validation errors.