Collect customer names
Collect business and individual names as first-class fields during checkout.
You can collect business or individual names from your customers by enabling name_collection on the Checkout Session. These first-class names are separate from the names collected in billing and shipping addresses, and they always appear as top-level name fields when you enable them.
Enable name collection Server-side
Create a Checkout Session and specify name collection settings. To enable name collection, configure the name_collection object when you create the Checkout Session. You can collect business names, individual names or both and set each field to required or optional based on your needs.
Command Line
Select a language
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
Common mistake
When you set business name collection to required, express checkout and one-click buttons, such as Apple Pay, move to the bottom of the payment form or are disabled.
Collect a business name Client-side
Use the Tax ID Element or build a custom form to collect business names.
Use the Tax ID Element
When name_collection.business.enabled is true on the Checkout Session and the Tax ID Element is mounted, the element automatically renders a business name field. For customers in countries without a supported tax ID type, the element shows only the business name field.
Create a container DOM element to mount the Tax ID Element. Then create the Tax ID Element with checkout.createTaxIdElement and mount it by calling element.mount, using either a CSS selector or the container DOM element.
checkout.html
<div id="tax-id-element"></div>
checkout.js
const taxIdElement = checkout.createTaxIdElement();
taxIdElement.mount('#tax-id-element');
When name_collection.business.enabled is true, the Tax ID Element automatically shows the business name field. You can control this behaviour with the fields.businessName option:
checkout.js
// Business name is shown automatically (default behavior)
const taxIdElement = checkout.createTaxIdElement();
checkout.js
// Explicitly hide business name to collect it via updateBusinessName() instead
const taxIdElement = checkout.createTaxIdElement({
fields: {businessName: 'never'}
});
Common mistake
If the Tax ID Element is mounted with fields.businessName shown, which is the default, don’t also call updateBusinessName(). Calling confirm() in this case throws an error. To collect the business name through your own custom form, set fields.businessName to never on the Tax ID Element.
Use a custom form
To collect business names through your own form, call updateBusinessName.
checkout.html
<label for="business-name">Business name</label>
<input type="text" id="business-name" />
<button id="update-business-name">Save</button>
checkout.js
const businessNameInput = document.getElementById('business-name');
const updateButton = document.getElementById('update-business-name');
updateButton.addEventListener('click', async () => {
await checkout.updateBusinessName(businessNameInput.value);
});
If you use the Tax ID Element, set fields.businessName to never before you call updateBusinessName().
Collect an individual name Client-side
To collect individual names, build a custom form and call updateIndividualName. There’s no pre-built Element for individual name collection.
checkout.html
<label for="individual-name">Full name</label>
<input type="text" id="individual-name" />
<button id="update-individual-name">Save</button>
checkout.js
const individualNameInput = document.getElementById('individual-name');
const updateButton = document.getElementById('update-individual-name');
updateButton.addEventListener('click', async () => {
await checkout.updateIndividualName(individualNameInput.value);
});
Read collected names from the session Client-side
You can read the collected names from the Session object at any time during the session. The values are available on session.nameCollection.
checkout.js
checkout.on('change', (session) => {
const businessName = session.nameCollection.businessName;
const individualName = session.nameCollection.individualName;
// Update your UI with the collected names
});
Retrieve the collected names Server-side
After the session, you can retrieve customers’ business or individual names from the resulting Account or Customer object, or from the Checkout Session object:
On the customer
Checkout saves collected names in the Account object’s identity.business_details.registered_name or display_name property.
You can access the names programmatically by either retrieving the Account object or listening for the v2.core.account.created webhook event.
{
"id": "acct_1Nv0FGQ9RKHgCVdK",
"object": "v2.core.account",
"applied_configurations": [
"customer",
"merchant"
],
"configuration": {
"customer": {},
"merchant": {}
},
...
"identity": {
"business_details": {
"registered_name": "Stripe, Inc.",
}
},
...
"display_name": "Jenny Rosen"
}
You can also view the customer names in the Dashboard.
On the Checkout Session
The customer’s names are also saved in the collected_information and customer_details hash of the Checkout Session object, under:
- collected_information.business_name and collected_information.individual_name
- customer_details.business_name and customer_details.individual_name
{
"object": {
"id": "cs_test_a1dJwt0TCJTBsDkbK7RcoyJ91vJxe2Y",
"object": "checkout.session",
...
"collected_information": {
"business_name": "Stripe, Inc.",
"individual_name": "Jenny Rosen"
},
...
"customer": "cus_id_of_new_customer",
"customer_details": {
...
"business_name": "Stripe, Inc.",
"individual_name": "Jenny Rosen",
"name": "Stripe, Inc."
},
...
}
}
After each successful Checkout Session, Stripe sends the checkout.session.completed event containing the Checkout Session object and collected values, which you can listen for in a webhook.