Summary
The Entity object now supports a dedicatedtax_id_type field alongside the existing tax_id. Previously, an entity’s tax identifier could be captured, but its kind was not modelled as a first-class field. tax_id_type makes the identifier explicit and lets Tazapay validate the value against the entity’s registration country and type.
As part of this change, tax_id has been removed as an option from the type enum of the entity’s national_identification_number object. Tax identifiers are now represented exclusively through the entity-level tax_id and tax_id_type fields.
What Changed
New tax_id_type field
tax_id_type is an optional string enum. When tax_id is supplied, tax_id_type is required (and vice versa). Accepted values:
The declared
tax_id_type must be consistent with the entity’s registration country and type — for example, a US-specific type such as ein cannot be declared for a non-US entity. For countries without a dedicated type, use others.
tax_id removed from national_identification_number.type
The tax_id value is no longer accepted in the type enum of the national_identification_number object. Use the entity-level tax_id and tax_id_type fields instead.
Affected Endpoints
POST /v3/entity— Create EntityPUT /v3/entity/{id}— Update EntityPOST /v3/entity/{id}/submit— Submit EntityGET /v3/entity/{id}— Fetch Entity (response now includestax_id_type)GET /v3/entity— List Entities (response now includestax_id_type)- Entity webhooks — the entity
datapayload now includestax_idandtax_id_type.
Compatibility
This is a backward-compatible enhancement.tax_id and tax_id_type are optional; existing integrations that do not send them are unaffected. Integrations that previously sent tax_id as a national_identification_number.type should migrate to the entity-level tax_id / tax_id_type fields.