Create a withdrawal

Creates a new withdrawal to a saved beneficiary.

POST /api/operations/withdrawal

Create a withdrawal

cURL

curl --request POST \
  --url https://api.sandbox.tracefinance.com/api/operations/withdrawal \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Idempotency-Key: <x-idempotency-key>' \
  --data '
{
  "accountId": "a1b2c3d4-5e6f-7890-abcd-ef1234567890",
  "quoteId": "d4e5f6a7-b8c9-0123-defa-2345678901bc",
  "beneficiary": {
    "type": "REFERENCE",
    "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "paymentInstruction": {
      "type": "REFERENCE",
      "id": "c3d4e5f6-a7b8-9012-cdef-1234567890ab"
    }
  }
}
'

201

pixWithdrawal

{ "id": "1f3a8c8d-2e1a-4b3a-9d2e-7c1a4b3a9d2e", "customerId": "11111111-1111-1111-1111-111111111111", "account": { "id": "a1b2c3d4-5e6f-7890-abcd-ef1234567890", "owner": "Acme Importação Ltda" }, "sourceAmount": { "value": "500.00", "asset": "BRL", "decimals": 2 }, "targetAmount": { "value": "500.00", "asset": "BRL", "decimals": 2 }, "fees": [], "transactions": [], "tags": [ { "key": "psp", "value": "Amazon" }, { "key": "compliance-tier", "value": "high" } ], "currentState": { "status": "REQUESTED", "createdAt": "2026-04-25T02:39:17Z" }, "states": [ { "status": "REQUESTED", "createdAt": "2026-04-25T02:39:17Z" } ], "intent": { "type": "WITHDRAWAL", "beneficiary": { "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901", "holder": { "type": "INDIVIDUAL", "firstName": "John", "lastName": "Doe", "taxId": { "value": "52998224725", "type": "CPF" }, "dateOfBirth": "1990-01-15", "address": { "addressLine1": "Rua Augusta, 500", "addressLine2": null, "city": "Sao Paulo", "state": "SP", "country": "BR", "postalCode": "01304-001" } }, "paymentInstruction": { "id": "c3d4e5f6-a7b8-9012-cdef-1234567890ab", "rail": "PIX_KEY", "keyType": "CPF", "key": "12345678901" } } }, "quote": { "id": "d4e5f6a7-b8c9-0123-defa-2345678901bc", "effectiveRate": { "value": "1.00", "base": "BRL", "quote": "BRL" }, "expiresAt": "2026-04-25T02:39:47Z", "consumedAt": null }, "createdAt": "2026-04-25T02:39:17Z", "updatedAt": "2026-04-25T02:39:17Z" }

Authorizations

Authorization · string · header · required

JWT bearer token. Include as Authorization: Bearer <token>. See the Authentication guide for how to obtain one.

Headers

X-Idempotency-Key · string<uuid> · required

Unique key to ensure idempotent request processing. Required on all POST, PUT, and PATCH requests.

X-Trace-Version · string

API version. Omit to use the default version.

Example:

"1"

Body

application/json

Every withdrawal references a quote previously obtained from POST /api/quotes. The quote determines sourceAmount and targetAmount and locks the FX rate (or the 1:1 spot for same-asset). A quote can be consumed by at most one operation.

accountId · string<uuid> · required

Account that funds the withdrawal. Must match the account on the referenced quote.

Example:

"a1b2c3d4-5e6f-7890-abcd-ef1234567890"

quoteId · string<uuid> · required

ID of a quote returned by POST /api/quotes. Must belong to the same customer, must not have expired, and must not have been consumed by another operation.

Example:

"d4e5f6a7-b8c9-0123-defa-2345678901bc"

beneficiary · Reference · object · required

Beneficiary for the withdrawal. Discriminated by type.

• REFERENCE — the only mode supported in the current slice. Points at a saved beneficiary by id.
• INLINE — currently rejected with 400 INLINE_BENEFICIARY_NOT_SUPPORTED.

Reference

Inline

Show child attributes

Response

201

application/json

Withdrawal accepted. The operation is in REQUESTED status.

An operation. Withdrawals (POST /api/operations/withdrawal), swaps (POST /api/operations/swap), deposits (POST /api/operations/deposit), and transfers (POST /api/operations/transfer) share this shape, discriminated by intent.type. The quote field is always present; for transfers without an explicit quoteId in the request, the system generates a 1:1 same-asset quote.

id · string<uuid> · required · read-only

customerId · string<uuid> · required

account · object · required

Reference to a customer account, including the registered owner name.

Show child attributes

sourceAmount · object · required

Monetary amount expressed as a decimal string in the asset's canonical scale. Use a decimal-precision library (BigDecimal, Decimal) for arithmetic — never JavaScript Number. Request bodies use the scalar AmountValue instead.

Show child attributes

targetAmount · object · required

Monetary amount expressed as a decimal string in the asset's canonical scale. Use a decimal-precision library (BigDecimal, Decimal) for arithmetic — never JavaScript Number. Request bodies use the scalar AmountValue instead.

Show child attributes

intent · Withdrawal · object · required

Operation intent. Discriminated by type.

Withdrawal

Swap

Deposit

Transfer

Show child attributes

quote · object · required

Reference to the quote consumed by the operation.

Show child attributes

fees · object[] · required

Show child attributes

transactions · object[] · required

Show child attributes

currentState · object · required

A single entry in an operation's state history. Carries a status, optional reason, and the time the state was entered.

Show child attributes

states · object[] · required

Full state history of the operation, oldest first. The last entry equals currentState.

Show child attributes

createdAt · string<date-time> · required · read-only

updatedAt · string<date-time> · required · read-only

tags · object[]

System-managed labels stamped onto the operation when it is created. Inherited from the account's propagating tags.

Show child attributes

Example:

[
  { "key": "psp", "value": "Amazon" },
  { "key": "compliance-tier", "value": "high" }
]