Skip to content
Create account
or
Sign in
The Stripe Docs logo
/
Ask AI
Create account
Sign in
Get started
Payments
Revenue
Platforms and marketplaces
Money management
Developer resources
APIs & SDKsHelp
Overview
About Stripe payments
Upgrade your integration
Payments analytics
Online payments
OverviewFind your use caseUse Managed Payments
Use Payment Links
Use a pre-built checkout page
Build a custom integration with Elements
    Overview
    Compare Checkout Sessions and PaymentIntents
    Quickstart guides
    Design an advanced integration
    Customise look and feel
    Manage payment methods
    Collect additional information
      Collect physical addresses and phone numbers
      Customise billing details collection
      Charge for shipping
    Build a subscriptions integration
    Dynamic updates
    Add discounts
    Collect taxes on your payments
    Redeem credits
    Let customers pay in their local currency
    Save and retrieve customer payment methods
    Send receipts and paid invoices
    Manually approve payments on your server
    Authorise and capture a payment separately
    Elements with Checkout Sessions API beta changelog
Build an in-app integration
Payment Methods
Add payment methods
Manage payment methods
Faster checkout with Link
Payment interfaces
Payment Links
Checkout
Web Elements
In-app payments
Payment scenarios
Handle multiple currencies
Custom payment flows
Flexible acquiring
Orchestration
In-person payments
Terminal
Beyond payments
Incorporate your company
Crypto
Agentic commerce
Financial Connections
Climate
Understand fraud
Radar fraud protection
Manage disputes
Verify identities
United States
English (United Kingdom)
HomePaymentsBuild a custom integration with ElementsCollect additional information

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.

Theme
Size
Customer Location

Set up Stripe
Server-side

First, create a Stripe account or sign in.

Use our official libraries to access the Stripe API from your application:

Collect address details
Client-side

You’re ready to collect address details on the client with the Address Element.

Set up Stripe.js

The Address Element is automatically available as a feature of Stripe.js. Include the Stripe.js script on your checkout page by adding it to the head of your HTML file. Always load Stripe.js directly from js.stripe.com to remain PCI compliant. Don’t include the script in a bundle or host a copy of it yourself.

Create a Stripe instance

Create an instance of Stripe on your payment page:

Add the Address Element to your page

The Address Element needs a place on your page. Create an empty DOM node (container) with a unique ID in your form.

After this form loads, create an instance of the Address Element, specify the address mode and mount it to the container DOM node.

If you already created an Elements instance, you can use the same instance to create the Address Element. Otherwise, create a new Elements instance first.

Retrieve address details
Client-side

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.

Configure the Address Element
Client-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.

To enable autocomplete in the Address Element for all other scenarios, you can use the autocomplete option with mode set to google_maps_api. 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.googleapis.com 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.

Validate address details
Client-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, use getValue to trigger validation errors to display in the Address Element.

OptionalCustomise the appearance
Client-side

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.

See also

  • Use the address
  • Set up autofill with Link
  • Customise the form’s appearance
Was this page helpful?
YesNo
  • Need help? Contact Support.
  • Check out our changelog.
  • Questions? Contact Sales.
  • LLM? Read llms.txt.
  • Powered by Markdoc