/customers/{customer_id}/tax_idsCreate
Create a tax ID attached to a customer (Stripe parity).
Body — 1:1 with CreateTaxIDDTO (app/handlers/v1/tax_id/request.go).
| Field | Required | Notes |
|---|---|---|
type | ✓ | One of the 111 tax-id type codes — see list below or fetch live via GET /tax_id_types |
value | ✓ | Tax ID number — format-checked, see below |
country | ✓ | ISO 3166-1 alpha-2 |
metadata | optional | Free-form key/value |
verification_status defaults to pending. Stripe webhooks update it later — there is no PATCH endpoint (immutable per Stripe parity).
Value validation
value is matched against the catalogue row for (country, type) before anything is created:
- unknown
type→ 400E1101withdetails.tax_id_type valuethat does not match the type's pattern → 400E1101withdetails.tax_id_type, plusdetails.expected_format(the type's placeholder) when the type has one- types that ship no pattern —
us_ein,hk_br,jp_trn,ru_inn,ru_kpp, and the genericeu_vat— accept any value eu_vatis checked against the pattern of the member state you send incountry, soDErequiresDE[0-9]{9}
Only the outer whitespace of value is trimmed — inner spaces and dashes are significant (CHE-123.456.789 HR, 123456789RT0002). If the catalogue cannot be reached the check fails open and the tax ID is created unvalidated.
Supported type values (111 total)
North America — us_ein · ca_bn · ca_gst_hst · ca_pst_bc · ca_pst_mb · ca_pst_sk · ca_qst · mx_rfc
EU / UK / EFTA — eu_vat · eu_oss_vat · gb_vat · xi_vat · de_stn · es_cif · hr_oib · hu_tin · ro_tin · si_tin · bg_uic · ch_vat · ch_uid · li_uid · li_vat · no_vat · no_voec · is_vat · ad_nrt
Asia-Pacific — jp_cn · jp_rn · jp_trn · cn_tin · hk_br · tw_vat · kr_brn · sg_gst · sg_uen · my_itn · my_sst · my_frp · id_npwp · ph_tin · vn_tin · th_vat · kh_tin · la_tin · np_pan · bd_bin · in_gst · au_abn · au_arn · nz_gst
Middle East — ae_trn · sa_vat · om_vat · bh_vat · il_vat · tr_tin
Africa — eg_tin · za_vat · ng_tin · ke_pin · tz_vat · ug_tin · zm_tin · zw_tin · ma_vat · et_tin · cm_niu · ao_tin · bf_ifu · bj_ifu · cd_nif · cv_nif · gn_nif · mr_nif · sn_ninea
Latin America & Caribbean — br_cnpj · br_cpf · ar_cuit · cl_tin · co_nit · pe_ruc · uy_ruc · ec_ruc · bo_tin · ve_rif · cr_tin · do_rcn · sv_nit · sr_fin · aw_tin · bb_tin · bs_tin
Eurasia / Caucasus / Balkans — am_tin · az_tin · ba_tin · by_tin · ge_vat · kg_tin · kz_bin · md_vat · me_pib · mk_vat · rs_pib · ru_inn · ru_kpp · tj_tin · ua_vat · uz_tin · uz_vat · al_tin
eu_vat is one code with 28 catalogue rows — 27 member states plus a generic EU row — so the catalogue has 138 rows for these 111 codes.
Source of truth: backend/gateway/resources/tax_ids.json, generated by scripts/build_tax_ids_resource.py (mirrors Stripe API — Customer Tax IDs).
Request
Example
curl -X POST 'https://api.paycose.com/api/v1/app1/platform/wallet/customers/{{customer_id}}/tax_ids/' \
-H 'X-Session-Token: {{session_token}}' \
-H 'X-Country: {{country}}' \
-H 'X-Test-Mode: {{x_test_mode}}' \
-d '{
"type": "th_vat",
"value": "1509966278552",
"country": "TH",
"metadata": {},
"labels": [
"<string>"
]
}'Headers
| Name | Value | Description |
|---|---|---|
| X-Session-Token | {{session_token}} | |
| X-Country | {{country}} | |
| X-Test-Mode | {{x_test_mode}} | true=wallet_test, false=wallet_live (default). Toggle the x_test_mode collection variable to flip every applicable request. |
Body
| Name | Type | Value |
|---|---|---|
| type | string | th_vat |
| value | string | 1509966278552 |
| country | string | TH |
| metadata | object | {…} |
| labels | array | [1] |
{
"type": "th_vat",
"value": "1509966278552",
"country": "TH",
"metadata": {},
"labels": [
"<string>"
]
}Responses
Headers
| Name | Value |
|---|---|
| Content-Type | application/json |
Body
{
"id": "<string>",
"object": "<string>",
"resource": "<string>",
"created_at": "<RFC3339 timestamp>",
"errors": [
{
"code": "<string>",
"message": "<string>"
}
],
"next_action": [
{
"type": "<string>",
"title": "<string>",
"description": "<string>",
"i18n_key": "<string>",
"url": "<string>",
"client_secret": "<string>",
"payment_method": "<string>",
"qr_data": "<string>"
}
]
}Headers
| Name | Value |
|---|---|
| Content-Type | application/json |
Body
{
"object": "error",
"code": "<string>",
"key": "<string>",
"i18n_key": "<string>",
"message": "<string>",
"request_id": "<string>"
}