> ## 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.

# Register a beneficiary

> Submit a beneficiary and a payment instruction, then track the compliance review to APPROVED.

## Overview

Beneficiaries are the end-users your platform pays out to. To withdraw funds to one, you first register the beneficiary together with at least one payment instruction (PIX dict key, bank account, or crypto wallet). The payment instruction is reviewed asynchronously by Trace Finance — only `APPROVED` instructions can be referenced by a withdrawal.

The beneficiary record itself has no status: it is created once and reused. Each payment instruction is reviewed individually.

## Prerequisites

* An [active account](/journeys/open-account) that will fund the eventual withdrawals.
* Valid [authentication credentials](/guides/authentication).
* A [webhook subscription](/webhooks/subscribe) for `BENEFICIARY_PAYMENT_INSTRUCTION_APPROVED` and `BENEFICIARY_PAYMENT_INSTRUCTION_REJECTED` (recommended — the review is asynchronous).
* The entity data you collected during your own end-user KYC. See [Beneficiary compliance](/guides/compliance/beneficiaries) for what Trace Finance reviews and what stays on your side.

## Steps

<Steps>
  <Step title="Submit the beneficiary and first payment instruction">
    The request carries both the entity identity and the first payment instruction in one call. The entity fields are identity-equivalent to a KYC submission; the payment instruction is rail-specific.

    | Field                               | Format        | Notes                                                           |
    | ----------------------------------- | ------------- | --------------------------------------------------------------- |
    | `entity.type`                       | enum          | `INDIVIDUAL` or `COMPANY`.                                      |
    | `entity.firstName` / `lastName`     | string        | Required when `type = INDIVIDUAL`.                              |
    | `entity.legalName`                  | string        | Required when `type = COMPANY`.                                 |
    | `entity.tradeName`                  | string        | Optional.                                                       |
    | `entity.taxId.value` / `taxId.type` | string / enum | CPF/CNPJ for Brazilian beneficiaries; foreign tax ID otherwise. |
    | `entity.birthDate`                  | `yyyy-MM-dd`  | Required when `type = INDIVIDUAL`.                              |
    | `entity.address`                    | object        | Residential or registered address.                              |
    | `relationshipType`                  | enum          | `SELF_OWNED` or `THIRD_PARTY`.                                  |
    | `paymentInstruction`                | object        | Rail-specific (PIX dict key, crypto wallet, etc.).              |

    ```bash theme={"theme":"tokyo-night"}
    curl --request POST \
      --url https://api.sandbox.tracefinance.com/v1/beneficiaries \
      --header 'Authorization: Bearer <token>' \
      --header 'X-Idempotency-Key: <unique-key>' \
      --header 'Content-Type: application/json' \
      --data '{
        "entity": {
          "type": "INDIVIDUAL",
          "firstName": "John",
          "lastName": "Doe",
          "taxId": {
            "value": "12345678901",
            "type": "CPF"
          },
          "birthDate": "1990-01-15"
        },
        "relationshipType": "THIRD_PARTY",
        "paymentInstruction": {
          "rail": "PIX_KEY",
          "asset": "BRL",
          "dictKeyType": "CPF",
          "dictKey": "12345678901"
        }
      }'
    ```

    The response returns the beneficiary with its `id` and the created `paymentInstruction.id` in `PENDING_REVIEW` status. A `BENEFICIARY_PAYMENT_INSTRUCTION_CREATED` webhook fires immediately.
  </Step>

  <Step title="Track the review to APPROVED">
    The first payment instruction on a new beneficiary triggers the full compliance review described in [Beneficiary compliance](/guides/compliance/beneficiaries). The review resolves asynchronously — typically within seconds — to `APPROVED` or `REJECTED`, delivered as a `BENEFICIARY_PAYMENT_INSTRUCTION_APPROVED` or `BENEFICIARY_PAYMENT_INSTRUCTION_REJECTED` webhook.

    If you cannot subscribe to webhooks, poll the beneficiary endpoint until the instruction settles:

    ```bash theme={"theme":"tokyo-night"}
    curl --request GET \
      --url https://api.sandbox.tracefinance.com/v1/beneficiaries/<beneficiary-id> \
      --header 'Authorization: Bearer <token>'
    ```

    On `REJECTED`, the webhook payload includes a `currentState.reason` describing why. The instruction cannot be reused — fix the data and submit a new instruction (see next step), or register a new beneficiary if the entity data was wrong.

    To force a rejection in sandbox while you build your handler, see [Testing in sandbox → Force a payment-instruction rejection](/guides/testing-in-sandbox#force-a-payment-instruction-rejection) — it shows the full request you send and the `BENEFICIARY_PAYMENT_INSTRUCTION_REJECTED` payload your handler will receive.
  </Step>

  <Step title="Upload a custody attestation for crypto (when required)">
    A crypto payment instruction requires a custody attestation document to complete its compliance review. Attach it inline when creating the beneficiary, or upload it afterwards while the instruction is still under review. The endpoint is scoped to the beneficiary; set the payment instruction as the document `holder` in the `body`. The document is uploaded as multipart: a JSON `body` part carrying the `documentType` and `holder`, plus the binary `file`:

    ```bash theme={"theme":"tokyo-night"}
    curl --request POST \
      --url https://api.sandbox.tracefinance.com/v1/beneficiaries/<beneficiary-id>/documents \
      --header 'Authorization: Bearer <token>' \
      --header 'X-Idempotency-Key: <unique-key>' \
      --form 'body={"documentType":"CUSTODY_ATTESTATION","holder":{"type":"PAYMENT_INSTRUCTION","referenceId":"<payment-instruction-id>"}};type=application/json' \
      --form 'file=@custody-attestation.pdf'
    ```

    Trace Finance stores the file and forwards it to the compliance review. Once accepted, the crypto instruction can settle to `APPROVED`.
  </Step>

  <Step title="Add more payment instructions (optional)">
    A beneficiary can hold multiple payment instructions across rails. Add another one without re-submitting the entity data:

    ```bash theme={"theme":"tokyo-night"}
    curl --request POST \
      --url https://api.sandbox.tracefinance.com/v1/beneficiaries/<beneficiary-id>/payment-instructions \
      --header 'Authorization: Bearer <token>' \
      --header 'X-Idempotency-Key: <unique-key>' \
      --header 'Content-Type: application/json' \
      --data '{
        "rail": "PIX_KEY",
        "asset": "BRL",
        "dictKeyType": "EMAIL",
        "dictKey": "john.doe@example.com"
      }'
    ```

    Subsequent instructions on the same beneficiary go through a reduced compliance check — the entity has already been screened, so only the new payment-instrument is verified.
  </Step>
</Steps>

## What happens next

* [Withdraw](/journeys/withdrawal) — use the `APPROVED` beneficiary and payment instruction to send funds.
* [Beneficiary compliance](/guides/compliance/beneficiaries) — what Trace Finance reviews on each instruction and what remains your responsibility.
* [Verify webhook signatures](/webhooks/verify-signatures) — confirm review-outcome webhooks came from Trace Finance.