Collect customer tax IDs with Checkout

Learn how to collect VAT and other customer Tax IDs during Checkout.

Displaying a customer’s Tax ID and legal business name on invoices is a common requirement that you can satisfy by enabling Tax ID Collection in Checkout. Tax ID Collection works with all Checkout Integration types: the hosted page, embedded page and elements mode.

Business tax IDs only

The Checkout Sessions API only collects business tax IDs, which might have formats similar to personal tax IDs in certain jurisdictions. You must make sure that only business tax IDs, as designated for this field, are provided when using this feature.

Enable tax ID collection Server-side

With Tax ID Collection enabled, Checkout shows and hides the Tax ID Collection form depending on your customer’s location. If your customer is in a location supported by Tax ID Collection, Checkout displays fields for them to enter the Tax ID and legal entity name for their business. If available, Checkout uses the customer’s shipping address to determine their location, otherwise it uses the billing address. Customers can only enter one Tax ID.

New customers

To enable tax ID collection for new customers, set tax_id_collection[enabled] to true when creating a Checkout Session.

Command Line

Select a language

cURL

Stripe CLI

Ruby

Python

PHP

Java

Node.js

Go

.NET

No results

You can additionally configure Checkout to create a new customer-configured Account or Customer for you using customer_creation. If you do, Checkout saves any Tax ID information collected during a session to that new Account or Customer. If not, the Tax ID information is still available at customer_details.tax_ids.

Existing customers

Create a Checkout Session with an existing customer to add any tax ID information collected during checkout. If the customer doesn’t have an existing tax ID, Checkout collects one. If the customer has one or more saved tax IDs, Checkout doesn’t display the tax ID collection form even if tax ID collection is enabled.

When creating the Checkout Session, set customer_update.name to auto to automatically update the customer’s name using details from the session.

If you don’t have saved addresses for existing customers, use the billing or shipping address entered during Checkout to assess their location. The following table describes the available options:

Create a Checkout Session with an existing v2 Account to add any tax ID information collected during checkout. The Checkout Session saves the business name to the identity object and saves the collected tax ID as a Tax ID resource associated with the account.

Command Line

Select a language

cURL

Stripe CLI

Ruby

Python

PHP

Java

Node.js

Go

.NET

No results

Optional Require tax ID collection

Optional Collect Tax IDs in the payment form

Retrieve customer tax ID details after a session

Checkout includes provided tax IDs on the resulting Session object. After each completed Session, Checkout emits a checkout.session.completed event that you can listen for in a webhook endpoint. If you want to retrieve the collected tax ID from the Session object, it’s available under the Session’s customer_details.tax_ids array:

{
 "object": {
 "id": "cs_test_a1dJwt0TCJTBsDkbK7RcoyJ91vJxe2Y",
 "object": "checkout.session",
 ...
 "customer": __TOKEN_PLACEHOLDER_0__,
 "customer_details": {
 ...
 "tax_ids": [
 {
 "type": "eu_vat",
 "value": "FRAB123456789"
 }
 ]
 },
 ...
 "tax_id_collection": {
 "enabled": true
 }
 ...
 }
}

Checkout saves collected tax IDs and business names to the Customer object when you associate the Checkout Session with a Customer. Checkout stores a collected tax ID under the customer.tax_ids array on the Customer. You can retrieve all tax IDs saved to a Customer with the Tax IDs resource by setting owner.type to customer and owner.customer to the customer ID. Checkout saves the business name to the Customer’s name and business_name properties. Your subscription invoices always show the collected legal business name.

Test your integration

In testing environments, you can enter any alphanumeric string that is in the correct format of a supported tax ID type (for example, the related setting for eu_vat). For a full list of example tax IDs you can reference our Customer Tax ID guide. You can also use our test tax IDs to test various verification state flows.

Validation

During the Checkout Session, Stripe verifies that the provided tax IDs are formatted correctly, but not that they’re valid. You’re responsible for ensuring the validity of customer information collected during checkout.

Stripe automatically performs asynchronous validation against government databases for Australian Business Numbers (ABNs), European Value Added Tax (EU VAT), and United Kingdom Value Added Tax (GB VAT) numbers.

Stripe sends an event when verification finishes for a tax ID saved to either of these objects:

• For a Customer , listen for the customer.tax_id.updated snapshot event. Inspect data.object.verification.status in the event.
• For a customer-configured Account , listen for the v1.customer.tax_id.updated thin event. Retrieve the Tax ID referenced by related _ object , then inspect its verification.status .

The status is pending, verified, unverified, or unavailable.

The checkout.session.completed event can arrive before the authority verification finishes. Stripe sends the applicable tax ID update event only when Checkout saves the tax ID to a Customer or customer-configured Account. For Guest customers, customer_details.tax_ids contains the collected tax ID type and value, but not a verification result, and Stripe doesn’t send a tax ID update event. To receive the result, save the tax ID to a Customer or customer-configured Account. Otherwise, verify the tax ID independently.

Stripe reports the verification result, and you’re responsible for determining how to handle an unverified tax ID, based on your own compliance requirements. When automatic validation is unavailable, you must manually verify the tax ID.

If you use Stripe Tax, Stripe Tax applies the reverse charge or zero rate according to applicable laws when the tax ID has the required number format, regardless of the government verification result.

Supported tax ID types

Checkout collects the following tax ID types in the given regions:

See also

• Automatically collect tax with the Checkout page
• Collect tax with Elements
• Test your tax integration