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
Overview
About Stripe payments
Upgrade your integration
Payments analytics
Online payments
OverviewFind your use caseUse Managed Payments
Use Payment Links
Use a prebuilt checkout page
Build a custom integration with Elements
    Overview
    Compare Checkout Sessions and PaymentIntents
    Quickstart guides
    Design an advanced integration
    Customize look and feel
    Manage payment methods
    Collect additional information
      Collect physical addresses and phone numbers
      Customize 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
    Authorize 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
HomePaymentsBuild a custom integration with ElementsCollect additional information

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.

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:

Command Line
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
# Available as a gem sudo gem install stripe
Gemfile
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
# If you use bundler, you can add this line to your Gemfile gem 'stripe'

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.

checkout.html
<head> <title>Checkout</title> <script src="https://js.stripe.com/clover/stripe.js"></script> </head>

Create a Stripe instance and initialize the checkout

Create an instance of Stripe on your checkout page:

checkout.js
// Set your publishable key: remember to change this to your live publishable key in production // See your keys here: https://dashboard.stripe.com/apikeys const stripe = Stripe(
'pk_test_TYooMQauvdEDq54NiTphI7jx'
); let checkout; initialize(); async function initialize() { const promise = fetch("/create-checkout-session", { method: "POST", headers: { "Content-Type": "application/json" }, }) .then((r) => r.json()) .then((r) => r.clientSecret); const appearance = { theme: 'stripe', }; checkout = stripe.initCheckout({ clientSecret: promise, elementsOptions: { appearance }, }); }

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.

checkout.html
<form id="address-form"> <h4>Billing Address</h4> <div id="billing-address-element"> <!--Stripe.js injects the Address Element--> </div> <h4>Shipping Address</h4> <div id="shipping-address-element"> <!--Stripe.js injects the Address Element--> </div> </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.

checkout.js
const options = { // Fully customizable with the Appearance API. appearance: { /* ... */ } }; const billingAddressElement = checkout.createBillingAddressElement(); billingAddressElement.mount("#billing-address-element"); const shippingAddressElement = checkout.createShippingAddressElement(); shippingAddressElement.mount("#shipping-address-element");

Retrieve address details
Client-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.

checkout.on('change', (session) => { if (event.complete){ // Extract potentially complete address const address = event.value.address; } })

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 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.

Prefill address form

You can use the updateBillingAddress or updateShippingAddress to prefill an address.

checkout.updateBillingAddress({ name: 'Jenny Rosen', address: { line1: '27 Fredrick Ave', city: 'Brothers', state: 'OR', postal_code: '97712', country: 'US', } });

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, you can validate addresses by confirming the Checkout Session, which automatically validates the Address Element and displays any validation errors.

OptionalCustomize the appearance
Client-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.

See also

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