Skip to main content

​
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

​
Steps

1

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.The entity’s identificationDocument accepts any supported document type. A tax-id type (such as CPF or CNPJ) implies its country, so no country is needed. A foreign natural person without a tax id can use a non-fiscal PASSPORT, in which case you must supply a country:
The response returns the beneficiary with its id and the created paymentInstruction.id in PENDING_REVIEW status. A BENEFICIARY_INSTRUCTION_CREATED webhook fires immediately.
2

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_INSTRUCTION_APPROVED or BENEFICIARY_INSTRUCTION_REJECTED webhook.If you cannot subscribe to webhooks, poll the beneficiary endpoint until the instruction settles:
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_INSTRUCTION_REJECTED payload your handler will receive.
3

Send the documents compliance asks for

Compliance decides what an instruction needs and tells you. Wait to be asked — creating a beneficiary takes no document, and uploading before the review has started is refused with 409.You learn what is wanted in two ways, and they say the same thing: the BENEFICIARY_INSTRUCTION_ACTION_REQUIRED webhook, or requirements on the instruction when you read the beneficiary. Everything in requirements.currentlyDue and requirements.errors is still owed. A crypto instruction is normally asked for a custody attestation, which proves the wallet’s custody arrangement.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:
Trace Finance stores the file and hands it to the compliance review in the same request, so a refusal reaches you as an error rather than silently. Once accepted, the instruction can settle to APPROVED.Sending the same documentType again replaces the file instead of adding a second document: it keeps its referenceId, its version increases, and the review restarts on the new file. Previous versions are retained.
A requirement can name a family of documents rather than one — IDENTITY_VERIFICATION, for example. anyOf lists the types that answer it, and sending any one of them settles the requirement. For a requirement naming a single document, anyOf holds exactly that one, so you can always read anyOf and ignore the distinction.
4

Replace a document compliance asks for (when it happens)

A reviewer can send a document back instead of deciding. The instruction moves to ACTION_REQUIRED and you get a BENEFICIARY_INSTRUCTION_ACTION_REQUIRED webhook. This is a request, not a verdict — the same instruction can still be approved.What to send is in instruction.requirements: errors holds what came back, each with the reason compliance gave; currentlyDue holds anything asked for that you have not sent yet. Upload exactly as in the previous step, with the same instruction as holder.
Read requirements, not documents[]. documents[] is what you already sent — compliance can ask for something you never sent, and then documents[] says nothing while the instruction is ACTION_REQUIRED.More than one thing can be owed at once, so one upload may not end the wait. The instruction returns to PENDING_REVIEW on its own once currentlyDue and errors are both empty.
5

Add more payment instructions (optional)

A beneficiary can hold multiple payment instructions across rails. Add another one without re-submitting the entity data:
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.