Collect customer tax IDs with Payment Intents

Use the Tax ID Element to collect business tax IDs from customers in your Payment Intents integration.

Collect customer tax IDs

Displaying a customer’s tax ID and legal business name on invoices is a common requirement. You can use the Tax ID Element to collect this information. This feature is in public preview.

Disclaimer

The Payment Intents API is designed to collect 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 the beta

The Tax ID Element with the Payment Intents API requires you to enable the elements_tax_id_1 beta. Add the beta to your Stripe.js initialization:

const stripe = Stripe('pk_test_TYooMQauvdEDq54NiTphI7jx', {
 betas: ['elements_tax_id_1'],
});

Create a CustomerSession (optional)

To save tax IDs and redisplay them for returning customers, create a CustomerSession, which provides secure, temporary access to customer data without exposing your secret API key to the client.

If you don’t use CustomerSession, the Tax ID Element still works but without save and redisplay functionality. You can use getValue to read the tax ID values from the element and handle them manually.

Create or retrieve a Customer:

Command Line

Select a language

cURL

Stripe CLI

Ruby

Python

PHP

Java

Node.js

Go

.NET

No results

Create a CustomerSession with the Tax ID Element component enabled:

Command Line

Select a language

cURL

Stripe CLI

Ruby

Python

PHP

Java

Node.js

Go

.NET

No results

The CustomerSession returns a client_secret that you’ll pass to the client side.

Create a PaymentIntent or SetupIntent

Create a PaymentIntent or SetupIntent on your server. When using CustomerSession, include the customer reference parameter to enable tax ID save and redisplay functionality:

Command Line

Select a language

cURL

Stripe CLI

Ruby

Python

PHP

Java

Node.js

Go

.NET

No results

Note

You don’t need to include any tax-ID-specific parameters when creating the Payment Intent or Setup Intent. The Tax ID Element automatically handles tax ID collection and saves it to the Customer when using a Customer Session with the appropriate permissions.

Initialize Elements

Create an Elements instance using the clientSecret from your PaymentIntent or SetupIntent.

To enable saving tax IDs to a Customer and redisplaying them for returning customers, include the customerSessionClientSecret:

const stripe = Stripe('pk_test_TYooMQauvdEDq54NiTphI7jx', {
 betas: ['elements_tax_id_1'],
});

// Fetch the clientSecret from your server
const {clientSecret} = await fetch('/create-payment-intent', {
 method: 'POST',
 headers: { 'Content-Type': 'application/json' },
}).then((res) => res.json());

// Fetch the customerSessionClientSecret from your server
const {customerSessionClientSecret} = await fetch('/create-customer-session', {
 method: 'POST',
 headers: { 'Content-Type': 'application/json' },
}).then((res) => res.json());

const elements = stripe.elements({
 clientSecret,
 customerSessionClientSecret,
 appearance: { /* ... */ }
});

Create and mount the Tax ID Element

Create an instance of the Tax ID Element and mount it to your page:

<form id="payment-form">
 <div id="tax-id-element">
 <!--Stripe.js injects the Tax ID Element-->
 </div>
 <button type="submit">Pay</button>
</form>

const taxIdElement = elements.create('taxId', {
 visibility: 'auto', // 'auto' | 'always' | 'never'
});
taxIdElement.mount('#tax-id-element');

You can customize the Tax ID Element with options such as visibility, fields, and validation. See Create a Tax ID Element for more details.

Use with Address Element (optional)

When you use the Tax ID Element with the Address Element, Stripe automatically determines the tax ID type and element visibility based on the customer’s address.

Complete the payment

When the customer submits the payment form, call confirmPayment or confirmSetup. Stripe automatically includes the tax ID information and saves it to the Customer if the payment succeeds:

You can also use getValue on the client side to read the tax ID values before submitting the payment.

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.

Asynchronous Tax ID validation

During payment or setup confirmation, 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.

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.

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.

Real-time tax ID validation Preview

In addition to the asynchronous validation described above, you can enable synchronous, real-time tax ID verification directly in the Tax ID Element. When you enable it, Stripe verifies tax IDs against government databases as your customer types and displays the result inline before they submit the payment. Stripe currently supports real-time verification for Australian Business Numbers (ABNs), European Value Added Tax (EU VAT), and United Kingdom Value Added Tax (GB VAT) numbers. If a government database is unavailable, Stripe falls back to synchronous format validation and performs full verification asynchronously. This feature is in public preview and requires the elements_tax_id_verification_1 beta.

const taxIdElement = elements.create('taxId', {
 ...
 verification: {
 taxId: {
 mode: 'if_supported',
 },
 },
});

When you enable verification, the change event includes the verification.taxId.status field. Its value can be pending, verified, unverified, or unavailable. The element’s complete status reflects the verification result. See Create a Tax ID Element and Tax ID Element on Change for details.

Supported Tax ID types

The Tax ID Element supports tax ID collection in the following countries and regions:

Use tax IDs in calculations (optional)

In some cases, such as the cross-border supply of services, your customer might need to account for tax on a reverse charge basis. Instead of collecting the tax, you must issue an invoice with the text, “Tax to be paid on reverse charge basis.”

When you provide your customer’s tax IDs to Stripe Tax, we automatically determine when reverse charge applies:

Command Line

Select a language

cURL

Stripe CLI

Ruby

Python

PHP

Java

Node.js

Go

.NET

No results

If you provide a tax ID with an invalid format, the calculation returns a tax_id_invalid error code.

See also

• Stripe Tax with PaymentIntents
• Customer tax ID validation
• Reverse charges