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

Changed in 5 of the 13 revisions of this API.9913

  • 9d4ba1cc037c134See the full diff
    • ▲

      the error response's property type/format changed from object/ to string/ for status 409

      response-property-type-changed

    • ●

      removed the optional property error/code from the response with the 409 status

      response-optional-property-removed

    • ●

      removed the optional property error/details from the response with the 409 status

      response-optional-property-removed

    • ●

      removed the optional property error/message from the response with the 409 status

      response-optional-property-removed

    • ○

      added the non-success response with the status 500

      response-non-success-status-added

    • ○

      added the optional property code to the response with the 409 status

      response-optional-property-added

    • ○

      added the optional property message to the response with the 409 status

      response-optional-property-added

    • ○

      added the optional property statusCode to the response with the 409 status

      response-optional-property-added

  • 8ba4c7f9e9db42See the full diff
    • ●

      removed the optional property withdrawal/errorMessage from the response with the 201 status

      response-optional-property-removed

    • ●

      removed the optional property withdrawal/pixKey from the response with the 201 status

      response-optional-property-removed

    • ●

      removed the optional property withdrawal/pixKeyType from the response with the 201 status

      response-optional-property-removed

    • ●

      removed the optional property withdrawal/processedAt from the response with the 201 status

      response-optional-property-removed

    • ○

      added the new optional request property destination/recipientDocument

      new-optional-request-property

    • ○

      added the non-success response with the status 503

      response-non-success-status-added

    This revision also has 24 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog

  • fdc857fbd70e1See the full diff
    • ●

      removed the request property destination/recipientDocument

      request-property-removed

  • 74ad5da44cf9816See the full diff
    • ▲

      added the new required request property destination/pixKey

      new-required-request-property

    • ▲

      added the new required request property destination/type

      new-required-request-property

    • ▲

      removed the enum value BOLETO of the request property method

      request-property-enum-value-removed

    • ▲

      removed the enum value CARD of the request property method

      request-property-enum-value-removed

    • ▲

      removed the enum value CRYPTO_LTC of the request property method

      request-property-enum-value-removed

    • ▲

      removed the enum value LTC of the request property currency

      request-property-enum-value-removed

    • ▲

      removed subschema #1: PIX destination subschema #2: Crypto destination from the destination request property oneOf list

      request-property-one-of-removed

    • ▲

      the destination request property type/format changed from / to object/

      request-property-type-changed

    • ●

      removed the request property idempotencyKey

      request-property-removed

    • ○

      added the new optional request property destination/recipientDocument

      new-optional-request-property

    • ○

      removed discriminator from destination request property

      request-property-discriminator-removed

    • ○

      added the optional property withdrawal/currency to the response with the 201 status

      response-optional-property-added

    • ○

      added the optional property withdrawal/errorMessage to the response with the 201 status

      response-optional-property-added

    • ○

      added the optional property withdrawal/paymentMethod to the response with the 201 status

      response-optional-property-added

    • ○

      added the optional property withdrawal/processedAt to the response with the 201 status

      response-optional-property-added

  • c756571007571See the full diff
    • ○

      endpoint added

      endpoint-added

    This revision also has 8 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog