Skip to content
Create account
 or
Sign in
The Stripe Docs logo
/
Create account
Sign in
OverviewUpgrade your integration
Online payments
OverviewFind your use caseUse Managed Payments
Payment methods
Payment interfaces
Payment scenarios
In-person payments
Beyond payments

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.

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

Was this page helpful?
YesNo