Skip to main content

Documentation Index

Fetch the complete documentation index at: https://tracefinance-docs-withdrawal-beneficiary-events.mintlify.app/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

Withdrawals move funds out of an account to an external destination — a bank account (PIX, TED) or a crypto wallet. Every withdrawal references a quote that locks the FX rate (or a 1:1 spot for same-asset) and a previously approved beneficiary with at least one payment instruction.

​
Prerequisites

​
Steps

1

Register a beneficiary and add a payment instruction

Submit the holder details and the payment instruction (PIX, bank account, or crypto wallet). The beneficiary record itself has no status — it is created once and reused across destinations. Each payment instruction is reviewed individually: it starts in PENDING_REVIEW on creation and transitions asynchronously to APPROVED or REJECTED. The first instruction on a new beneficiary triggers the full compliance review; instructions added later to the same beneficiary go through a reduced check.
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 '{
    "holder": {
      "type": "INDIVIDUAL",
      "firstName": "John",
      "lastName": "Doe",
      "taxId": {
        "value": "12345678901",
        "type": "CPF"
      },
      "dateOfBirth": "1990-01-15"
    },
    "relationshipType": "THIRD_PARTY",
    "paymentInstruction": {
      "type": "PIX",
      "asset": "BRL",
      "dictKeyType": "CPF",
      "dictKey": "12345678901"
    }
  }'
The response returns the beneficiary with its id and the created paymentInstruction.id. A BENEFICIARY_PAYMENT_INSTRUCTION_CREATED webhook fires immediately, then either BENEFICIARY_PAYMENT_INSTRUCTION_APPROVED or BENEFICIARY_PAYMENT_INSTRUCTION_REJECTED once the review completes — subscribe to track the outcome. Only APPROVED instructions can be used in a withdrawal.
2

Create a quote

Quotes lock the FX rate (or a 1:1 spot for same-asset) for a short window and are bound to one account. Provide either sourceAmount or targetAmount, never both.
curl --request POST \
  --url https://api.sandbox.tracefinance.com/api/quotes \
  --header 'Authorization: Bearer <token>' \
  --header 'X-Idempotency-Key: <unique-key>' \
  --header 'Content-Type: application/json' \
  --data '{
    "accountId": "<account-id>",
    "sourceAsset": "BRL",
    "targetAsset": "BRL",
    "sourceAmount": "500.00"
  }'
The response returns the quote id, the locked effectiveRate, and expiresAt. The quote can be consumed by exactly one operation before it expires.
3

Create the withdrawal

Reference the approved beneficiary, the chosen payment instruction on that beneficiary, and the quote.
curl --request POST \
  --url https://api.sandbox.tracefinance.com/api/operations/withdrawal \
  --header 'Authorization: Bearer <token>' \
  --header 'X-Idempotency-Key: <unique-key>' \
  --header 'Content-Type: application/json' \
  --data '{
    "accountId": "<account-id>",
    "quoteId": "<quote-id>",
    "beneficiary": {
      "type": "REFERENCE",
      "id": "<beneficiary-id>",
      "paymentInstruction": {
        "type": "REFERENCE",
        "id": "<payment-instruction-id>"
      }
    }
  }'
Returns 201 immediately with the operation in REQUESTED status. Settlement and rail dispatch happen asynchronously.
4

Track the withdrawal

Subscribe to OPERATION_COMPLETED and OPERATION_FAILED to receive the terminal outcome — both deliver the same payload as OPERATION_REQUESTED, with currentState.status set to the new status (and currentState.reason populated on failure). Intermediate statuses (PROCESSING, ON_HOLD, ACTION_REQUIRED) are not published as webhooks; poll GET /api/operations/{operationId} if you need to surface them in your UI.
curl --request GET \
  --url https://api.sandbox.tracefinance.com/api/operations/<operation-id> \
  --header 'Authorization: Bearer <token>'

​
What happens next