curl --request POST \
--url https://api.yuvexpay.com/v1/withdrawals \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--header 'X-Idempotency-Key: <x-idempotency-key>' \
--data '
{
"amount": 500,
"method": "PIX",
"currency": "BRL",
"destination": {
"type": "pix",
"pixKey": "ana@example.com",
"recipientDocument": "529.982.247-25"
},
"description": "Weekly payout"
}
'{
"withdrawal": {
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"txId": "WIT1746280868443K3F9Q",
"grossAmount": 123,
"feeAmount": 123,
"netAmount": 123,
"paymentMethod": "PIX",
"currency": "BRL",
"status": "PENDING",
"isSandbox": true,
"createdAt": "2023-11-07T05:31:56Z"
}
}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.
curl --request POST \
--url https://api.yuvexpay.com/v1/withdrawals \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--header 'X-Idempotency-Key: <x-idempotency-key>' \
--data '
{
"amount": 500,
"method": "PIX",
"currency": "BRL",
"destination": {
"type": "pix",
"pixKey": "ana@example.com",
"recipientDocument": "529.982.247-25"
},
"description": "Weekly payout"
}
'{
"withdrawal": {
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"txId": "WIT1746280868443K3F9Q",
"grossAmount": 123,
"feeAmount": 123,
"netAmount": 123,
"paymentMethod": "PIX",
"currency": "BRL",
"status": "PENDING",
"isSandbox": true,
"createdAt": "2023-11-07T05:31:56Z"
}
}Authorizations
YuvexPay API key. Include as Authorization: Bearer ypk_<env>_<kid>_<secret> where <env> is test (sandbox) or live (production). Create and manage keys in the dashboard under Settings > API Keys.
Headers
A unique string to ensure the request is processed only once. Must be unique per request. Valid for 24 hours. Successful (2xx) responses are stored and replayed for the key. On POST /v1/payments, a 502 PROVIDER_TEMPORARILY_UNAVAILABLE for a boleto payment is stored and replayed too: to recover that payment, repeat the request once with the same externalId and a new key. A retry of an earlier card payment request now returns 400 CARD_PAYMENTS_NOT_AVAILABLE_VIA_API instead of the stored response (201 or 502): recover that payment with GET /v1/payments/txid/{txId}, or with a create request with the same externalId, mode: "hosted" and methods: ["CARD"], no card object or card fields, and a new key.
100Body
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.
10 <= x <= 1000000Must be a multiple of 0.01Where to send the funds.
Show child attributes
Show child attributes
Public withdrawals currently support PIX only.
PIX BRL Internal description for this withdrawal.
500Response
Withdrawal created.
The withdrawal as returned by POST /v1/withdrawals. This response is deliberately narrower than GET /v1/withdrawals/{withdrawalId}: it omits pixKey, pixKeyType, processedAt, errorMessage and providerErrorCode, which are only meaningful once the network has acted.
Show child attributes
Show child attributes