docs(guides): tighten KYC/KYB scope, fix doc list, add beneficiary review

docs.json

@@ -47,7 +47,8 @@
               "quickstart",
               "guides/authentication",
               "guides/environments",
-              "guides/kyc-kyb"
+              "guides/kyc-kyb",
+              "guides/beneficiary-compliance-review"
             ]
           },
           {

guides/beneficiary-compliance-review.mdx

@@ -0,0 +1,66 @@
+---
+title: "Beneficiary compliance review"
+description: "How Trace FX reviews the parties a marketplace pays out to, and what the marketplace must still do on its side."
+---
+
+## Overview
+
+Beneficiaries are the end-users your platform pays out to. They are not Trace's direct customers — you are — but Trace's banking and crypto rails are what move funds on their behalf, so each beneficiary goes through a compliance review tuned to the rail used.
+
+This review is **separate** from KYC/KYB — KYC/KYB applies to your account ownership and your UBOs (see [KYC and KYB requirements](/guides/kyc-kyb)). The beneficiary review described here happens at instruction creation, not at account onboarding.
+
+## What you submit per beneficiary
+
+Submitted on [`POST /api/beneficiaries`](/api-reference/fx-payment/beneficiaries/create-beneficiary):
+
+| Field | Format | Notes |
+| --- | --- | --- |
+| `holder.type` | enum | `INDIVIDUAL` or `COMPANY`. |
+| `holder.firstName` / `lastName` | string | Required when `type = INDIVIDUAL`. |
+| `holder.legalName` | string | Required when `type = COMPANY`. |
+| `holder.tradeName` | string | Optional. |
+| `holder.taxId.value` / `taxId.type` | string / enum | CPF/CNPJ for Brazilian beneficiaries; foreign tax ID otherwise. |
+| `holder.dateOfBirth` | `yyyy-MM-dd` | Required when `type = INDIVIDUAL`. |
+| `holder.address` | object | Residential or registered address. |
+| `relationshipType` | enum | `SELF_OWNED` or `THIRD_PARTY`. |
+| `paymentInstruction` | object | Rail-specific (PIX dict key, crypto wallet, etc.). |
+
+The data shape is identity-equivalent to a KYC submission, but documents and UBO chains are not currently accepted on beneficiary submissions.
+
+## What Trace reviews
+
+When a payment instruction is created, Trace runs an automated review tuned to the rail. The exact check set is:
+
+- **Identity screening** on `holder.taxId`, `holder.firstName + lastName` (or `legalName`), and `holder.address.country` against sanctions and PEP lists.
+- **Payment-instrument verification** matched to the rail:
+  - **PIX** — the dict key must resolve in the PIX directory before the instruction is accepted as approved.
+  - **Crypto** — the wallet address is recorded; deeper screening described below.
+
+The instruction transitions from `PENDING_REVIEW` to either `APPROVED` or `REJECTED` once the review completes. Subscribe to the `BENEFICIARY_PAYMENT_INSTRUCTION_APPROVED` and `BENEFICIARY_PAYMENT_INSTRUCTION_REJECTED` webhooks to track the outcome (see the [withdrawal journey](/journeys/withdrawal) for the full flow).
+
+## What the marketplace still owns
+
+The beneficiary review at Trace does not relieve you of your own KYC obligations on your end-users. Specifically, you are expected to:
+
+- Verify the identity of every end-user before they receive payouts through Trace.
+- Maintain your own KYC files (identity documents, address proof, source-of-funds where applicable) in line with the regulators that apply to your business.
+- Ensure the data submitted to Trace per beneficiary is accurate and up to date.
+- Apply your own internal limits and risk-tiers; Trace's review is the rail-side gate, not a substitute for your platform's customer-due-diligence program.
+
+If your business operates under a regulated regime that requires Trace to participate in the customer review (for example, certain BaaS arrangements), reach out to Trace's compliance team — those arrangements are negotiated separately.
+
+## Statuses you will observe
+
+A payment instruction goes through:
+
+- `PENDING_REVIEW` — submitted, awaiting Trace's automated checks.
+- `APPROVED` — checks passed; usable for withdrawals.
+- `REJECTED` — checks failed; not usable. The webhook payload includes a `currentState.reason` describing why.
+
+`PENDING_REVIEW` typically resolves within seconds. Withdrawals can only reference `APPROVED` instructions.
+
+## Related
+
+- [KYC and KYB requirements](/guides/kyc-kyb) — owner-side review, separate from this one.
+- [Withdraw](/journeys/withdrawal) — end-to-end payout flow, including the review's place in the lifecycle.
+- [Webhooks](/api-reference/fx-webhook) — `BENEFICIARY_PAYMENT_INSTRUCTION_*` events.

guides/kyc-kyb.mdx

@@ -10,13 +10,15 @@
 - **KYB (Know Your Business)** applies to company-owned accounts (`owner.type = COMPANY`).
 - **KYC (Know Your Customer)** applies to individually-owned accounts (`owner.type = INDIVIDUAL`) and to every beneficial owner (UBO) registered on a company-owned account.
 
-Information is submitted as structured fields on [`POST /api/accounts`](/api-reference/fx-account/accounts/create-account); supporting documents are uploaded against [`POST /api/documents`](/api-reference/fx-account/documents/upload-document) once the account exists. The exact document list varies per segment and per banking partner — the response from account creation returns the full `requirements.currentlyDue` list for your case.
+KYC and KYB obligations apply to the **account owner** (your direct customer of Trace) and the UBOs that ultimately control a company customer. End-user beneficiaries — the parties a marketplace pays out to — go through a separate, rail-tuned compliance review described in [Beneficiary compliance review](/guides/beneficiary-compliance-review).
+
+Information is submitted as structured fields on [`POST /api/accounts`](/api-reference/fx-account/accounts/create-account); supporting documents are uploaded against [`POST /api/documents`](/api-reference/fx-account/documents/upload-document) once the account exists. The exact document list varies per segment and per banking partner — the response from account creation returns `requirements.currentlyDue` (open) along with `pendingVerification`, `errors`, and `satisfied` for in-flight tracking.
 
 ## Details
 
 ### Business
 
 Business onboarding covers companies that operate under one of the supported segments: standard companies (startups and PJs), payment service providers, crypto businesses, non-resident entities, funds, and exchange operators.
 
 #### Common information for all business segments
 
@@ -38,50 +40,51 @@
 | `name` | string | Full legal name. |
 | `taxId.value` / `taxId.type` | string / enum | CPF for Brazilian residents; foreign tax ID for non-residents. |
 | `address` | object | Residential address. |
+| `phone` | string | Required. Mobile or contact number. |
+| `email` | string | Required. |
 | `ownershipPercentage` | number | Optional. Percentage of ownership. |
+| `isLegalRepresentative` | boolean | Optional, defaults to `false`. `true` if the UBO can sign on behalf of the company. |
 
 #### Common documents for all business segments
 
-These documents are required for every business segment:
+These documents are required for every business segment. Each bullet shows the canonical `documentType` value for [`POST /api/documents`](/api-reference/fx-account/documents/upload-document):
 
-- Articles of association, bylaws, or board-election minutes — registered and issued by the commercial registry (Junta Comercial in Brazil).
-- Articles of association of any corporate shareholder (PJ partner), if applicable.
-- Dated and signed organizational chart, if the corporate structure has multiple layers.
-- Annual revenue declaration, income statement (DRE), or balance sheet — signed by the accountant and the legal representative.
+- Articles of association or bylaws — registered and issued by the commercial registry (Junta Comercial in Brazil) — `ARTICLES_OF_ASSOCIATION`.
+- Board-election minutes or equivalent proof of who can sign on behalf of the company — `SIGNING_AUTHORITY_PROOF`.
+- Articles of association and financial statements of any corporate shareholder (PJ partner), if applicable — `PJ_PARTNER_DOCUMENTS` and `PJ_PARTNER_FINANCIAL_STATEMENT`.
+- Dated and signed organizational chart, if the corporate structure has multiple layers — `ORGANIZATIONAL_CHART`.
+- Annual revenue declaration, income statement (DRE), or balance sheet — signed by the accountant and the legal representative — `FINANCIAL_STATEMENT`.
 
 For each beneficial owner:
 
-- Government-issued photo ID (RG, CNH, passport, RNM, or MRE) and tax ID (CPF for Brazilian residents).
-- Email address and phone number.
-- Proof of residence issued within the last 90 days (required by most partner banks).
+- Government-issued photo ID — RG (`ID_CARD`), CNH (`DRIVER_LICENSE`), passport (`PASSPORT`), or RNM (`RESIDENCE_PERMIT`).
+- Proof of residence issued within the last 90 days, accepted as `PROOF_OF_ADDRESS` (required by most partner banks).
 
 #### Extra documents for payment service providers (PSPs)
 
 PSPs (also referred to as "facilitadoras") aggregate or facilitate payments on behalf of merchants. In addition to the common business documents, partner banks require:
 
-- AML/CTF policies, manuals, and registration forms.
-- A signed KYC form completed by the commercial officer.
-- A signed BaaS adhesion form, where applicable.
-- Operational details: number of employees, company website, and annual revenue.
-- A merchants record sheet listing the PSP's clients.
-- A PLD/FT (anti-money-laundering) policy in its current version.
-- A CDD (customer due diligence) questionnaire signed by the compliance officer.
-- Power of attorney and identity documents for any signatories acting on the company's behalf.
+- AML/CTF (PLD/FT) policies and manuals — `AML_POLICY`.
+- A signed KYC form completed by the commercial officer — `KYC_FORM`. Operational details (number of employees, company website, annual revenue) are captured as part of this form today.
+- A signed BaaS adhesion form, where applicable — `BAAS_ADHESION_FORM`.
+- A merchants record sheet listing the PSP's clients — `OTHER` with descriptive `metadata`.
+- A CDD (customer due diligence) questionnaire signed by the compliance officer — `OTHER` with descriptive `metadata`.
+- Power of attorney for any signatories acting on the company's behalf — `POWER_OF_ATTORNEY`. Identity documents for those signatories follow the format described under "For each beneficial owner".
 
 #### Extra documents for crypto businesses
 
 Crypto businesses submit the standard business package plus:
 
-- A signed KYC form completed by the commercial officer.
-- A signed BaaS adhesion form.
-- A crypto exposure questionnaire (CEQ).
-- Information on the exchanges and platforms used to operate.
-- Evidence of source of funds.
-- A description of the target audience, fundraising strategy, and marketing approach (for funds operating in crypto).
+- A signed KYC form completed by the commercial officer — `KYC_FORM`.
+- A signed BaaS adhesion form — `BAAS_ADHESION_FORM`.
+- A crypto exposure questionnaire (CEQ) — `OTHER` with descriptive `metadata`.
+- Information on the exchanges and platforms used to operate — `OTHER` with descriptive `metadata`.
+- Evidence of source of funds — `EVIDENCE_OF_SOURCE_OF_FUNDS`.
+- A description of the target audience, fundraising strategy, and marketing approach (for funds operating in crypto) — `PROOF_OF_BUSINESS_ACTIVITY`.
 
 #### Extra documents for non-residents (CNR)
 
 Non-resident entities (companies incorporated outside Brazil opening a CNR account) submit constitutional documents matching their legal form, all duly apostilled:
 
 | Legal form | Required constitutional documents |
 | --- | --- |
@@ -92,14 +95,13 @@
 
 In addition:
 
-- Financial statements signed by the accountant and the legal representative.
-- Corporate organizational chart identifying ultimate beneficial owners.
-- AML/CTF policies.
-- Operating licenses, where the entity handles third-party funds.
-- Pre-approval from compliance: license, main merchants, and operational flow.
-- KYC form, due diligence form, and account-opening forms specific to the partner bank.
-- Power of attorney granting authority to a Brazilian legal representative, when the foreign representative does not hold a CPF.
-- Wolfsberg questionnaire, when the entity is a financial institution.
+- Financial statements signed by the accountant and the legal representative — `FINANCIAL_STATEMENT`.
+- Corporate organizational chart identifying ultimate beneficial owners — `ORGANIZATIONAL_CHART`.
+- AML/CTF policies — `AML_POLICY`.
+- Operating licenses, where the entity handles third-party funds — `PROOF_OF_REGULATORY_LICENSE`.
+- KYC form (`KYC_FORM`); due diligence form and account-opening forms specific to the partner bank — `OTHER` with descriptive `metadata`.
+- Power of attorney granting authority to a Brazilian legal representative, when the foreign representative does not hold a CPF — `POWER_OF_ATTORNEY`.
+- Wolfsberg questionnaire, when the entity is a financial institution — `WOLFSBERG_QUESTIONNAIRE`.
 
 ### Individuals
 
@@ -120,18 +122,18 @@
 
 #### Common documents for individuals
 
-- Government-issued photo ID — RG, CNH, passport, RNM, or MRE. Some partner banks require the document to have been issued within the last 10 years.
-- Proof of residence issued within the last 90 days.
-- Email address and phone number.
-- Marital status, and the spouse's full name and CPF when married.
-- Tax identification number (NIF or equivalent) in the country of fiscal residence, for non-Brazilian residents.
-- Proof of income — most recent income tax return, the last three pay stubs, or equivalent evidence.
-- Profession, employer name, monthly income, and net worth, where the partner bank requires it.
-- A FATCA form for individuals classified as foreign or with fiscal residence abroad.
+- Government-issued photo ID — RG (`ID_CARD`), CNH (`DRIVER_LICENSE`), passport (`PASSPORT`), or RNM (`RESIDENCE_PERMIT`). Some partner banks require the document to have been issued within the last 10 years.
+- Proof of residence issued within the last 90 days — `PROOF_OF_ADDRESS`.
+- Email address and phone number — collected via the authentication profile, not on the create-account body.
+- Marital status, and the spouse's full name and CPF when married — collected via partner-bank-specific forms.
+- Tax identification number (NIF or equivalent) in the country of fiscal residence, for non-Brazilian residents — collected via partner-bank-specific forms.
+- Proof of income — most recent income tax return, the last three pay stubs, or equivalent evidence — `EVIDENCE_OF_SOURCE_OF_WEALTH`.
+- Profession, employer name, monthly income, and net worth, where the partner bank requires it — collected via partner-bank-specific forms.
+- A FATCA form for individuals classified as foreign or with fiscal residence abroad — `OTHER` with descriptive `metadata`.
 
 ## Related
 
 - [Open multi-currency account](/journeys/open-multi-currency-account) — end-to-end flow that submits owner details, uploads documents, and registers UBOs.
 - [Create an account](/api-reference/fx-account/accounts/create-account) — request schema for company and individual owners.
 - [Upload a document](/api-reference/fx-account/documents/upload-document) — endpoint used to submit each required document.
 - [Add a UBO](/api-reference/fx-account/beneficial-owners/add-ubo) — register a beneficial owner for a company-owned account.