Collect Customer Tax IDs with 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. This guide assumes that you’ve already integrated Checkout. If you haven’t, see the guide.
Supported Tax ID types
Checkout collects the following tax ID types in the given regions:
国家/地区 | 枚举 | 描述 | 示例 |
---|---|---|---|
丹麦 | eu_vat | European VAT number | DK12345678 |
俄罗斯 | ru_inn | 俄罗斯企业编码 (INN) | 1234567891 |
俄罗斯 | ru_kpp | 俄罗斯工业企业编码 (KPP) | 123456789 |
保加利亚 | eu_vat | European VAT number | BG0123456789 |
克罗地亚 | eu_vat | European VAT number | HR12345678912 |
冰岛 | is_vat | 冰岛增值税 (VAT) | 123456 |
加拿大 | ca_bn | 加拿大商业号码 (BN) | 123456789 |
加拿大 | ca_gst_hst | 加拿大商品及服务税/统一销售税税号 (GST/HST) | 123456789RT0002 |
加拿大 | ca_pst_bc | 加拿大省销售税税号 (PST)(不列颠哥伦比亚) | PST-1234-5678 |
加拿大 | ca_pst_mb | 加拿大省销售税税号 (PST)(马尼托巴湖) | 123456-7 |
加拿大 | ca_pst_sk | 加拿大省销售税税号 (PST)(萨斯喀彻温省) | 1234567 |
加拿大 | ca_qst | 加拿大魁北克销售税 (QST)(魁北克) | 1234567890TQ1234 |
匈牙利 | eu_vat | European VAT number | HU12345678 |
南非 | za_vat | 南非增值税号 (VAT) | 4123456789 |
卢森堡 | eu_vat | European VAT number | LU12345678 |
印度 | in_gst | 印度商品及服务税税号 (GST) | 12ABCDE3456FGZH |
哈萨克斯坦 | kz_bin | 哈萨克斯坦商家识别码 | 123456789012 |
土耳其 | tr_tin | 土耳其税务识别号 | 0123456789 |
埃及 | eg_tin | 埃及税务识别号 | 123456789 |
塞浦路斯 | eu_vat | European VAT number | CY12345678Z |
奥地利 | eu_vat | European VAT number | ATU12345678 |
尼日利亚 | ng_tin | 尼日利亚纳税人识别码 | 12345678-0001 |
巴林 | bh_vat | 巴林增值税号 | 123456789012345 |
希腊 | eu_vat | European VAT number | EL123456789 |
德国 | eu_vat | European VAT number | DE123456789 |
意大利 | eu_vat | European VAT number | IT12345678912 |
拉脱维亚 | eu_vat | European VAT number | LV12345678912 |
挪威 | no_vat | 挪威增值税号 (VAT) | 123456789MVA |
捷克 | eu_vat | European VAT number | CZ1234567890 |
斯洛伐克 | eu_vat | European VAT number | SK1234567891 |
斯洛文尼亚 | eu_vat | European VAT number | SI12345678 |
新加坡 | sg_gst | 新加坡商品及服务税税号 (GST) | M12345678X |
新西兰 | nz_gst | 新西兰商品及服务税税号 (GST) | 123456789 |
智利 | cl_tin | 智利纳税人识别号 (TIN) | 12.345.678-K |
格鲁吉亚 | ge_vat | 格鲁吉亚增值税税号 (VAT) | 123456789 |
比利时 | eu_vat | European VAT number | BE0123456789 |
沙特阿拉伯 | sa_vat | 沙特阿拉伯增值税税号 (VAT) | 123456789012345 |
法国 | eu_vat | European VAT number | FRAB123456789 |
波兰 | eu_vat | European VAT number | PL1234567890 |
泰国 | th_vat | 泰国增值税税号 (VAT) | 1234567891234 |
澳大利亚 | au_abn | 澳大利亚商业号码 (AU ABN) | 12345678912 |
爱尔兰 | eu_vat | European VAT number | IE1234567AB |
爱沙尼亚 | eu_vat | European VAT number | EE123456789 |
瑞典 | eu_vat | European VAT number | SE123456789123 |
瑞士 | ch_vat | 瑞士增值税号 (VAT) | CHE-123.456.789 MWST |
立陶宛 | eu_vat | European VAT number | LT123456789123 |
罗马尼亚 | eu_vat | European VAT number | RO1234567891 |
肯尼亚 | ke_pin | 肯尼亚税务局个人识别号码 | P000111111A |
芬兰 | eu_vat | European VAT number | FI12345678 |
英国 | eu_vat | Northern Ireland VAT number | XI123456789 |
英国 | gb_vat | 英国增值税号 (VAT) | GB123456789 |
荷兰 | eu_vat | European VAT number | NL123456789B12 |
葡萄牙 | eu_vat | European VAT number | PT123456789 |
西班牙 | es_cif | 西班牙 NIF 编号(之前为西班牙 CIF 编号) | A12345678 |
西班牙 | eu_vat | European VAT number | ESA1234567Z |
阿曼 | om_vat | 阿曼增值税号 | OM1234567890 |
阿联酋 | ae_trn | 阿联酋税务登记号码 (TRN) | 123456789012345 |
韩国 | kr_brn | 韩国商业登记号码 (BRN) | 123-45-67890 |
马尔他 | eu_vat | European VAT number | MT12345678 |
墨西哥 | mx_rfc | 墨西哥纳税登记号 (RFC) | ABC010203AB9 |
Enable Tax ID collection
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 shows a checkbox allowing the customer to indicate that they’re purchasing as a business. When a customer checks the box, Checkout displays fields for them to enter their business’s tax ID and their business’s legal entity name. If available, Checkout uses the customer’s shipping address to determine their location, otherwise Checkout uses the customer’s 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.
备注
The above code example creates a Session in payment
mode with tax ID collection enabled. To enable tax ID collection in subscription
mode you would make the same changes highlighted in green to your subscription
mode Session creation request.
You can additionally configure Checkout to create a new Customer for you using customer_creation. If you do, Checkout saves any tax ID information collected during a Session to that new Customer. If not, the tax ID information will still be available at customer_details.tax_ids.
Existing Customers
If you pass an existing Customer when creating a Session, Checkout updates the Customer with any tax ID information collected during the Session. Checkout saves the collected business name onto the Customer’s name property, and adds the collected tax ID to the Customer’s customer.tax_ids array. Since the collection of a business name could result in the Customer’s existing name being overridden, you must set customer_update[name]
to auto
when creating the Session.
注意
Checkout only collects tax IDs on Customer’s that don’t already have an existing tax ID. If a Customer has one or more tax IDs saved, Checkout does not display the tax ID collection form even if tax ID collection is enabled.
When collecting tax IDs for existing customers you can choose to either base their location on existing addresses on the customer or the addresses entered during checkout. By default, Checkout looks for existing addresses on the customer to assess their location:
If you don’t have the addresses of your existing customers saved, you can choose to base their location on the billing or shipping address entered during Checkout. To specify that you want to use the billing address entered during Checkout to assess the customer’s location, you must set customer_update[address]
to auto
.
备注
When setting customer_update[address]
to auto
Checkout replaces any previously saved addresses on the customer with the address entered during the session.
If you’re collecting shipping addresses for existing customers, you must base their location on the shipping address entered during checkout. To do so, set customer_update[shipping]
to auto
.
备注
When setting customer_update[shipping]
to auto
Checkout replaces any previously saved shipping addresses on the customer with the shipping address entered during the session.
备注
The above code examples create Sessions in payment
mode with tax ID collection enabled. To enable tax ID collection in subscription
mode you would make the same changes highlighted in green to your subscription
mode Session creation request.
Retrieving 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 wish 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": "cus_id_of_new_customer", "customer_details": { ... "tax_ids": [ {
Checkout also saves collected tax IDs and business names to the Customer object if one is associated with the Session. A tax ID collected during checkout is accessible under the Customer’s customer.tax_ids array. You can also retrieve all tax IDs saved to a Customer with the Tax IDs resource by specifying the owner[type]
parameter to customer
and owner[customer]
to the Customer’s ID. Every new tax ID includes an associated legal business name, which Checkout saves to the Customer’s name property. In doing so, the collected legal business name is always visible on any subscription invoices for that Customer.
Testing your integration
In test mode you can enter any alphanumeric string that is in the correct format of a supported tax ID type (for example, DE123456789
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: test business tax IDs.
Validation
Checkout performs checks during the Session to ensure that provided tax IDs are formatted correctly. We don’t verify that provided tax IDs are valid during the Session. You’re responsible for ensuring the validity of customer information collected during Checkout. To help, Stripe automatically performs asynchronous validation against government databases for Australian Business (ABN) numbers, European Value-Added-Tax (EU VAT) numbers, and United Kingdom Value-Added-Tax (GB VAT) numbers. You can read more on the validation we perform, and how to consume the status of those checks in our Customer Tax ID guide.