---
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_PIX_KEY` covers format only. Whether the key exists on the PIX network is not checked before acceptance: depending on when the network rejects, a well-formed key that belongs to nobody surfaces either as a synchronous `400 PROVIDER_ERROR` on this call or later as a `WITHDRAWAL_FAILED` webhook.

The creditor document sent to the PIX network is resolved in three steps, in order: (1) `destination.recipientDocument` when you send it; (2) the PIX key itself when `destination.pixKey` is a CPF or CNPJ key; (3) your own verified tax id — company CNPJ for business accounts, owner CPF for individual accounts. Step 3 is a fallback, not a default: if you pay a third party on an e-mail, phone or random key and omit `destination.recipientDocument`, the network is told your own document is the creditor, and the payout may be rejected downstream by the receiving institution.

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

`creditorDocumentSource` is a dashboard-only field and is not accepted here: sending it returns `400 CREDITOR_DOCUMENT_SOURCE_NOT_SUPPORTED` rather than being silently ignored. Use `destination.recipientDocument` to put a specific document on the payout.

## Headers

- `X-Idempotency-Key` string, required

## Request body

- CreateWithdrawalRequest
  - `amount` number, required — The NET amount in BRL — exactly what the recipient receives. The platform fee is added on top, never deducted: your balance is debited `amount + feeAmount` (returned as `grossAmount`), and that gross is what counts against `INSUFFICIENT_BALANCE`, the daily/nightly limits and the per-transaction cap. The R$10.00 minimum is compared against `amount` (the net); it is the floor the platform never goes below, and the value that actually applies to you is `minAmount` from `GET /v1/withdrawals/limits`. The 1,000,000 ceiling is a request-validation bound, not your limit — the per-transaction cap that applies to your account is returned by `GET /v1/withdrawals/limits`.
  - `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`. The key is normalized before use: CPF and CNPJ keys are reduced to digits and must pass their check digits, phone keys are normalized to `+55` E.164, and e-mail and EVP keys are trimmed and lowercased. A key that matches none of those shapes is rejected with `INVALID_PIX_KEY`.
    - `recipientDocument` string — CPF or CNPJ of the PIX key holder. Whitespace and punctuation are stripped server-side; the result must be a valid CPF (11 digits) or CNPJ (14 digits), check digits included. Send it whenever the destination key belongs to someone other than you. Omitting it on a third-party e-mail, phone or random key makes the network see your own document as creditor. If `pixKey` is itself a CPF or CNPJ key, this field must agree with it or the request is rejected with `RECIPIENT_DOCUMENT_MISMATCH`.
  - `description` string — Internal description for this withdrawal.

## Response `201`

Withdrawal created.

- object
  - `withdrawal` WithdrawalCreated — The withdrawal as returned by `POST /v1/withdrawals`. This response is deliberately narrower than the object returned by the read endpoints: it omits `pixKey`, `pixKeyType`, `processedAt` and `errorMessage`, which are only meaningful once the network has acted.
    - `id` string, uuid
    - `txId` string — Transaction identifier: `WIT` followed by a millisecond timestamp and 5 uppercase alphanumerics, e.g. `WIT1746280868443K3F9Q`. Treat it as an opaque string.
    - `grossAmount` number
    - `feeAmount` number
    - `netAmount` number
    - `paymentMethod` 'PIX'
    - `currency` 'BRL'
    - `status` 'PENDING' | 'PROCESSING' | 'COMPLETED' | 'FAILED' | 'CANCELLED' — Possible withdrawal statuses.
    - `isSandbox` boolean
    - `createdAt` string, date-time

## Other responses

- `400` — Validation failed, or the PIX network rejected the payout deterministically. Withdrawal-specific codes: `INVALID_PIX_KEY`, `INVALID_RECIPIENT_DOCUMENT`, `RECIPIENT_DOCUMENT_MISMATCH`, `CREDITOR_DOCUMENT_SOURCE_NOT_SUPPORTED`, `WITHDRAWAL_BELOW_MINIMUM`, `WITHDRAWAL_LIMIT_EXCEEDED`, `WITHDRAWAL_BELOW_PROVIDER_MINIMUM`, `WITHDRAWAL_PIX_KEY_BLOCKED`, `BLOCKLIST_DENIED`, `INSUFFICIENT_BALANCE`, `WITHDRAWAL_RECIPIENT_DOCUMENT_MISMATCH`, `PROVIDER_ERROR`. Note that a missing `X-Idempotency-Key` is rejected before the error envelope is applied and returns the flat shape `{ statusCode, error, message, code }` with code `IDEMPOTENCY_KEY_REQUIRED`.
- `401` — Missing or invalid authentication token.
- `403` — Withdrawals blocked for this account. Codes: `WITHDRAWALS_BLOCKED`, `VERIFICATION_REQUIRED`, `CREDITOR_DOCUMENT_UNAVAILABLE`, `SANDBOX_COMPANY_PRODUCTION_BLOCKED`, `CREDITOR_DOCUMENT_OVERRIDE_FORBIDDEN`, `WITHDRAWAL_PROVIDER_OVERRIDE_FORBIDDEN`.
- `409` — Idempotency conflict, raised by the idempotency middleware. `IDEMPOTENCY_PAYLOAD_MISMATCH` means the key was already used with a different request body, at any point in the 24-hour window, including by a request still in flight. `IDEMPOTENCY_CONFLICT` means a request with the same key and the same body is still being processed. Both use the **flat** envelope: `error` is the HTTP reason phrase and the machine-readable code is the top-level `code`. Note that `IDEMPOTENCY_CONFLICT` raised later by the withdrawal service on an idempotency-key collision uses the nested `Error` envelope instead.
- `429` — Rate limit exceeded.
- `500` — Code `CREDITOR_DOCUMENT_UNREADABLE`: your tax id is on file but could not be read, so no creditor document could be resolved. No money moved. Unlike a generic `INTERNAL_ERROR` this is deterministic — retrying the identical request fails the same way. Send `destination.recipientDocument` to unblock the payout, or contact support.
- `503` — The withdrawal never reached the PIX network and no money moved. Codes: `WITHDRAWAL_PROVIDER_UNAVAILABLE`, `WITHDRAWAL_TEMPORARILY_UNAVAILABLE`, `WITHDRAWAL_PROCESSING_FAILED`. Safe to retry with a new idempotency key.

## Changes

- **2026-08-27** `9d4ba1cc037c` — 1 breaking, 3 warning, 4 info
  - the `error` response's property type/format changed from `object`/`` to `string`/`` for status `409`
  - removed the optional property `error/code` from the response with the `409` status
  - removed the optional property `error/details` from the response with the `409` status
  - removed the optional property `error/message` from the response with the `409` status
  - …4 more
- **2026-08-27** `8ba4c7f9e9db` — 4 warning, 2 info
  - removed the optional property `withdrawal/errorMessage` from the response with the `201` status
  - removed the optional property `withdrawal/pixKey` from the response with the `201` status
  - removed the optional property `withdrawal/pixKeyType` from the response with the `201` status
  - removed the optional property `withdrawal/processedAt` from the response with the `201` status
  - …2 more
- **2026-05-04** `fdc857fbd70e` — 1 warning
  - removed the request property `destination/recipientDocument`
- **2026-04-14** `74ad5da44cf9` — 8 breaking, 1 warning, 6 info
  - added the new required request property `destination/pixKey`
  - added the new required request property `destination/type`
  - removed the enum value `BOLETO` of the request property `method`
  - removed the enum value `CARD` of the request property `method`
  - …11 more
- **2026-04-14** `c75657100757` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/yuvexpay/apis/yuvexpay-api/changes/v1/withdrawals/post.md)

---

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