Saques

O termo de produto é Saque (payout). O endpoint atual é /v1/withdrawals — o nome de fio em uso hoje, ainda não renomeado para /v1/payouts.

Tira saldo para fora da sua carteira Liqfy, rumo a um destino real — uma chave Pix, uma conta bancária (TED) ou um endereço cripto. É o inverso do pagamento Pix: pagamento credita sua carteira, saque debita.

#O fluxo, de relance

1. POST /v1/withdrawals/validate-pix-key   (opcional — checagem prévia)
2. POST /v1/withdrawals                    (cria a solicitação; debita na aprovação)
3. A Liqfy aprova / o adquirente liquida
4. O webhook withdrawal.completed (ou .failed) chega no seu endpoint

Saque exige usuário autenticado por JWT (o painel ou seu back-office), não a chave de API pública. Ele debita a carteira do lojista direto e passa por aprovação — não é um fluxo que o cliente final dispara.

A disponibilidade dos trilhos é por conta. TED e cripto dependem de o módulo correspondente estar habilitado para você. Confirme com seu contato na Liqfy antes de construir em cima de um deles.

#1. Validar uma chave Pix (recomendado)

Antes de criar o saque, confira se a chave de destino está bem formada.

POST /v1/withdrawals/validate-pix-key

{
  "key": "12345678909",
  "type": "CPF"
}

Resposta 200 OK

{
  "valid": true,
  "type": "CPF",
  "normalised": "12345678909"
}

Valores aceitos em type

Falha

{
  "valid": false,
  "type": "CPF",
  "errors": ["invalid CPF checksum"]
}

#2. Criar o saque

POST /v1/withdrawals

Exemplo — saque Pix

curl -X POST https://liqfy.com.br/v1/withdrawals \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "PIX",
    "amount": 50000,
    "currency": "BRL",
    "pixKey": "12345678909",
    "pixKeyType": "CPF",
    "description": "Saque semanal — semana 17",
    "idempotencyKey": "saque-2026-S17"
  }'

Resposta 201 Created

{
  "id": "f6a7b8c9-d0e1-4234-9f01-234567890123",
  "status": "PENDING",
  "type": "PIX",
  "amount": 50000,
  "currency": "BRL",
  "pixKey": "12345678909",
  "pixKeyType": "CPF",
  "fee": 100,
  "netAmount": 49900,
  "description": "Saque semanal — semana 17",
  "createdAt": "2026-04-25T16:10:00.000Z"
}

A carteira ainda não foi debitada — isso acontece na aprovação.

#3. Ciclo de vida

PENDING  ─▶  APPROVED  ─▶  PROCESSING  ─▶  COMPLETED   ✓ dinheiro entregue
                                            ─▶  FAILED       adquirente recusou, carteira estornada
              ─▶  REJECTED                                   negado na revisão — nunca debitado
              ─▶  CANCELLED                                  você cancelou antes da aprovação

#4. Webhooks

Assine withdrawal.completed e withdrawal.failed (o mesmo array events usado nos pagamentos) para acompanhar o desfecho:

{
  "event": "withdrawal.completed",
  "data": {
    "withdrawalId": "f6a7b8c9-d0e1-4234-9f01-234567890123",
    "amount": 50000,
    "fee": 100,
    "netAmount": 49900,
    "status": "COMPLETED",
    "previousStatus": "PROCESSING",
    "type": "PIX",
    "occurredAt": "2026-04-25T16:11:42.000Z"
  }
}

Em withdrawal.failed, o data.status é FAILED, REJECTED ou CANCELLED. No caso de FAILED a carteira já foi estornada automaticamente.

#5. Listar seus saques

GET /v1/withdrawals?page=1&limit=20&status=COMPLETED

Autenticação: o mesmo JWT do endpoint de criação.

{
  "data": [
    {
      "id": "wd_...",
      "status": "COMPLETED",
      "type": "PIX",
      "amount": 50000,
      "fee": 100,
      "netAmount": 49900,
      "completedAt": "2026-04-25T16:11:42.000Z",
      "...": "..."
    }
  ],
  "total": 17,
  "page": 1,
  "limit": 20
}

#6. Limites e regras

• Teto por transação no Pix — R$ 100.000,00 por padrão (seu contrato pode ampliar).
• Teto diário — 5× o teto por transação, por padrão.
• A carteira precisa cobrir valor + taxa — débito parcial nunca acontece; a solicitação é recusada de uma vez.
• Aprovação — por padrão, todo saque passa por aprovação. Lojistas com histórico podem solicitar aprovação automática abaixo de um limite configurado.
• TED — restrito a bancos brasileiros (código do banco na lista da FEBRABAN). Liquidação no mesmo dia útil se aprovado até 16:30 (horário de Brasília).
• Cripto — liquida só em USDT na BSC (BEP-20). O cryptoNetwork precisa ser BSC e o cryptoCurrency, USDT; o destino precisa ser um endereço BEP-20 (0x…) válido, verificado no servidor antes de qualquer débito na carteira. Rede, token ou endereço não suportados são recusados de imediato e não movem dinheiro. Envio para a rede errada não tem recuperação — é assim por natureza do trilho, não por decisão nossa.

#Dúvidas

P: Criei um saque e ele está preso em PENDING. R: A aprovação é obrigatória por padrão. Aprove pelo painel ou solicite a aprovação automática ao suporte.

P: Meu saque deu FAILED — a taxa foi cobrada? R: Não. O FAILED dispara um estorno automático e atômico de valor + taxa na carteira.

P: Dá para cancelar um saque? R: Só enquanto estiver PENDING. Depois de aprovado, o dinheiro já está em trânsito.

P: Minha chave CNPJ foi recusada como inválida, mas meu banco aceita. R: O dígito verificador mod-11 falha em chaves emitidas antes de 2014. Dá para aceitar o valor com o parâmetro ?strictCnpj=false — peça ao suporte para habilitar.

P: Meu banco não aparece na lista de TED. R: Usamos a lista de códigos FEBRABAN do Bacen. Abra um chamado se faltar algum — normalmente resolvemos em 24h.