> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usevext.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Solicitar saque

> Tira dinheiro do saldo: PIX para uma chave no bolsão, TED para a conta bancária no split.

> [!NOTE]
>
> Os valores aqui são **inteiros em centavos**: R\$ 100,00 se envia como `10000`. Decimais são
> recusados com `422`, e o porquê está em [Valores em centavos](https://docs.usevext.com/essenciais/valores-em-centavos.md).

> [!NOTE]
>
> Envie `Idempotency-Key` nesta chamada e você pode repetir com tranquilidade depois de um erro de
> rede: a mesma chave devolve o recurso que já existe, em vez de criar um segundo.
> Veja [Idempotência](https://docs.usevext.com/essenciais/idempotencia.md).

> [!WARNING]
>
> O tipo da chave é **declarado** em `pix_key_type`, e um valor de outro tipo é recusado — nunca
> reclassificado. Com o saque automático desligado, o saque fica em `awaiting_approval` até a Vext
> aprovar. Destino por modelo, tipos de chave e recusas em [Saques](https://docs.usevext.com/essenciais/saques.md).


## OpenAPI

````yaml api-reference/openapi.yaml POST /v1/withdrawals
openapi: 3.1.0
info:
  title: Vext - API de pagamentos PIX com split
  version: 1.0.0
  summary: Cobranças PIX, estornos e saldo do vendedor.
  description: |
    API pública do gateway. Todo endpoint desta versão vive sob `/v1`.

    ## Dinheiro é sempre CENTAVOS INTEIROS

    Não há exceção. `amount`, `platform_fee`, `net_amount`, `refunded_amount`,
    `fee_returned`, `seller_debit`, `balance`, `available`, `reserved`, `debt`
    e `withdrawable` são inteiros em centavos de real.

    | Valor       | Envie / receba |
    |-------------|----------------|
    | R$ 1,00     | `100`          |
    | R$ 10,50    | `1050`         |
    | R$ 1.234,56 | `123456`       |

    Enviar `10.50` devolve `422`. A recusa é deliberada: `10.50` chega ao
    servidor como ponto flutuante, `10.50 * 100` não é exatamente `1050` em
    binário, e o centavo perdido só aparece na conciliação do mês. Diante de
    um decimal preferimos recusar a adivinhar a intenção - com dinheiro,
    adivinhar sai caro.

    ## Autenticação

    Toda chamada leva a chave no header:

    ```
    Authorization: Bearer sk_live_SUA_CHAVE_SECRETA
    ```

    A chave é criada em **Desenvolvedores** no painel e o valor em claro
    aparece **uma única vez**, na criação - guardamos apenas um hash
    SHA-256. Perdeu, gere outra.

    Cada chave carrega escopos (`charges:read`, `charges:write`,
    `refunds:write`, `balance:read`, `cards:manage`). Chamar um endpoint
    fora do escopo devolve `403`, e não `401`: a chave está certa, faltou
    permissão.

    Chaves de teste usam o prefixo `sk_test_`. A diferença é visível a olho
    nu de propósito - uma chave de teste colada em produção precisa ser
    reconhecível antes de alguém passar a tarde investigando.

    ## Idempotência

    Envie `Idempotency-Key` em todo `POST`. A conexão que cai depois da
    requisição e antes da resposta deixa você sem saber se cobrou; repetir
    com a mesma chave resolve isso sem risco de cobrar duas vezes.

    - **mesma chave, mesmo corpo** → a resposta gravada, com
      `Idempotent-Replayed: true`. A cobrança não é recriada.
    - **mesma chave, corpo diferente** → `409 idempotency_key_reused`.
      Devolver a cobrança antiga faria você acreditar que cobrou o valor
      novo.
    - **mesma chave, primeira ainda em voo** → `409
      idempotency_key_in_progress`. Repita em instantes.

    A ordem dos campos no JSON não invalida o retry. A chave vale por 24
    horas e é sua: dois clientes diferentes podem usar `pedido-1` sem
    colidir.

    ## Erros

    Todo erro - inclusive os que não previmos - tem a mesma forma:

    ```json
    {
      "error": {
        "type": "invalid_request_error",
        "code": "amount_below_minimum",
        "message": "…",
        "details": {}
      }
    }
    ```

    Trate pelo `code`, nunca pela `message`: o código é contrato, o texto
    pode ser reescrito a qualquer momento.
  contact:
    name: Suporte Vext
    url: https://wa.me/5511936185272
servers:
  - url: https://api.usevext.com
    description: Produção
security:
  - apiKey: []
tags:
  - name: Cobranças
    description: Criação, consulta e estorno de cobranças, no PIX e no cartão.
  - name: Saldo
    description: Quanto o vendedor tem e quanto pode sacar.
  - name: Saques
    description: PIX para uma chave no bolsão, TED para a conta bancária no split.
  - name: Cartão no navegador
    description: |
      O que o navegador do comprador precisa para virar um formulário de
      cartão: a credencial de tokenização e o token do desafio de
      autenticação. O número do cartão nunca passa por esta API.
  - name: Cartões
    description: |
      Os cartões que os compradores deixaram guardados, para cobrar de novo
      sem pedir nada a eles.
paths:
  /v1/withdrawals:
    post:
      tags:
        - Saques
      summary: Solicitar saque
      description: |
        Tira dinheiro do saldo do vendedor: PIX para uma chave no modelo
        bolsão, TED para a conta bancária no split. Destino, tipos de chave,
        status e recusas em [Saques](/essenciais/saques).
      operationId: createWithdrawal
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateWithdrawalRequest'
            examples:
              email:
                summary: PIX para um e-mail
                value:
                  amount: 50000
                  pix_key_type: email
                  pix_key: financeiro@fornecedor.com.br
              aleatoria:
                summary: PIX para uma chave aleatória
                value:
                  amount: 50000
                  pix_key_type: random
                  pix_key: 123e4567-e89b-12d3-a456-426614174000
              padrao:
                summary: Para a chave ou conta padrão
                value:
                  amount: 50000
      responses:
        '201':
          description: Saque registrado e saldo debitado.
          headers:
            Idempotent-Replayed:
              $ref: '#/components/headers/IdempotentReplayed'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Withdrawal'
              examples:
                bolsao:
                  summary: Saque PIX aguardando conferência
                  value:
                    object: withdrawal
                    id: wd_01k1y8d4h1g2f3e4d5c6b7a8z9
                    status: awaiting_approval
                    method: pix
                    amount: 50000
                    currency: BRL
                    fee: 367
                    net: 49633
                    pix_key_type: email
                    pix_key: fi********@fornecedor.com.br
                    failed_reason: null
                    created_at: '2026-10-27T14:02:00+00:00'
                    processed_at: null
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '409':
          $ref: '#/components/responses/IdempotencyConflict'
        '422':
          $ref: '#/components/responses/UnprocessableWithdrawal'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
        '502':
          $ref: '#/components/responses/ProviderUnavailable'
      security:
        - apiKey:
            - withdrawals:write
components:
  parameters:
    IdempotencyKey:
      name: Idempotency-Key
      in: header
      required: false
      description: |
        Identificador único da SUA tentativa. Use o mesmo valor ao repetir
        a requisição depois de um erro de rede.

        Opcional, mas recomendado em toda criação de cobrança e estorno.
        Sem ele, uma repetição cria uma segunda cobrança.
      schema:
        type: string
        maxLength: 255
      example: pedido-1042
  schemas:
    CreateWithdrawalRequest:
      type: object
      required:
        - amount
      properties:
        amount:
          allOf:
            - $ref: '#/components/schemas/Cents'
          description: |
            O que sai do saldo, em centavos inteiros. A taxa vem de dentro
            deste valor.
          example: 50000
        pix_key_type:
          type: string
          enum:
            - cpf
            - cnpj
            - email
            - phone
            - random
            - evp
          description: |
            Obrigatório junto com `pix_key`. Só para contas no modelo bolsão.
        pix_key:
          type: string
          maxLength: 77
          description: |
            A chave, do tipo declarado. CPF e CNPJ têm o dígito verificador
            conferido; telefone aceita com ou sem `+55`; e-mail é gravado em
            minúsculas. Obrigatório junto com `pix_key_type`.
          example: financeiro@fornecedor.com.br
    Withdrawal:
      type: object
      description: |
        Um saque. `amount`, `fee` e `net` são centavos inteiros, e sempre
        `net = amount - fee`. A chave PIX vem mascarada.
      required:
        - object
        - id
        - status
        - method
        - amount
        - currency
        - fee
        - net
        - pix_key_type
        - pix_key
        - failed_reason
        - created_at
        - processed_at
      properties:
        object:
          type: string
          const: withdrawal
        id:
          type: string
          example: wd_01k1y8d4h1g2f3e4d5c6b7a8z9
        status:
          $ref: '#/components/schemas/WithdrawalStatus'
        method:
          type: string
          enum:
            - pix
            - ted
          description: '`pix` no bolsão, `ted` no split.'
        amount:
          allOf:
            - $ref: '#/components/schemas/Cents'
          description: O que saiu do saldo.
        currency:
          type: string
          const: BRL
        fee:
          allOf:
            - $ref: '#/components/schemas/Cents'
          description: A taxa do saque, de dentro de `amount`.
        net:
          allOf:
            - $ref: '#/components/schemas/Cents'
          description: O que chega ao destino.
        pix_key_type:
          oneOf:
            - $ref: '#/components/schemas/PixKeyType'
            - type: 'null'
          description: '`null` no saque por TED.'
        pix_key:
          type:
            - string
            - 'null'
          description: A chave de destino, mascarada. `null` no saque por TED.
          example: fi********@fornecedor.com.br
        failed_reason:
          type:
            - string
            - 'null'
        created_at:
          type: string
          format: date-time
        processed_at:
          type:
            - string
            - 'null'
          format: date-time
    Cents:
      type: integer
      format: int64
      description: |
        Valor monetário em **centavos inteiros** de real. R$ 10,00 = `1000`.
        Nunca decimal, nunca string.
    WithdrawalStatus:
      type: string
      description: O que cada status significa está em [Saques](/essenciais/saques#status).
      enum:
        - pending
        - processing
        - awaiting_approval
        - approved
        - paid
        - failed
        - canceled
        - rejected
    PixKeyType:
      type: string
      description: |
        `random` é a chave aleatória (o EVP do Banco Central); `evp` é
        aceito como sinônimo na entrada, e a saída usa sempre `random`.
      enum:
        - cpf
        - cnpj
        - email
        - phone
        - random
    Error:
      type: object
      required:
        - error
      properties:
        error:
          type: object
          required:
            - type
            - code
            - message
            - details
          properties:
            type:
              type: string
              description: |
                Família do erro. Responde "de quem é o problema e o que
                fazer": `invalid_request_error` se corrige mudando a
                chamada, `authentication_error` trocando a chave, e
                `api_error` é nosso - repita, não reescreva.
              enum:
                - authentication_error
                - permission_error
                - invalid_request_error
                - idempotency_error
                - not_found_error
                - rate_limit_error
                - api_error
                - card_error
            code:
              type: string
              description: |
                Código estável do erro. **Trate por ele.** A `message` pode
                ser reescrita a qualquer momento; o código, não.
            message:
              type: string
              description: Explicação em português, para leitura humana.
            details:
              type: object
              description: |
                Sempre objeto, mesmo vazio. Em `validation_failed`, traz os
                campos recusados e suas mensagens.
              additionalProperties: true
  headers:
    IdempotentReplayed:
      description: |
        Presente com valor `true` quando o corpo devolvido é uma resposta
        **gravada**, e não um recurso novo. Nada foi criado nesta chamada.
      schema:
        type: string
        enum:
          - 'true'
  responses:
    Unauthorized:
      description: |
        Chave ausente, desconhecida, revogada ou expirada. A revogada é
        distinguida da inexistente na MENSAGEM, nunca no status: quem
        integra precisa saber que a chave existiu e foi desligada, e quem
        está adivinhando tokens não aprende nada com isso.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            ausente:
              summary: missing_api_key
              value:
                error:
                  type: authentication_error
                  code: missing_api_key
                  message: 'Envie a chave em Authorization: Bearer sk_live_...'
                  details: {}
            invalida:
              summary: invalid_api_key
              value:
                error:
                  type: authentication_error
                  code: invalid_api_key
                  message: Chave de API inválida.
                  details: {}
            revogada:
              summary: revoked_api_key
              value:
                error:
                  type: authentication_error
                  code: revoked_api_key
                  message: >-
                    Esta chave de API foi revogada. Gere uma nova em
                    Desenvolvedores.
                  details: {}
            expirada:
              summary: expired_api_key
              value:
                error:
                  type: authentication_error
                  code: expired_api_key
                  message: Esta chave de API expirou. Gere uma nova em Desenvolvedores.
                  details: {}
    Forbidden:
      description: |
        A chave é válida, mas não tem o escopo do endpoint. `403` e não
        `401` de propósito: `401` diria "sua chave está errada" a quem tem
        a chave certa.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            escopo:
              summary: insufficient_scope
              value:
                error:
                  type: permission_error
                  code: insufficient_scope
                  message: Esta chave não tem o escopo [refunds:write].
                  details:
                    required_ability: refunds:write
                    abilities:
                      - charges:read
                      - charges:write
            umClique:
              summary: one_click_requires_three_ds
              value:
                error:
                  type: permission_error
                  code: one_click_requires_three_ds
                  message: >-
                    Esta loja exige autenticação do portador, e o pagamento de
                    um clique não a suporta.
                  details: {}
    IdempotencyConflict:
      description: Conflito de chave de idempotência.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            reusada:
              summary: idempotency_key_reused
              description: |
                A chave já foi usada com outro corpo. Devolver a resposta
                antiga faria você acreditar que cobrou o valor novo.
              value:
                error:
                  type: idempotency_error
                  code: idempotency_key_reused
                  message: >-
                    Esta chave de idempotência já foi usada com um corpo
                    diferente. Use uma chave nova.
                  details: {}
            emAndamento:
              summary: idempotency_key_in_progress
              value:
                error:
                  type: idempotency_error
                  code: idempotency_key_in_progress
                  message: >-
                    Uma requisição com esta chave ainda está em processamento.
                    Tente novamente em instantes.
                  details: {}
    UnprocessableWithdrawal:
      description: |
        O saque foi recusado - por validação (`validation_failed`, com o
        campo em `details`) ou por uma regra de negócio. Nada foi debitado.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            saldo:
              summary: insufficient_balance
              value:
                error:
                  type: invalid_request_error
                  code: insufficient_balance
                  message: >-
                    Saldo disponível para saque: R$ 300,00. Você solicitou R$
                    500,00.
                  details: {}
            semChave:
              summary: no_pix_key
              description: Bolsão, sem chave na chamada e sem chave cadastrada.
              value:
                error:
                  type: invalid_request_error
                  code: no_pix_key
                  message: Cadastre uma chave PIX antes de solicitar saque.
                  details: {}
            teto:
              summary: amount_above_maximum
              value:
                error:
                  type: invalid_request_error
                  code: amount_above_maximum
                  message: >-
                    O valor máximo por saque é R$ 15.000,00. Divida em mais de
                    um pedido.
                  details: {}
            chaveInvalida:
              summary: validation_failed
              description: O valor não é chave do tipo declarado.
              value:
                error:
                  type: invalid_request_error
                  code: validation_failed
                  message: Alguns campos não passaram na validação.
                  details:
                    pix_key:
                      - Chave PIX inválida para o tipo Telefone.
            splitComPix:
              summary: validation_failed (conta split)
              value:
                error:
                  type: invalid_request_error
                  code: validation_failed
                  message: Alguns campos não passaram na validação.
                  details:
                    pix_key:
                      - >-
                        O saque desta conta vai para a conta bancária
                        cadastrada. Chave PIX só vale para contas no modelo
                        bolsão.
    RateLimited:
      description: |
        Requisições demais.

        Há três limites, por minuto: um por IP antes da autenticação, e
        depois um de leitura e um de escrita, ambos por CHAVE - o excesso
        de uma integração não consome a cota das outras do mesmo
        vendedor. A escrita é bem mais apertada porque cada cobrança
        criada vira uma chamada ao provedor.

        `Retry-After` diz em quantos segundos voltar. Os cabeçalhos
        `X-RateLimit-*` vêm em TODA resposta, não só nesta: são eles que
        permitem desacelerar antes de bater no limite.
      headers:
        Retry-After:
          description: Segundos até a cota ser reposta.
          schema:
            type: integer
        X-RateLimit-Limit:
          description: Requisições permitidas por minuto neste balde.
          schema:
            type: integer
        X-RateLimit-Remaining:
          description: Quantas ainda cabem no minuto corrente.
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            cota:
              summary: too_many_requests
              value:
                error:
                  type: rate_limit_error
                  code: too_many_requests
                  message: Muitas requisições. Tente novamente em 42 segundos.
                  details:
                    retry_after: 42
            provedor:
              summary: provider_rate_limited
              value:
                error:
                  type: rate_limit_error
                  code: provider_rate_limited
                  message: >-
                    Limite de requisições do provedor atingido. Tente novamente
                    em instantes.
                  details: {}
    InternalError:
      description: |
        Erro inesperado do nosso lado. Repita com a mesma
        `Idempotency-Key` - ela é o que torna repetir seguro.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            interno:
              value:
                error:
                  type: api_error
                  code: internal_error
                  message: >-
                    Erro interno. Se persistir, informe o horário da chamada ao
                    suporte.
                  details: {}
    ProviderUnavailable:
      description: |
        O provedor de pagamento não respondeu. **Repita com a mesma
        `Idempotency-Key`**: pode ser que a cobrança tenha sido criada lá e
        a resposta se perdido no caminho, e a mesma chave devolve a
        cobrança em vez de criar outra.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            indisponivel:
              value:
                error:
                  type: api_error
                  code: provider_unavailable
                  message: >-
                    O provedor de pagamento não respondeu. Repita a requisição
                    com a mesma Idempotency-Key.
                  details: {}
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
      bearerFormat: sk_live_… | sk_test_…
      description: |
        Chave secreta do vendedor, criada no painel em **Desenvolvedores**.

        O valor em claro existe uma única vez, na criação. Guardamos só o
        hash SHA-256 - nem o suporte consegue recuperá-lo, o que é o ponto:
        um dump do nosso banco não permite cobrar em nome de ninguém.

        A chave vai no **servidor**. Colocá-la no navegador do comprador a
        entrega a qualquer pessoa que abra a página.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.