---
title: "Create a withdrawal"
method: POST
path: "/v1/withdrawals"
tags: ["Withdrawals"]
---

# Create a withdrawal

`POST /v1/withdrawals`

Create a PIX withdrawal to transfer BRL funds from your YuvexPay balance. Requires an idempotency key.

The PIX key type (CPF, CNPJ, e-mail, phone, or random key) is detected automatically from `destination.pixKey` — you do not need to declare it. Invalid keys are rejected with `INVALID_PIX_KEY`.

The creditor document on the network is always derived server-side from your verified company tax id (CNPJ for business accounts, owner CPF for individual accounts).

Withdrawals may be blocked outside business hours or if your account has restrictions.

## Headers

- `X-Idempotency-Key` string, required

## Request body

- CreateWithdrawalRequest
  - `amount` number, required — Withdrawal amount (minimum R$10.00).
  - `method` 'PIX' — Public withdrawals currently support PIX only.
  - `currency` 'BRL'
  - `destination` object, required — Where to send the funds.
    - `type` 'pix', required
    - `pixKey` string, required — PIX key. Accepts CPF, CNPJ, e-mail, Brazilian phone (`+55XXXXXXXXXXX`), or a random EVP/UUID. The type is detected automatically; you do not need to send `pixKeyType`. Whitespace and punctuation are stripped server-side.
  - `description` string — Internal description for this withdrawal.

## Response `201`

Withdrawal created.

- object
  - `withdrawal` Withdrawal
    - `id` string, uuid
    - `txId` string
    - `grossAmount` number
    - `feeAmount` number
    - `netAmount` number
    - `pixKey` string — The destination PIX key, masked. The full key is never returned by the API once the withdrawal is created.
    - `pixKeyType` string — Type of PIX key (CPF, CNPJ, EMAIL, PHONE, RANDOM).
    - `status` 'PENDING' | 'PROCESSING' | 'COMPLETED' | 'FAILED' | 'CANCELLED' — Possible withdrawal statuses.
    - `isSandbox` boolean
    - `createdAt` string, date-time
    - `paymentMethod` 'PIX'
    - `currency` 'BRL'
    - `processedAt` string, date-time, nullable
    - `errorMessage` string, nullable — Human-readable failure message. Treat as opaque text and surface only to internal operators.

## Other responses

- `400` — Validation error.
- `401` — Missing or invalid authentication token.
- `403` — Withdrawals blocked for this account.
- `409` — Idempotency conflict. The key was already used with a different payload.
- `429` — Rate limit exceeded.

---

[API](https://skmtc.net/yuvexpay/apis/yuvexpay-api.md) · [All operations](https://skmtc.net/yuvexpay/apis/yuvexpay-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/yuvexpay/yuvexpay-api/revisions/0d036504e049/schema)