Sign in
Withdrawals

Create a withdrawal

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.

post/v1/withdrawals

Headers

X-Idempotency-Keystring required

A unique string to ensure the request is processed only once. Must be unique per request. Valid for 24 hours.

Request body

amountnumber 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'
descriptionstring

Internal description for this withdrawal.

Response

Withdrawal created.

Example response

{
  "withdrawal": {
    "txId": "WIT1746280868443K3F9Q"
  }
}

Changes