> ## Documentation Index
> Fetch the complete documentation index at: https://docs.liquerapay.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Solicitar Saque
> Solicita um saque do seu saldo disponível para uma chave PIX.
**Atenção:**
- O valor mínimo é de **50 centavos** (R$ 0,50), máximo 100.000.000 (R$ 1.000.000,00)
- O saque inclui uma taxa que é debitada junto: o débito total é `amount + fee`
- Só é permitido **um saque em andamento por vez** (`PENDING`/`PROCESSING`) — uma nova solicitação enquanto houver um em curso retorna `400`
- Saques podem estar bloqueados se `withdrawalsEnabled` estiver desativado para o merchant
Solicita um saque do saldo `available` para uma chave PIX.
`amount` (mínimo 50 centavos), `pixKey` e `pixKeyType`. A taxa é calculada
automaticamente conforme o contrato do merchant.
**Exemplo:**
```json theme={null}
{
"amount": 5000,
"pixKey": "pagamentos@minhaloja.com",
"pixKeyType": "EMAIL",
"description": "Repasse semanal"
}
```
**Resposta:**
```json theme={null}
{
"data": {
"id": "with_018f91023e4a7d20e5f6",
"amount": 5000,
"fee": 50,
"status": "PENDING",
"createdAt": "2026-04-19T20:00:00.000Z"
},
"error": null,
"success": true
}
```
A resposta é enxuta — não devolve `pixKey`/`pixKeyType` (você já os
enviou). Para ver todos os detalhes depois, use
[`GET /withdrawals/{id}`](/pages/withdrawals/get).
## Só um saque por vez
Você só pode ter **um saque em andamento** (`PENDING` ou `PROCESSING`) por
merchant. Uma nova solicitação enquanto houver um em curso retorna `400` —
aguarde a conclusão (ou falha) do saque atual antes de solicitar outro.
## Erros possíveis
| HTTP | `error` | Causa |
| ----- | ------------- | --------------------------------------------------------- |
| `400` | `BAD_REQUEST` | Saques não habilitados para este merchant |
| `400` | `BAD_REQUEST` | Já existe um saque em processamento |
| `400` | `BAD_REQUEST` | Saldo insuficiente |
| `400` | `BAD_REQUEST` | Valor fora da faixa permitida (50 a 100.000.000 centavos) |
| `400` | `BAD_REQUEST` | Valor acima do limite de saque do merchant |
O saque retorna **imediatamente** com status `PENDING`. O processamento
real é assíncrono — acompanhe o resultado via [`GET /withdrawals/{id}`](/pages/withdrawals/get)
ou pelos webhooks `WITHDRAWAL_COMPLETED` / `WITHDRAWAL_FAILED`.
## OpenAPI
````yaml POST /withdrawals
openapi: 3.1.0
info:
title: API Liquerapay
description: |
API pública da Liquerapay para criar cobranças PIX, processar saques,
gerenciar clientes e receber eventos via webhooks.
## Versão Beta
A v1 está em **beta**. Endpoints e payloads podem sofrer pequenas
alterações antes da versão estável (1.0). Recomendamos travar a versão
da sua integração no `package.json` / `requirements.txt` enquanto
estivermos em beta.
Não há ambiente de sandbox — todas as chamadas acontecem contra o
ambiente de produção.
## Como começar
1. Crie sua conta em [app.liquerapay.com](https://app.liquerapay.com)
2. Gere uma chave de API no painel (`liq_...`)
3. Faça sua primeira chamada em `https://api.liquerapay.com`
version: 1.0.0-beta
contact:
name: Suporte Liquerapay
url: https://liquerapay.com
license:
name: Proprietary
servers:
- url: https://api.liquerapay.com
description: Produção
security:
- bearerAuth: []
tags:
- name: Customers
description: Cadastre e gerencie os clientes da sua loja para reutilizar em cobranças.
- name: Checkout Transparente
description: >-
Crie cobranças PIX (QR Code copia-e-cola) direto pela API e gerencie
devoluções.
- name: Withdrawals
description: Solicite saques do saldo disponível para uma chave PIX.
- name: Webhooks
description: Cadastre URLs para receber eventos da Liquerapay em tempo real.
paths:
/withdrawals:
post:
tags:
- Withdrawals
summary: Solicitar saque
description: >
Solicita um saque do seu saldo disponível para uma chave PIX.
**Atenção:**
- O valor mínimo é de **50 centavos** (R$ 0,50), máximo 100.000.000 (R$
1.000.000,00)
- O saque inclui uma taxa que é debitada junto: o débito total é `amount
+ fee`
- Só é permitido **um saque em andamento por vez**
(`PENDING`/`PROCESSING`) — uma nova solicitação enquanto houver um em
curso retorna `400`
- Saques podem estar bloqueados se `withdrawalsEnabled` estiver
desativado para o merchant
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateWithdrawalRequest'
responses:
'201':
description: Saque criado e enfileirado para processamento.
content:
application/json:
schema:
$ref: '#/components/schemas/CreateWithdrawalResponse'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
components:
schemas:
CreateWithdrawalRequest:
type: object
required:
- amount
- pixKey
- pixKeyType
additionalProperties: false
properties:
amount:
type: integer
minimum: 50
maximum: 100000000
description: >-
Valor do saque em centavos (mínimo 50 = R$ 0,50, máximo 100.000.000
= R$ 1.000.000,00).
example: 5000
pixKey:
type: string
minLength: 1
maxLength: 140
description: Chave PIX que receberá o saque.
example: pagamentos@minhaloja.com
pixKeyType:
$ref: '#/components/schemas/PixKeyType'
description:
type: string
maxLength: 140
description: Texto livre para sua referência.
example: Repasse semanal
taxId:
type: string
maxLength: 18
description: CPF/CNPJ do destinatário da chave PIX (opcional).
example: '12345678900'
CreateWithdrawalResponse:
type: object
required:
- data
- error
- success
properties:
data:
$ref: '#/components/schemas/Withdrawal'
error:
type: 'null'
example: null
success:
type: boolean
enum:
- true
example: true
PixKeyType:
type: string
enum:
- CPF
- CNPJ
- EMAIL
- TELEFONE
- CHAVE_ALEATORIA
description: |
Tipo da chave PIX:
- `CPF`: CPF (apenas dígitos)
- `CNPJ`: CNPJ (apenas dígitos)
- `EMAIL`: e-mail válido
- `TELEFONE`: celular no formato `+5511999999999`
- `CHAVE_ALEATORIA`: chave aleatória (UUID/EVP)
example: EMAIL
Withdrawal:
type: object
required:
- id
- amount
- fee
- status
- createdAt
description: >-
Shape retornado por `POST /withdrawals`. Não inclui
`pixKey`/`pixKeyType` — consulte com `GET /withdrawals/{id}` os dados
que você mesmo enviou, se precisar.
properties:
id:
type: string
example: with_018f91023e4a7d20e5f6
amount:
type: integer
example: 5000
fee:
type: integer
example: 50
status:
$ref: '#/components/schemas/WithdrawalStatus'
createdAt:
type: string
format: date-time
example: '2026-04-19T20:00:00.000Z'
Error:
type: object
required:
- error
- message
- success
properties:
error:
type: string
description: >-
Código do erro (ex.: `VALIDATION_ERROR`, `UNAUTHORIZED`,
`NOT_FOUND`).
example: VALIDATION_ERROR
message:
type: string
description: Mensagem amigável descrevendo o erro.
example: 'amount: deve ser um número inteiro positivo'
success:
type: boolean
enum:
- false
example: false
WithdrawalStatus:
type: string
enum:
- PENDING
- PROCESSING
- COMPLETED
- FAILED
description: |
- `PENDING`: solicitado, aguardando processamento
- `PROCESSING`: em processamento no PSP
- `COMPLETED`: PIX enviado com sucesso
- `FAILED`: falhou (ver `failedReason`)
example: COMPLETED
responses:
BadRequest:
description: Requisição inválida (validação ou regra de negócio).
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
validation:
summary: Erro de validação
value:
error: VALIDATION_ERROR
message: 'amount: deve ser um número inteiro positivo'
success: false
business:
summary: Erro de regra de negócio
value:
error: BAD_REQUEST
message: >-
Saldo insuficiente. Disponível 4500 centavos, necessário 5050
centavos
success: false
Unauthorized:
description: Falha de autenticação (token inválido, ausente ou revogado).
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error: UNAUTHORIZED
message: Token inválido ou ausente
success: false
Forbidden:
description: Acesso negado para esta operação.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error: FORBIDDEN
message: Saques estão temporariamente bloqueados para este merchant
success: false
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: API Key ou JWT
description: |
Autentique suas requisições enviando o token no header
`Authorization: Bearer `.
O token pode ser:
- Uma **API key** com prefixo `liq_`, gerada em
[Dashboard Liquerapay → Configurações → API Keys](https://app.liquerapay.com).
- Um **JWT** retornado pelo login do dashboard (uso interno).
Não há distinção de ambiente — toda chave vale para o único
ambiente disponível (produção).
````