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
Phone number
Autocomplete
Contacts
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
Select a language
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
# Available as a gem
sudo gem install stripe
Gemfile
Select a language
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
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.initCheckoutElementsSdk({
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 to collect a billing or shipping address, and mount it to the container DOM node.
If you already created a Checkout instance, you can use the same instance to create the Address Element. Otherwise, create a new Checkout 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', (event) => {
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 pass defaultValues when initializing the checkout SDK, which lets you prefill the address form when the page loads. An Address Element with all values prefilled looks similar to:
checkout = stripe.initCheckoutElementsSdk({
clientSecret: promise,
elementsOptions: { appearance },
defaultValues: {
billingAddress: {
name: 'Jane Doe',
address: {
line1: '354 Oyster Point Blvd',
line2: '',
city: 'South San Francisco',
state: 'CA',
postal_code: '94080',
country: 'US',
},
},
shippingAddress: {
name: 'Jane Doe',
address: {
line1: '354 Oyster Point Blvd',
line2: '',
city: 'South San Francisco',
state: 'CA',
postal_code: '94080',
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.”
You can validate addresses by confirming the Checkout Session, which automatically validates the Address Element and displays any validation errors.
Optional Customize the appearance Client-side
Use the Address Element with other elements
You can collect both shipping and billing addresses by using multiple Address Elements on your page.
If you need to collect both shipping and billing addresses and want to use only one Address Element, use the Shipping Address Element along with the Payment Element, which collects only the necessary billing address details.
When you use the Address Element with other elements, there is some automatic behavior when confirming the Checkout Session. The Address Element validates completeness when confirming the Checkout Session, and then displays errors for each field if there are any validation errors.
Sync billing and shipping addresses
When you use both a Billing Address Element and Shipping Address Element, you can show a checkbox that lets customers sync their billing and shipping addresses.
Pass the syncAddressCheckbox option in elementsOptions when initializing Checkout to configure which Address Element shows the checkbox.
checkout.js
const checkout = stripe.initCheckoutElementsSdk({
clientSecret,
elementsOptions: {
syncAddressCheckbox: 'shipping',
},
});
Set the value to 'billing' or 'shipping' to choose which Address Element shows the checkbox. Set it to 'none' to hide the checkbox, or leave it blank to use the default value ( 'billing').