Register a beneficiary

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 that will fund the eventual withdrawals.
Valid authentication credentials.
A webhook subscription 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 for what Trace Finance reviews and what stays on your side.

Steps

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

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.

Track the review to APPROVED

The first payment instruction on a new beneficiary triggers the full compliance review described in Beneficiary compliance. 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:

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 — it shows the full request you send and the BENEFICIARY_PAYMENT_INSTRUCTION_REJECTED payload your handler will receive.

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 payment instruction — its ID goes in the path. The document is uploaded as multipart: a JSON body part carrying the documentType, plus the binary file:

curl --request POST \
  --url https://api.sandbox.tracefinance.com/v1/beneficiaries/<beneficiary-id>/payment-instructions/<payment-instruction-id>/documents \
  --header 'Authorization: Bearer <token>' \
  --header 'X-Idempotency-Key: <unique-key>' \
  --form 'body={"documentType":"CUSTODY_ATTESTATION"};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.

Add more payment instructions (optional)

A beneficiary can hold multiple payment instructions across rails. Add another one without re-submitting the entity data:

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.

What happens next

Withdraw — use the APPROVED beneficiary and payment instruction to send funds.
Beneficiary compliance — what Trace Finance reviews on each instruction and what remains your responsibility.
Verify webhook signatures — confirm review-outcome webhooks came from Trace Finance.

Getting started

Compliance Requirements

API principles

Webhooks

Journeys

Overview

Prerequisites

Steps

What happens next

​Overview

​Prerequisites

​Steps

​What happens next

Overview

Prerequisites

Steps

What happens next