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 that will fund the eventual withdrawals.
• Valid authentication credentials.
• A webhook subscription for BENEFICIARY_INSTRUCTION_APPROVED and BENEFICIARY_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

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.

   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.identificationDocument.value / identificationDocument.type	string / enum	CPF/CNPJ for Brazilian beneficiaries; a foreign tax id or non-fiscal PASSPORT otherwise.
   entity.identificationDocument.country	ISO 3166-1 alpha-2	Required only for PASSPORT; implied by the type for tax ids.
   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.).

   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:

   "identificationDocument": {
     "value": "A1234567",
     "type": "PASSPORT",
     "country": "US"
   }
   

   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",
         "identificationDocument": {
           "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_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:

   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_INSTRUCTION_REJECTED payload your handler will receive.

3. 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:

   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.

   If compliance asks for a clearer file, upload the same documentType again while the instruction is still under review. That replaces the file instead of adding a second document: the document keeps its referenceId, its version increases, and the review restarts on the new file. Previous versions are retained.

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.

   Which file to replace is in instruction.documents[]: the one whose currentState.status is ACTION_REQUIRED, with its own currentState.reason (for example, “Send a colour scan — this one is illegible”). Upload the replacement exactly as in the previous step, with the same instruction as holder.

   Compliance can ask about more than one document. The instruction stays ACTION_REQUIRED until none of its documents is, so replacing one file may not end the wait — always read the per-document state rather than assuming one upload settles the review. The instruction returns to PENDING_REVIEW on its own once nothing is outstanding.

5. 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": "[e-mail]"
     }'
   

   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.