> ## Documentation Index > Fetch the complete documentation index at: https://docs.tracefinance.com/llms.txt > Use this file to discover all available pages before exploring further. # Create a beneficiary > Registers a new beneficiary for withdrawals. ## OpenAPI ````yaml apis/fx-payment/openapi.yml POST /v1/beneficiaries openapi: 3.1.1 info: title: Trace Finance Payments API version: 1.0.0 description: > API for deposits, withdrawals, swaps, and beneficiary management on the Trace Finance platform. servers: - url: https://api.sandbox.tracefinance.com description: Sandbox security: - bearerAuth: [] tags: - name: Operations description: >- Create deposits, withdrawals, and swaps. Query operation status and history. - name: Reports description: Generate aggregated views of operations across a time window. - name: Beneficiaries description: >- Manage external beneficiaries and their payment instructions for withdrawals. - name: Payment instructions description: Add or remove payment instructions on an existing beneficiary. paths: /v1/beneficiaries: post: tags: - Beneficiaries summary: Create a beneficiary description: >- Registers a new beneficiary for withdrawals. Each payment instruction undergoes a compliance review — instructions start in `PENDING_REVIEW` and transition to `APPROVED` or `REJECTED` asynchronously. Crypto payment instructions require a custody attestation document, which can be attached later via `POST /v1/beneficiaries/{beneficiaryId}/documents` with the payment instruction set as the document `holder`. operationId: createBeneficiary parameters: - $ref: '#/components/parameters/IdempotencyKey' - $ref: '#/components/parameters/TraceVersion' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateBeneficiaryRequest' examples: pixIndividual: summary: Individual with PIX key value: entity: type: INDIVIDUAL firstName: João lastName: Silva taxId: value: '52998224725' type: CPF birthDate: '1985-03-15' address: addressLine1: Av. Paulista, 1000 addressLine2: Apto 42 city: São Paulo state: SP postalCode: 01310-100 country: BR relationshipType: THIRD_PARTY paymentInstruction: rail: PIX_KEY asset: BRL dictKeyType: EMAIL dictKey: joao@example.com bankCompany: summary: Company with bank account value: entity: type: COMPANY legalName: Acme Importação Ltda tradeName: Acme taxId: value: '27922482000193' type: CNPJ address: addressLine1: Rua da Consolação, 222 city: São Paulo state: SP postalCode: 01302-000 country: BR relationshipType: THIRD_PARTY paymentInstruction: rail: PIX_BANK_INSTRUCTION asset: BRL bankCode: '001' branch: '0001' accountNumber: '123456' cryptoWallet: summary: Individual with crypto wallet value: entity: type: INDIVIDUAL firstName: Jane lastName: Doe taxId: value: '11144477735' type: CPF birthDate: '1990-07-22' address: addressLine1: 123 Main St city: Lisbon postalCode: 1000-001 country: PT relationshipType: SELF_OWNED paymentInstruction: rail: CRYPTO address: '0x742d35Cc6634C0532925a3b844Bc9e7595f2bD18' network: ETHEREUM asset: USDT responses: '201': description: >- Beneficiary created. Its initial payment instruction starts in `PENDING_REVIEW` status. headers: X-Request-Id: $ref: '#/components/headers/RequestId' content: application/json: schema: $ref: '#/components/schemas/BeneficiaryResponse' '401': $ref: '#/components/responses/UnauthorizedError' '422': description: >- Validation error (invalid entity type, invalid instruction type, missing details). headers: X-Request-Id: $ref: '#/components/headers/RequestId' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: invalidData: summary: Request body failed validation value: code: INVALID_DATA message: Object contains invalid data details: errors: - code: REQUIRED message: Parameter 'body:entity' not found in request field: body:entity params: {} missingPaymentInstructionDetails: summary: Payment instruction is missing required fields value: code: MISSING_PAYMENT_INSTRUCTION_DETAILS message: Missing required payment instruction details details: rail: PIX_KEY missingKeys: - dictKeyType - dictKey components: parameters: IdempotencyKey: name: X-Idempotency-Key in: header required: true description: >- Unique key to ensure idempotent request processing. Required on all `POST`, `PUT`, and `PATCH` requests. schema: type: string format: uuid TraceVersion: name: X-Trace-Version in: header required: false description: API version. Omit to use the default version. schema: type: string example: '1' schemas: CreateBeneficiaryRequest: type: object description: Request body for creating a beneficiary. properties: entity: $ref: '#/components/schemas/EntityRequest' relationshipType: type: string enum: - SELF_OWNED - THIRD_PARTY description: >- Whether the beneficiary is the customer themselves (`SELF_OWNED`) or a separate party (`THIRD_PARTY`). paymentInstruction: $ref: '#/components/schemas/PaymentInstructionRequest' required: - entity - relationshipType - paymentInstruction BeneficiaryResponse: type: object description: An external beneficiary registered for withdrawals. properties: id: type: string format: uuid example: ben-a1b2c3d4-5e6f-7890-abcd-ef1234567890 readOnly: true customerId: type: string format: uuid description: Customer that owns this beneficiary. entity: $ref: '#/components/schemas/EntityResponse' relationshipType: type: string enum: - SELF_OWNED - THIRD_PARTY description: >- Whether the beneficiary is the customer themselves (`SELF_OWNED`) or a separate party (`THIRD_PARTY`). paymentInstructions: type: array items: $ref: '#/components/schemas/PaymentInstructionResponse' createdAt: type: string format: date-time example: '2026-04-14T10:30:00Z' readOnly: true updatedAt: type: string format: date-time example: '2026-04-14T10:30:00Z' readOnly: true required: - id - customerId - entity - relationshipType - paymentInstructions - createdAt - updatedAt ErrorResponse: type: object properties: code: type: string description: Machine-readable error code. message: type: string description: Human-readable description. details: type: object additionalProperties: true required: - code - message EntityRequest: description: The person or company that receives funds. Discriminated by `type`. oneOf: - $ref: '#/components/schemas/CompanyEntityRequest' - $ref: '#/components/schemas/IndividualEntityRequest' discriminator: propertyName: type mapping: COMPANY: $ref: '#/components/schemas/CompanyEntityRequest' INDIVIDUAL: $ref: '#/components/schemas/IndividualEntityRequest' PaymentInstructionRequest: description: Payment instruction for receiving funds. Discriminated by `rail`. oneOf: - $ref: '#/components/schemas/PixKeyInstructionRequest' - $ref: '#/components/schemas/PixBankInstructionRequest' - $ref: '#/components/schemas/CryptoWalletInstructionRequest' discriminator: propertyName: rail mapping: PIX_KEY: $ref: '#/components/schemas/PixKeyInstructionRequest' PIX_BANK_INSTRUCTION: $ref: '#/components/schemas/PixBankInstructionRequest' CRYPTO: $ref: '#/components/schemas/CryptoWalletInstructionRequest' EntityResponse: description: The person or company that receives funds. Discriminated by `type`. oneOf: - $ref: '#/components/schemas/IndividualEntityResponse' - $ref: '#/components/schemas/CompanyEntityResponse' discriminator: propertyName: type mapping: INDIVIDUAL: $ref: '#/components/schemas/IndividualEntityResponse' COMPANY: $ref: '#/components/schemas/CompanyEntityResponse' PaymentInstructionResponse: type: object description: >- A payment instruction on a beneficiary. Use `address.rail` to discriminate routing details — for beneficiary payment instructions it is one of `PIX_KEY`, `PIX_BANK_INSTRUCTION`, or `CRYPTO`. properties: id: type: string format: uuid example: pi-a1b2c3d4-5e6f-7890-abcd-ef1234567890 readOnly: true asset: $ref: '#/components/schemas/Asset' currentState: $ref: '#/components/schemas/InstructionState' address: $ref: '#/components/schemas/FinancialAddress' createdAt: type: string format: date-time example: '2026-04-14T10:30:00Z' readOnly: true required: - id - asset - currentState - address - createdAt CompanyEntityRequest: title: Company type: object properties: type: type: string enum: - COMPANY legalName: type: string description: Registered legal name. example: Acme Importação Ltda tradeName: type: - string - 'null' description: Trade name. Optional. example: Acme taxId: $ref: '#/components/schemas/TaxIdRequest' address: $ref: '#/components/schemas/Address' required: - type - legalName - taxId - address IndividualEntityRequest: title: Individual type: object properties: type: type: string enum: - INDIVIDUAL firstName: type: string description: Given name. example: João lastName: type: string description: Family name. example: Silva taxId: $ref: '#/components/schemas/TaxIdRequest' birthDate: type: string format: date description: Date of birth in ISO 8601 (`yyyy-MM-dd`). example: '1985-03-15' address: $ref: '#/components/schemas/Address' required: - type - firstName - lastName - taxId - birthDate - address PixKeyInstructionRequest: title: PIX key type: object description: PIX payment routed by a DICT key. properties: rail: type: string enum: - PIX_KEY asset: $ref: '#/components/schemas/Asset' dictKeyType: type: string enum: - CPF - CNPJ - EMAIL - PHONE - EVP description: DICT key type. dictKey: type: string description: DICT key value. example: john@example.com required: - rail - asset - dictKeyType - dictKey PixBankInstructionRequest: title: PIX bank instruction type: object description: >- PIX payment routed by bank-account details (agency + account) instead of a DICT key. properties: rail: type: string enum: - PIX_BANK_INSTRUCTION asset: $ref: '#/components/schemas/Asset' bankCode: type: string description: >- COMPE code of the receiving bank. The server resolves it to the full `Bank` (name, ISPB) on the response side. example: '001' branch: type: string description: Branch number. example: '0001' accountNumber: type: string description: Account number. example: '123456' required: - rail - asset - bankCode - branch - accountNumber CryptoWalletInstructionRequest: title: Crypto wallet type: object description: Crypto-wallet payment routed by an on-chain address. properties: rail: type: string enum: - CRYPTO asset: $ref: '#/components/schemas/Asset' address: type: string description: Wallet address. example: '0x742d35Cc6634C0532925a3b844Bc9e7595f2bD18' network: type: string description: Blockchain network. example: ETHEREUM required: - rail - asset - address - network IndividualEntityResponse: title: Individual type: object properties: type: type: string enum: - INDIVIDUAL firstName: type: string example: João lastName: type: string example: Silva taxId: $ref: '#/components/schemas/TaxIdResponse' birthDate: type: string format: date description: Date of birth in ISO 8601 (`yyyy-MM-dd`). example: '1985-03-15' address: $ref: '#/components/schemas/Address' required: - type - firstName - lastName - taxId - birthDate - address CompanyEntityResponse: title: Company type: object properties: type: type: string enum: - COMPANY legalName: type: string example: Acme Importação Ltda tradeName: type: - string - 'null' example: Acme taxId: $ref: '#/components/schemas/TaxIdResponse' address: $ref: '#/components/schemas/Address' required: - type - legalName - taxId - address Asset: type: string enum: - BRL - USDT - USDC description: > ISO 4217 currency code or stablecoin ticker. The maximum decimal scale of an `AmountValue` paired with this asset depends on the asset: | Asset | Decimals | |---|---| | BRL | 2 | | USDT | 6 | | USDC | 6 | example: BRL InstructionState: type: object description: >- A single entry in a payment instruction's state history. Carries a status, optional reason (present only for `REJECTED`), and the time the state was entered. properties: status: $ref: '#/components/schemas/InstructionStatus' reason: $ref: '#/components/schemas/Reason' description: >- Justification for entering this status (e.g., why an instruction was `REJECTED`). Present for `REJECTED`; omitted for `PENDING_REVIEW` and `APPROVED`. createdAt: type: string format: date-time description: Time the instruction entered this status. required: - status - createdAt FinancialAddress: description: >- A payment route, discriminated by `rail`. Beneficiary payment instructions emit one of `PIX_KEY`, `PIX_BANK_INSTRUCTION`, or `CRYPTO`; other rails appear in operation responses. oneOf: - $ref: '#/components/schemas/PixKeyAddress' - $ref: '#/components/schemas/PixBankInstructionAddress' - $ref: '#/components/schemas/PixStaticQrCodeAddress' - $ref: '#/components/schemas/BoletoAddress' - $ref: '#/components/schemas/CryptoWalletAddress' discriminator: propertyName: rail mapping: PIX_KEY: $ref: '#/components/schemas/PixKeyAddress' PIX_BANK_INSTRUCTION: $ref: '#/components/schemas/PixBankInstructionAddress' PIX_STATIC_QR_CODE: $ref: '#/components/schemas/PixStaticQrCodeAddress' BOLETO: $ref: '#/components/schemas/BoletoAddress' CRYPTO: $ref: '#/components/schemas/CryptoWalletAddress' TaxIdRequest: type: object description: > Tax identifier for a beneficiary entity. 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). properties: value: type: string description: Tax identifier digits only (no dots, dashes, or slashes). example: '52998224725' type: $ref: '#/components/schemas/TaxIdType' required: - value - type Address: type: object description: Postal address of an entity or beneficiary. properties: addressLine1: type: string description: Primary street line (number + street). addressLine2: oneOf: - type: string - type: 'null' description: >- Secondary line (apartment, suite, building). `null` if not applicable. city: type: string state: oneOf: - type: string - type: 'null' description: >- State, province, or region. `null` for countries without subdivisions in the address. country: $ref: '#/components/schemas/Country' postalCode: type: string description: Postal or ZIP code, formatted per the country's convention. required: - addressLine1 - addressLine2 - city - state - country - postalCode TaxIdResponse: type: object description: Tax identifier returned for a beneficiary entity. properties: value: type: string example: '52998224725' type: $ref: '#/components/schemas/TaxIdType' required: - value - type InstructionStatus: type: string enum: - PENDING_REVIEW - APPROVED - REJECTED description: > Compliance review status of a payment instruction. New instructions start in `PENDING_REVIEW` and transition asynchronously to `APPROVED` or `REJECTED`. Reason: type: object description: >- Machine- and human-readable explanation. Returned inside an `OperationState` entry when a status transition requires justification (e.g., `FAILED`). properties: code: type: string description: Machine-readable code. example: INSUFFICIENT_BALANCE message: type: string description: Human-readable description. example: Insufficient balance for the requested operation details: type: object additionalProperties: true description: Free-form context relevant to the reason. required: - code - message - details PixKeyAddress: type: object description: PIX route via DICT key. properties: rail: type: string enum: - PIX_KEY dictKeyType: type: string enum: - CPF - CNPJ - EMAIL - PHONE - EVP description: DICT key type. dictKey: type: string description: DICT key value. example: john@example.com required: - rail - dictKeyType - dictKey PixBankInstructionAddress: type: object description: PIX route via bank-account details (no DICT key). properties: rail: type: string enum: - PIX_BANK_INSTRUCTION bank: $ref: '#/components/schemas/Bank' branch: type: string example: '0001' accountNumber: type: string example: '123456' required: - rail - bank - branch - accountNumber PixStaticQrCodeAddress: type: object description: PIX route via static QR code payload. properties: rail: type: string enum: - PIX_STATIC_QR_CODE qrCode: type: string description: PIX QR code payload (EMV format). example: 00020126580014br.gov.bcb.pix... required: - rail - qrCode BoletoAddress: type: object description: Boleto route. properties: rail: type: string enum: - BOLETO barcode: type: string description: Boleto barcode (digitable line). example: 23793.38128 60800.000003 00000.000400 1 84340000012345 dueDate: type: string format: date-time description: Due date for the boleto. example: '2026-05-15T23:59:59Z' required: - rail - barcode - dueDate CryptoWalletAddress: type: object description: Crypto-wallet route. properties: rail: type: string enum: - CRYPTO network: type: string description: Blockchain network. example: ETHEREUM address: type: string description: Wallet address. example: '0x742d35Cc6634C0532925a3b844Bc9e7595f2bD18' required: - rail - network - address TaxIdType: type: string description: > Country-specific tax identifier type. The type itself implies the country (`CPF`/`CNPJ` are Brazilian, `CUIT`/`CUIL` are Argentine, `RUT_CL` is Chilean, etc.). 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. example: BR enum: - AF - AL - DZ - AS - AD - AO - AI - AQ - AG - AR - AM - AW - AU - AT - AZ - BS - BH - BD - BB - BY - BE - BZ - BJ - BM - BT - BO - BQ - BA - BW - BV - BR - IO - BN - BG - BF - BI - CV - KH - CM - CA - KY - CF - TD - CL - CN - CX - CC - CO - KM - CD - CG - CK - CR - HR - CU - CW - CY - CZ - CI - DK - DJ - DM - DO - EC - EG - SV - GQ - ER - EE - SZ - ET - FK - FO - FJ - FI - FR - GF - PF - TF - GA - GM - GE - DE - GH - GI - GR - GL - GD - GP - GU - GT - GG - GN - GW - GY - HT - HM - VA - HN - HK - HU - IS - IN - ID - IR - IQ - IE - IM - IL - IT - JM - JP - JE - JO - KZ - KE - KI - KP - KR - KW - KG - LA - LV - LB - LS - LR - LY - LI - LT - LU - MO - MG - MW - MY - MV - ML - MT - MH - MQ - MR - MU - YT - MX - FM - MD - MC - MN - ME - MS - MA - MZ - MM - NA - NR - NP - NL - NC - NZ - NI - NE - NG - NU - NF - MP - 'NO' - OM - PK - PW - PS - PA - PG - PY - PE - PH - PN - PL - PT - PR - QA - MK - RO - RU - RW - RE - BL - SH - KN - LC - MF - PM - VC - WS - SM - ST - SA - SN - RS - SC - SL - SG - SX - SK - SI - SB - SO - ZA - GS - SS - ES - LK - SD - SR - SJ - SE - CH - SY - TW - TJ - TZ - TH - TL - TG - TK - TO - TT - TN - TR - TM - TC - TV - UG - UA - AE - GB - UM - US - UY - UZ - VU - VE - VN - VG - VI - WF - EH - YE - ZM - ZW - AX Bank: type: object description: >- Bank reference. Resolved server-side from the COMPE code provided in the request. properties: code: type: string description: COMPE code (3-digit Brazilian bank code, may be sent unpadded). example: '001' name: type: string description: Registered bank name. example: BANCO DO BRASIL S.A. ispbCode: oneOf: - type: string - type: 'null' description: >- ISPB code (8-digit Brazilian payment-system identifier). `null` when the bank is not registered with an ISPB. example: '00000000' required: - code - name - ispbCode headers: RequestId: description: >- Unique request identifier emitted on every response. Reference it when contacting Trace Finance support so we can trace the request end-to-end. See [Errors](/guides/principles/errors). schema: type: string format: uuid responses: UnauthorizedError: description: Missing or invalid authentication token. headers: X-Request-Id: $ref: '#/components/headers/RequestId' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: invalidToken: $ref: '#/components/examples/InvalidToken' expiredToken: $ref: '#/components/examples/ExpiredToken' examples: InvalidToken: summary: Bearer token is invalid or malformed value: code: INVALID_ACCESS_TOKEN message: Invalid access token details: {} ExpiredToken: summary: Bearer token has expired value: code: EXPIRED_ACCESS_TOKEN message: Expired access token details: {} securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT description: >- JWT bearer token. Include as `Authorization: Bearer `. See the [Authentication](/guides/authentication) guide for how to obtain one. ````