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_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

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.taxId.value / taxId.type	string / enum	CPF/CNPJ for Brazilian beneficiaries; foreign tax ID otherwise.
   entity.dateOfBirth	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/api/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"
         },
         "dateOfBirth": "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.

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_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/api/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.

3. 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/api/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.