Skip to content
Create account
 or
Sign in
The Stripe Docs logo
/
Create account
Sign in
OverviewUpgrade your integration
Online payments
OverviewFind your use case
Payment methods
Payment UIs
Payment scenarios
In-person payments
Other Stripe products

Collect customer detailsBeta

Collect email addresses, physical addresses, and other customer details.

Email addresses

Custom Checkout requires you to collect customer email addresses.

Create a component to collect your customer’s email address. Call updateEmail when your customer finishes the input to validate and save the email address.

  • If you have a multi-step form, call updateEmail before moving to the next step, such as clicking a Save button.
  • If you have a single-page form, call updateEmail before submitting the payment. You can also call updateEmail to validate earlier, such as on input blur.
EmailInput.jsx
import React from 'react';
import {useCheckout} from '@stripe/react-stripe-js';

const EmailInput = () => {
  const checkout = useCheckout();
  const [email, setEmail] = React.useState('');
  const [error, setError] = React.useState(null);

  const handleBlur = () => {
    checkout.updateEmail(email).then((result) => {
      if (result.type === 'error') {
        setError(result.error);
      }
    })
  };

  const handleChange = (e) => {
    setError(null);
    setEmail(e.target.value);
  };
  return (
    <div>
      <input
        type="text"
        value={email}
        onChange={handleChange}
        onBlur={handleBlur}
      />
      {error && <div>{error.message}</div>}
    </div>
  );
};

export default EmailInput;

Billing addresses

By default, Checkout collects the minimal billing details required for payment through the Payment Element.

Using Address Element

You can collect complete billing addresses using the Address Element.

First, pass billing_address_collection=required when you create the Checkout Session.

Create a container DOM element to mount the Address Element. Then create an instance of the Address Element using checkout.createElement and mount it by calling element.mount, providing either a CSS selector or the container DOM element.

index.html
<div id="billing-address"></div>
checkout.js
const billingAddressElement = checkout.createElement('address', {mode: 'billing'});
billingAddressElement.mount('#billing-address');

The following options are supported:

Using a custom form

You can build your own form to collect billing addresses.

  • If your checkout page has a distinct address collection step before confirmation, call updateBillingAddress when your customer submits the address.
  • Otherwise, you can submit the address when your customer clicks the “pay” button by passing billingAddress to confirm.

Collect partial billing addresses

To collect partial billing addresses, such as just the country and postal code, pass billing_address_collection=auto.

When collecting partial billing addresses, you must collect addresses manually. By default, Payment Element is configured to automatically collect the minimal billing details required for payment. To avoid double collection of billing details, pass fields.billingDetails=never when creating the Payment Element. If you only intend to collect a subset of billing details (such as the customer’s name), pass never for only the fields you intend to collect yourself.

Shipping addresses

To collect a customer’s shipping address, pass the shipping_address_collection parameter when you create the Checkout Session.

When you collect a shipping address, you must also specify which countries to allow shipping to. Configure the allowed_countries property with an array of two-letter ISO country codes property with an array of two-letter ISO country codes.

Using Address Element

You can collect complete shipping addresses with the Address Element.

Create a container DOM element to mount the Address Element. Then create an instance of the Address Element using checkout.createElement and mount it by calling element.mount, providing either a CSS selector or the container DOM element.

index.html
<div id="shipping-address"></div>
checkout.js
const shippingAddressElement = checkout.createElement('address', {mode: 'shipping'});
shippingAddressElement.mount('#shipping-address');

The following options are supported:

Using a custom form

You can build your own form to collect shipping addresses.

  • If your checkout page has a distinct address collection step before confirmation, call updateShippingAddress when your customer submits the address.
  • Otherwise, you can submit the address when your customer clicks the “pay” button by passing shippingAddress to confirm.
Was this page helpful?
YesNo
Need help? Contact Support.
Join our early access program.
Check out our product changelog.
Questions? Contact Sales.
Powered by Markdoc