tracefinance · diegopereira90 · Apr 29, 2026 · Apr 29, 2026 · Apr 29, 2026
diff --git 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
@@ -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
@@ -5,7 +5,7 @@

 ## Overview

 An account in Trace FX is multi-currency: every account includes crypto support by default, and you declare which fiat assets (like BRL) to enable when you create it. Each fiat asset and the crypto wallet run their own onboarding pipelines.

 ## Prerequisites

@@ -16,7 +16,7 @@

 <Steps>
  <Step title="Create the account">
    Submit a request with the fiat assets to enable and the account owner's details. Crypto support is always included — you don't need to declare it.

    ```bash
    curl --request POST \
@@ -32,9 +32,8 @@
           "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 @@
       --data '{
         "name": "João Silva",
         "taxId": {
-          "value": "12345678909",
           "type": "CPF",
-          "country": "BR"
+          "value": "12345678909"
         },
         "address": {
           "addressLine1": "Rua das Flores, 100",
@@ -96,7 +94,7 @@
    The response includes the UBO's `id`, which you'll need for uploading their documents.
  </Step>
  <Step title="Upload UBO documents">
    Each UBO needs identity documents. Use the same `/api/documents` endpoint — set `holder.type` to `UBO` and `holder.referenceId` to the UBO's `id`. Identity documents typically require a `documentSubType` (e.g., `FRONT_SIDE` / `BACK_SIDE`) and a `metadata.country`:

    ```bash
    curl --request POST \
@@ -122,7 +120,7 @@
    Returns `202 Accepted`. The account transitions from `ACTION_REQUIRED` to `REVIEWING`. If any documents are still missing or rejected, the API returns `422` with a `MISSING_DOCUMENTS_FOR_REVIEW` error listing the outstanding `documentType` names.
  </Step>
  <Step title="Wait for activation">
    After review is approved, each asset activates on its own pipeline. Poll [`GET /api/accounts/{accountId}`](/api-reference/fx-account/accounts/get-account) — the account moves through `OPENING` and becomes `ACTIVE` once the first underlying provider account finishes onboarding (typically the crypto wallet, since it has no manual steps). Each entry in the response's `assets` array carries its own provider-account `status` (`ONBOARDING`, `ACTIVE`, `FAILED`, `FROZEN`, `DEACTIVATED`) so you can see which assets are ready.
  </Step>
  <Step title="Retrieve funding instructions">
    Once the account is active, retrieve the incoming transfer details for each active asset:
@@ -149,5 +147,5 @@

 ## What happens next

 - [Make a deposit](/journeys/deposit) — fund the account with BRL or crypto.
 - [Execute a swap](/journeys/swap) — convert between the account's assets.
diff --git a/journeys/withdrawal.mdx b/journeys/withdrawal.mdx
@@ -5,7 +5,7 @@

 ## Overview

 Withdrawals move funds out of an account to an external destination — a bank account (PIX, TED) or a crypto wallet. Every withdrawal references a quote that locks the FX rate (or a 1:1 spot for same-asset) and a previously approved beneficiary with at least one payment instruction.

 ## Prerequisites

@@ -16,7 +16,7 @@

 <Steps>
  <Step title="Register a beneficiary (one time per destination)">
    Submit the holder details and the payment instruction (PIX, bank account, or crypto wallet). The beneficiary starts in `PENDING_REVIEW` status and transitions asynchronously to `APPROVED` or `REJECTED` after compliance review.

    ```bash
    curl --request POST \
@@ -29,7 +29,7 @@
           "type": "INDIVIDUAL",
           "firstName": "John",
           "lastName": "Doe",
-          "taxId": "12345678901",
+          "taxId": {"type": "CPF", "value": "12345678901"},
           "dateOfBirth": "1990-01-15"
         },
         "paymentInstruction": {