# 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](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-name_collection) on the Checkout Session. These *first-class* (First-class fields are prominent input fields that appear at the top level of the payment form and API, rather than being grouped within other sections such as billing or shipping details) 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](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-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.

```curl
curl https://api.stripe.com/v1/checkout/sessions \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d mode=payment \
  -d ui_mode=elements \
  --data-urlencode "return_url=https://example.com/return" \
  -d "line_items[0][price]={{PRICE_ID}}" \
  -d "line_items[0][quantity]=1" \
  -d "name_collection[business][enabled]=true" \
  -d "name_collection[individual][enabled]=true" \
  -d "name_collection[individual][optional]=true"
```

> 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](https://docs.stripe.com/js/custom_checkout/create_tax_id_element) is mounted, the element automatically renders a business name field. For buyers in countries without a supported tax ID type, the element shows only the business name field.

#### HTML + JS

Create a container DOM element to mount the Tax ID Element. Then create the Tax ID Element with [checkout.createTaxIdElement](https://docs.stripe.com/js/custom_checkout/create_tax_id_element) and mount it by calling [element.mount](https://docs.stripe.com/js/element/mount), using either a CSS selector or the container DOM element.

```html
<div id="tax-id-element"></div>
```

```javascript
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 behavior with the `fields.businessName` option:

```javascript
// Business name is shown automatically (default behavior)
const taxIdElement = checkout.createTaxIdElement();
```

```javascript
// Explicitly hide business name to collect it via updateBusinessName() instead
const taxIdElement = checkout.createTaxIdElement({
  fields: {businessName: 'never'}
});
```

#### React

Mount the `TaxIdElement` component in the `CheckoutElementsProvider`.

```jsx
import React from 'react';
import {TaxIdElement} from '@stripe/react-stripe-js/checkout';

const CheckoutForm = () => {
  return (
    <form>
      <TaxIdElement />
    </form>
  )
};
```

When `name_collection.business.enabled` is `true`, the Tax ID Element automatically shows the business name field. You can control this behavior with the `fields.businessName` option:

```jsx
// Explicitly hide business name to collect it via updateBusinessName() instead
<TaxIdElement options={{fields: {businessName: 'never'}}} />
```

> 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](https://docs.stripe.com/js/custom_checkout/update_business_name).

#### HTML + JS

```html
<label for="business-name">Business name</label>
<input type="text" id="business-name" />
<button id="update-business-name">Save</button>
```

```javascript
const businessNameInput = document.getElementById('business-name');
const updateButton = document.getElementById('update-business-name');

updateButton.addEventListener('click', async () => {
  await checkout.updateBusinessName(businessNameInput.value);
});
```

#### React

```jsx
import React, {useState, useCallback} from 'react';
import {useCheckout} from '@stripe/react-stripe-js/checkout';

const BusinessNameForm = () => {
  const checkout = useCheckout();
  const [businessName, setBusinessName] = useState('');

  const handleSubmit = useCallback(async () => {
    await checkout.updateBusinessName(businessName);
  }, [checkout, businessName]);

  return (
    <div>
      <label htmlFor="business-name">Business name</label>
      <input
        id="business-name"
        type="text"
        value={businessName}
        onChange={(e) => setBusinessName(e.target.value)}
      />
      <button onClick={handleSubmit}>Save</button>
    </div>
  );
};
```

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](https://docs.stripe.com/js/custom_checkout/update_individual_name). There’s no pre-built Element for individual name collection.

#### HTML + JS

```html
<label for="individual-name">Full name</label>
<input type="text" id="individual-name" />
<button id="update-individual-name">Save</button>
```

```javascript
const individualNameInput = document.getElementById('individual-name');
const updateButton = document.getElementById('update-individual-name');

updateButton.addEventListener('click', async () => {
  await checkout.updateIndividualName(individualNameInput.value);
});
```

#### React

```jsx
import React, {useState, useCallback} from 'react';
import {useCheckout} from '@stripe/react-stripe-js/checkout';

const IndividualNameForm = () => {
  const checkout = useCheckout();
  const [individualName, setIndividualName] = useState('');

  const handleSubmit = useCallback(async () => {
    await checkout.updateIndividualName(individualName);
  }, [checkout, individualName]);

  return (
    <div>
      <label htmlFor="individual-name">Full name</label>
      <input
        id="individual-name"
        type="text"
        value={individualName}
        onChange={(e) => setIndividualName(e.target.value)}
      />
      <button onClick={handleSubmit}>Save</button>
    </div>
  );
};
```

## Read collected names from the session [Client-side]

You can read the collected names from the [Session object](https://docs.stripe.com/js/custom_checkout/session_object) at any time during the session. The values are available on `session.nameCollection`.

#### HTML + JS

```javascript
checkout.on('change', (session) => {
  const businessName = session.nameCollection.businessName;
  const individualName = session.nameCollection.individualName;
  // Update your UI with the collected names
});
```

#### React

```jsx
import React from 'react';
import {useCheckout} from '@stripe/react-stripe-js/checkout';

const NameDisplay = () => {
  const checkoutState = useCheckout();
  if (checkoutState.type !== 'success') return null;
  const {businessName, individualName} = checkoutState.checkout.nameCollection;

  return (
    <div>
      {businessName && <p>Business: {businessName}</p>}
      {individualName && <p>Individual: {individualName}</p>}
    </div>
  );
};
```

## Retrieve the collected names [Server-side]

After the session, you can retrieve customers’ business or individual names from the resulting [Account](https://docs.stripe.com/api/v2/core/accounts/object.md) or [Customer](https://docs.stripe.com/api/customers/object.md) object, or from the *Checkout Session* (A Checkout Session represents your customer's session as they pay for one-time purchases or subscriptions through Checkout. After a successful payment, the Checkout Session contains a reference to the Customer, and either the successful PaymentIntent or an active Subscription) object:

### On the customer

#### Accounts v2

Checkout saves collected names in the `Account` object’s [identity.business_details.registered_name](https://docs.stripe.com/api/v2/core/accounts/object.md#v2_account_object-identity-business_details-registered_name) or [display_name](https://docs.stripe.com/api/v2/core/accounts/object.md#v2_account_object-display_name) property.

You can access the names programmatically by either [retrieving the Account object](https://docs.stripe.com/api/v2/core/accounts/retrieve.md) or listening for the [v2.core.account.created](https://docs.stripe.com/api/v2/core/events/event-types.md#v2_event_types-v2.core.account.created) *webhook event* (A webhook is a real-time push notification sent to your application as a JSON payload through HTTPS requests).

```json
{
  "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"
}
```

#### Customers v1

Checkout saves collected names in the `Customer` object’s [business_name](https://docs.stripe.com/api/customers/object.md#customer_object-business_name) or [individual_name](https://docs.stripe.com/api/customers/object.md#customer_object-individual_name) property.

You can access the names programmatically by either [retrieving the Customer object](https://docs.stripe.com/api/customers/retrieve.md), or listening for the [customer.created](https://docs.stripe.com/api/events/types.md#event_types-customer.created) *webhook event* (A webhook is a real-time push notification sent to your application as a JSON payload through HTTPS requests).

The Customer object’s [name](https://docs.stripe.com/api/customers/object.md#customer_object-name) is also set to the `business_name` or `individual_name`, in that order.

```json
{
  "object": {
    "id": "cus_HQmikpKnGHkNwW",
    "object": "customer",
    ...
    "name": "Stripe, Inc.""business_name": "Stripe, Inc."
    ..."individual_name": "Jenny Rosen"
    ...
  }
}
```

You can also view the customer names in the [Dashboard](https://dashboard.stripe.com/customers).

### 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](https://docs.stripe.com/api/checkout/sessions/object.md#checkout_session_object-collected_information-business_name) and [collected_information.individual_name](https://docs.stripe.com/api/checkout/sessions/object.md#checkout_session_object-collected_information-individual_name)
- [customer_details.business_name](https://docs.stripe.com/api/checkout/sessions/object.md#checkout_session_object-customer_details-business_name) and [customer_details.individual_name](https://docs.stripe.com/api/checkout/sessions/object.md#checkout_session_object-customer_details-individual_name)

```json
{
  "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](https://docs.stripe.com/api/events/types.md#event_types-checkout.session.completed) event containing the Checkout Session object and collected values, which you can listen for in a *webhook* (A webhook is a real-time push notification sent to your application as a JSON payload through HTTPS requests).