diff --git a/apis/fx-account/openapi.yml b/apis/fx-account/openapi.yml index 410d7b9..8583c96 100644 --- a/apis/fx-account/openapi.yml +++ b/apis/fx-account/openapi.yml @@ -243,20 +243,17 @@ components: - address TaxIdRequest: type: object - description: Tax identifier for the owner or beneficial owner. Validated against the country and type. + description: Tax identifier for the owner or beneficial owner. Validated against the type's country-specific format. properties: + type: + $ref: "#/components/schemas/TaxIdType" value: type: string - description: Tax identifier digits or alphanumeric value (depending on type). + description: Tax identifier digits or alphanumeric characters (depending on type), with no formatting separators. example: "11222333000181" - type: - $ref: "#/components/schemas/TaxIdType" - country: - $ref: "#/components/schemas/Country" required: - - value - type - - country + - value AddressRequest: type: object properties: @@ -548,17 +545,14 @@ components: type: object description: Tax identifier returned for an owner or beneficial owner. properties: + type: + $ref: "#/components/schemas/TaxIdType" value: type: string example: "11222333000181" - type: - $ref: "#/components/schemas/TaxIdType" - country: - $ref: "#/components/schemas/Country" required: - - value - type - - country + - value AddressResponse: type: object properties: @@ -810,9 +804,48 @@ components: example: "BRL" TaxIdType: type: string - description: > - Country-specific tax identifier type. The `country` field on the same - TaxId object must match the country implied by the type. + description: | + Tax identifier type. Each value implies a single issuing country — no separate `country` field is needed on the request. + + **South America** + - Brazil (BR): `CPF` (individual), `CNPJ` (company) + - Argentina (AR): `CUIT`, `CUIL` + - Chile (CL): `RUT_CL` + - Uruguay (UY): `RUT_UY`, `CI_UY` + - Peru (PE): `RUC`, `DNI_PE` + - Colombia (CO): `NIT`, `CC` + - Paraguay (PY): `RUC_PY`, `CI_PY` + + **North America** + - Mexico (MX): `RFC` + - USA (US): `EIN`, `SSN`, `ITIN` + - Canada (CA): `BN_CA`, `SIN` + + **Europe** + - Portugal (PT): `NIPC`, `NIF_PT` + - Spain (ES): `CIF`, `NIF_ES`, `NIE` + - France (FR): `SIREN`, `SIRET`, `NIF_FR` + - Italy (IT): `PARTITA_IVA`, `CODICE_FISCALE` + - Germany (DE): `UST_IDNR`, `STEUER_ID` + - Netherlands (NL): `KVK`, `BSN` + - Belgium (BE): `BCE`, `NN_BE` + - Sweden (SE): `ORGANISATIONSNUMMER`, `PERSONNUMMER` + - Norway (NO): `ORGANISASJONSNUMMER`, `FODSELSNUMMER` + - Switzerland (CH): `UID_CH`, `AHV` + - United Kingdom (GB): `VAT_GB`, `NIN` + + **Asia & Pacific** + - China (CN): `USCC` + - Japan (JP): `CORPORATE_NUMBER_JP`, `MY_NUMBER` + - South Korea (KR): `BRN_KR`, `RRN` + - India (IN): `GSTIN`, `PAN` + - Russia (RU): `INN_RU` + - Australia (AU): `ABN`, `TFN` + + **Middle East & Africa** + - Israel (IL): `COMPANY_NUMBER_IL`, `TEUDAT_ZEHUT` + - UAE (AE): `TRADE_LICENSE`, `EMIRATES_ID` + - South Africa (ZA): `CIPC`, `SA_ID` enum: - CPF - CNPJ @@ -1541,9 +1574,8 @@ paths: type: "COMPANY" legalName: "Acme Ltda" taxId: - value: "11222333000181" type: "CNPJ" - country: "BR" + value: "11222333000181" industry: "INFORMATION_TECHNOLOGY" incorporateDate: "2018-05-12" address: @@ -1564,9 +1596,8 @@ paths: firstName: "Maria" lastName: "Silva" taxId: - value: "12345678909" type: "CPF" - country: "BR" + value: "12345678909" birthDate: "1990-03-21" address: addressLine1: "Rua das Flores, 100" @@ -1589,14 +1620,14 @@ paths: $ref: "#/components/schemas/ErrorResponse" examples: invalidTaxId: - summary: Owner taxId fails the country/type-specific validator + summary: Owner taxId fails the type-specific validator value: code: "INVALID_DATA" message: "Object contains invalid data" details: errors: - code: "VALIDATE_TAX_ID" - message: "Tax ID is invalid for the given type and country" + message: "Tax ID is invalid for the given type" field: "body:owner.taxId.value" params: {} unsupportedAsset: @@ -2042,9 +2073,8 @@ paths: value: name: "João Silva" taxId: - value: "12345678909" type: "CPF" - country: "BR" + value: "12345678909" address: addressLine1: "Rua das Flores, 100" city: "São Paulo" @@ -2067,14 +2097,14 @@ paths: $ref: "#/components/schemas/ErrorResponse" examples: invalidTaxId: - summary: UBO taxId fails the country/type-specific validator + summary: UBO taxId fails the type-specific validator value: code: "INVALID_DATA" message: "Object contains invalid data" details: errors: - code: "VALIDATE_TAX_ID" - message: "Tax ID is invalid for the given type and country" + message: "Tax ID is invalid for the given type" field: "body:taxId.value" params: {} invalidData: @@ -2257,9 +2287,8 @@ paths: value: name: "João Carlos Silva" taxId: - value: "98765432100" type: "CPF" - country: "BR" + value: "98765432100" address: addressLine1: "Av. Paulista, 1000" city: "São Paulo" @@ -2282,14 +2311,14 @@ paths: $ref: "#/components/schemas/ErrorResponse" examples: invalidTaxId: - summary: UBO taxId fails the country/type-specific validator + summary: UBO taxId fails the type-specific validator value: code: "INVALID_DATA" message: "Object contains invalid data" details: errors: - code: "VALIDATE_TAX_ID" - message: "Tax ID is invalid for the given type and country" + message: "Tax ID is invalid for the given type" field: "body:taxId.value" params: {} invalidData: diff --git a/apis/fx-payment/openapi.yml b/apis/fx-payment/openapi.yml index 525b6c5..f08e48b 100644 --- a/apis/fx-payment/openapi.yml +++ b/apis/fx-payment/openapi.yml @@ -287,23 +287,125 @@ components: TaxId: type: object description: > - Tax identifier as a typed value object. The `number` must match the format expected + Tax identifier as a typed value object. The `value` must match the format expected for the supplied `type` (e.g. a `CPF` must be 11 digits with valid check digits, a - `CNPJ` must be 14 digits with valid check digits). + `CNPJ` must be 14 digits with valid check digits). Some types are alphanumeric + (e.g. `RFC`, `ABN`, `VAT_GB`). properties: type: + $ref: "#/components/schemas/TaxIdType" + value: type: string - description: > - Tax identifier kind. Brazilian beneficiaries use `CPF` (individual) or `CNPJ` - (company); other jurisdictions use the local code (e.g. `SSN`, `EIN`, `CUIT`). - example: "CPF" - number: - type: string - description: Tax identifier number, digits only (no dots, dashes, or slashes). + description: Tax identifier digits or alphanumeric characters (depending on type), with no formatting separators. example: "52998224725" required: - type - - number + - value + TaxIdType: + type: string + description: | + Tax identifier type. Each value implies a single issuing country — no separate `country` field is needed on the request. + + **South America** + - Brazil (BR): `CPF` (individual), `CNPJ` (company) + - Argentina (AR): `CUIT`, `CUIL` + - Chile (CL): `RUT_CL` + - Uruguay (UY): `RUT_UY`, `CI_UY` + - Peru (PE): `RUC`, `DNI_PE` + - Colombia (CO): `NIT`, `CC` + - Paraguay (PY): `RUC_PY`, `CI_PY` + + **North America** + - Mexico (MX): `RFC` + - USA (US): `EIN`, `SSN`, `ITIN` + - Canada (CA): `BN_CA`, `SIN` + + **Europe** + - Portugal (PT): `NIPC`, `NIF_PT` + - Spain (ES): `CIF`, `NIF_ES`, `NIE` + - France (FR): `SIREN`, `SIRET`, `NIF_FR` + - Italy (IT): `PARTITA_IVA`, `CODICE_FISCALE` + - Germany (DE): `UST_IDNR`, `STEUER_ID` + - Netherlands (NL): `KVK`, `BSN` + - Belgium (BE): `BCE`, `NN_BE` + - Sweden (SE): `ORGANISATIONSNUMMER`, `PERSONNUMMER` + - Norway (NO): `ORGANISASJONSNUMMER`, `FODSELSNUMMER` + - Switzerland (CH): `UID_CH`, `AHV` + - United Kingdom (GB): `VAT_GB`, `NIN` + + **Asia & Pacific** + - China (CN): `USCC` + - Japan (JP): `CORPORATE_NUMBER_JP`, `MY_NUMBER` + - South Korea (KR): `BRN_KR`, `RRN` + - India (IN): `GSTIN`, `PAN` + - Russia (RU): `INN_RU` + - Australia (AU): `ABN`, `TFN` + + **Middle East & Africa** + - Israel (IL): `COMPANY_NUMBER_IL`, `TEUDAT_ZEHUT` + - UAE (AE): `TRADE_LICENSE`, `EMIRATES_ID` + - South Africa (ZA): `CIPC`, `SA_ID` + enum: + - CPF + - CNPJ + - CUIT + - CUIL + - RUT_CL + - RUT_UY + - CI_UY + - RUC + - DNI_PE + - NIT + - CC + - RFC + - RUC_PY + - CI_PY + - NIPC + - NIF_PT + - CIF + - NIF_ES + - NIE + - SIREN + - SIRET + - NIF_FR + - PARTITA_IVA + - CODICE_FISCALE + - UST_IDNR + - STEUER_ID + - KVK + - BSN + - BCE + - NN_BE + - ORGANISATIONSNUMMER + - PERSONNUMMER + - ORGANISASJONSNUMMER + - FODSELSNUMMER + - UID_CH + - AHV + - VAT_GB + - NIN + - EIN + - SSN + - ITIN + - BN_CA + - SIN + - ABN + - TFN + - USCC + - CORPORATE_NUMBER_JP + - MY_NUMBER + - BRN_KR + - RRN + - GSTIN + - PAN + - INN_RU + - COMPANY_NUMBER_IL + - TEUDAT_ZEHUT + - TRADE_LICENSE + - EMIRATES_ID + - CIPC + - SA_ID + example: "CPF" Country: type: string description: ISO 3166-1 alpha-2 country code. @@ -2116,7 +2218,7 @@ paths: lastName: "Doe" taxId: type: "CPF" - number: "52998224725" + value: "52998224725" dateOfBirth: "1990-01-15" address: addressLine1: "Rua Augusta, 500" @@ -2881,7 +2983,7 @@ paths: lastName: "Silva" taxId: type: "CPF" - number: "52998224725" + value: "52998224725" dateOfBirth: "1985-03-15" address: addressLine1: "Av. Paulista, 1000" @@ -2905,7 +3007,7 @@ paths: tradeName: "Acme" taxId: type: "CNPJ" - number: "27922482000193" + value: "27922482000193" address: addressLine1: "Rua da Consolação, 222" city: "São Paulo" @@ -2928,7 +3030,7 @@ paths: lastName: "Doe" taxId: type: "CPF" - number: "11144477735" + value: "11144477735" dateOfBirth: "1990-07-22" address: addressLine1: "123 Main St" diff --git a/journeys/open-multi-currency-account.mdx b/journeys/open-multi-currency-account.mdx index e0b8516..018c3b0 100644 --- a/journeys/open-multi-currency-account.mdx +++ b/journeys/open-multi-currency-account.mdx @@ -32,9 +32,8 @@ An account in Trace FX is multi-currency: every account includes crypto support "type": "COMPANY", "legalName": "Acme Ltda", "taxId": { - "value": "11222333000181", "type": "CNPJ", - "country": "BR" + "value": "11222333000181" }, "industry": "INFORMATION_TECHNOLOGY", "incorporateDate": "2018-05-12", @@ -78,9 +77,8 @@ An account in Trace FX is multi-currency: every account includes crypto support --data '{ "name": "João Silva", "taxId": { - "value": "12345678909", "type": "CPF", - "country": "BR" + "value": "12345678909" }, "address": { "addressLine1": "Rua das Flores, 100", diff --git a/journeys/withdrawal.mdx b/journeys/withdrawal.mdx index 80491e6..10b4c41 100644 --- a/journeys/withdrawal.mdx +++ b/journeys/withdrawal.mdx @@ -29,7 +29,7 @@ Withdrawals move funds out of an account to an external destination — a bank a "type": "INDIVIDUAL", "firstName": "John", "lastName": "Doe", - "taxId": "12345678901", + "taxId": {"type": "CPF", "value": "12345678901"}, "dateOfBirth": "1990-01-15" }, "paymentInstruction": {