> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tracefinance.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Withdraw

> Step-by-step guide to sending funds from an account to a registered beneficiary.

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

* An [active account](/journeys/open-account) with sufficient balance in the quote's source asset.
* Valid [authentication credentials](/guides/authentication).

## Steps

<Steps>
  <Step title="Register a beneficiary and add a payment instruction">
    Submit the entity 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.

    ```bash theme={"theme":"tokyo-night"}
    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`. 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.
  </Step>

  <Step title="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.

    ```bash theme={"theme":"tokyo-night"}
    curl --request POST \
      --url https://api.sandbox.tracefinance.com/v1/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.
  </Step>

  <Step title="Create the withdrawal">
    Reference the approved beneficiary, the chosen payment instruction on that beneficiary, and the quote.

    ```bash theme={"theme":"tokyo-night"}
    curl --request POST \
      --url https://api.sandbox.tracefinance.com/v1/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": {
          "mode": "REFERENCE",
          "id": "<beneficiary-id>",
          "paymentInstruction": {
            "mode": "REFERENCE",
            "id": "<payment-instruction-id>"
          }
        }
      }'
    ```

    Returns `201` immediately with the operation in `REQUESTED` status. Settlement and rail dispatch happen asynchronously.
  </Step>

  <Step title="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). If the operation pauses waiting on an action from you, `OPERATION_CUSTOMER_ACTION_REQUIRED` fires and processing resumes once the pending action is resolved. The intermediate `PROCESSING` status is not published as a webhook; poll `GET /v1/operations/{operationId}` if you need to surface it in your UI.

    ```bash theme={"theme":"tokyo-night"}
    curl --request GET \
      --url https://api.sandbox.tracefinance.com/v1/operations/<operation-id> \
      --header 'Authorization: Bearer <token>'
    ```

    On `FAILED`, the operation's `currentState.reason` carries a code and message describing the cause. To exercise this branch in sandbox before you ship, see [Testing in sandbox → Force a withdrawal failure](/guides/testing-in-sandbox#force-a-withdrawal-failure) — it shows the withdrawal request you submit and the `OPERATION_FAILED` payload your handler will receive for each of the simulated rail errors.
  </Step>
</Steps>

## What happens next

* [Make a deposit](/journeys/deposit) — fund an account before withdrawing.
* [Execute a swap](/journeys/swap) — convert between assets before sending out.