Saques

Um saque (cashout) tira dinheiro do seu saldo disponível e envia para uma chave Pix.

Método	Endpoint	Descrição
POST	/api/withdrawals	Solicita um saque Pix
GET	/api/withdrawals	Consulta saques (magic_id, status, external_ref, end_to_end, limit, resend)

Solicitar saque

POST /api/withdrawals

Headers obrigatórios: Content-Type, x-api-key, x-token, idempotency-key. Opcional: x-timezone.

Corpo da requisição

Campo	Tipo	Obrigatório	Descrição
amount	number	Sim	Valor do saque em BRL, maior que zero
requester.name	string	Sim	Nome do recebedor
requester.key	string	Sim	Chave Pix de destino
requester.key_type	string	Sim	cpf, cnpj, phone, email ou evp
transfer_method	string	Não	Pix (único valor aceito)
description	string	Não	Descrição do saque
external_ref	string	Não	A sua referência

O formato da key precisa corresponder ao key_type — veja Formatos de chave Pix. O key_type é normalizado para minúsculas antes da validação.

Exemplos por tipo de chave

CPF

POST /api/withdrawals — key_type: cpf

curl --request POST \
  --url https://api.avexus.app/api/withdrawals \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <API_KEY>' \
  --header 'x-token: <TOKEN>' \
  --header 'x-timezone: America/Sao_Paulo' \
  --header 'idempotency-key: <UNIQUE_KEY>' \
  --data '{
    "amount": 300.00,
    "description": "Repasse semanal",
    "requester": {
      "name": "Maria Souza",
      "key": "95876150096",
      "key_type": "cpf"
    },
    "transfer_method": "Pix",
    "external_ref": "repasse_2026_30"
  }'

CNPJ

POST /api/withdrawals — key_type: cnpj

curl --request POST \
  --url https://api.avexus.app/api/withdrawals \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <API_KEY>' \
  --header 'x-token: <TOKEN>' \
  --header 'x-timezone: America/Sao_Paulo' \
  --header 'idempotency-key: <UNIQUE_KEY>' \
  --data '{
    "amount": 1500.00,
    "description": "Pagamento de fornecedor",
    "requester": {
      "name": "Fornecedor XYZ LTDA",
      "key": "33400689000109",
      "key_type": "cnpj"
    },
    "transfer_method": "Pix",
    "external_ref": "fornecedor_001"
  }'

E-mail

POST /api/withdrawals — key_type: email

curl --request POST \
  --url https://api.avexus.app/api/withdrawals \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <API_KEY>' \
  --header 'x-token: <TOKEN>' \
  --header 'x-timezone: America/Sao_Paulo' \
  --header 'idempotency-key: <UNIQUE_KEY>' \
  --data '{
    "amount": 250.00,
    "requester": {
      "name": "Financeiro",
      "key": "financeiro@example.com",
      "key_type": "email"
    },
    "transfer_method": "Pix"
  }'

Telefone

POST /api/withdrawals — key_type: phone

curl --request POST \
  --url https://api.avexus.app/api/withdrawals \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <API_KEY>' \
  --header 'x-token: <TOKEN>' \
  --header 'x-timezone: America/Sao_Paulo' \
  --header 'idempotency-key: <UNIQUE_KEY>' \
  --data '{
    "amount": 100.00,
    "requester": {
      "name": "Maria Souza",
      "key": "+5511999999999",
      "key_type": "phone"
    },
    "transfer_method": "Pix"
  }'

EVP (aleatória)

POST /api/withdrawals — key_type: evp

curl --request POST \
  --url https://api.avexus.app/api/withdrawals \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <API_KEY>' \
  --header 'x-token: <TOKEN>' \
  --header 'x-timezone: America/Sao_Paulo' \
  --header 'idempotency-key: <UNIQUE_KEY>' \
  --data '{
    "amount": 500.00,
    "requester": {
      "name": "Maria Souza",
      "key": "17ce9060-b29d-4ab5-89cd-20550ce6e7ac",
      "key_type": "evp"
    },
    "transfer_method": "Pix"
  }'

Resposta

O saque nasce em CREATED e informa a fee cobrada:

201 — Withdrawal created

{
  "code": 201,
  "content": {
    "magic_id": "wth_03UdoKvLNLHg",
    "fee": 0.15,
    "amount": 300.00,
    "currency": "BRL",
    "status": "CREATED",
    "decline_reason": null,
    "description": "Repasse semanal",
    "transfer_method": "Pix",
    "end_to_end": null,
    "external_ref": "repasse_2026_30",
    "created_at": "2026-07-24T18:38:25.688Z",
    "updated_at": "2026-07-24T18:38:26.703Z"
  },
  "message": "Withdrawal created",
  "timestamp": "2026-07-24T18:38:26.703Z"
}

Nota

Todos os estados possíveis estão em Status de saque.

O que a Avexus verifica

Na criação, em ordem:

1. Conta não pausada — lojista pausado pelo operador não abre saque novo (403 · merchant is paused by the operator; new withdrawals are disabled).
2. transfer_method — só Pix (400 · unsupported transfer_method).
3. Chave Pix — formato compatível com o key_type, com dígito verificador quando for CPF/CNPJ.
4. requester.name — obrigatório, não pode ser só espaço.
5. Saldo disponível — o valor mais a taxa precisa caber em balance (422 · Insufficient available balance).

A reserva do valor é atômica: o saldo é travado, a suficiência conferida e o saque, o lançamento no ledger (AVAILABLE → PROCESSING) e o evento gravados na mesma transação de banco. Não existe janela em que dois saques simultâneos gastem o mesmo saldo.

A taxa vem das configurações da plataforma

A fee é lida a cada saque das configurações vigentes — mudar a taxa no painel do operador vale para o próximo saque, sem deploy.

Consultar saques

GET /api/withdrawals

Parâmetro	Descrição
magic_id	Identificador do saque na Avexus
status	Filtra por status (ex.: CREATED)
external_ref	Filtra pela sua referência
end_to_end	Filtra pelo identificador end-to-end do Pix
limit	Máximo de resultados. Padrão 20, teto 100
resend	true reenfileira o webhook dos saques retornados

GET /api/withdrawals — listar

curl --request GET \
  --url 'https://api.avexus.app/api/withdrawals?limit=20' \
  --header 'x-api-key: <API_KEY>' \
  --header 'x-token: <TOKEN>' \
  --header 'x-timezone: America/Sao_Paulo'

GET /api/withdrawals — por magic_id

curl --request GET \
  --url 'https://api.avexus.app/api/withdrawals?magic_id=wth_03UdoKvLNLHg' \
  --header 'x-api-key: <API_KEY>' \
  --header 'x-token: <TOKEN>' \
  --header 'x-timezone: America/Sao_Paulo'

GET /api/withdrawals — múltiplos filtros

curl --request GET \
  --url 'https://api.avexus.app/api/withdrawals?status=CREATED&external_ref=repasse_2026_30&limit=20' \
  --header 'x-api-key: <API_KEY>' \
  --header 'x-token: <TOKEN>' \
  --header 'x-timezone: America/Sao_Paulo'

GET /api/withdrawals — com reenvio de webhook

curl --request GET \
  --url 'https://api.avexus.app/api/withdrawals?magic_id=wth_03UdoKvLNLHg&resend=true' \
  --header 'x-api-key: <API_KEY>' \
  --header 'x-token: <TOKEN>' \
  --header 'x-timezone: America/Sao_Paulo'

Saque em USDT

A Avexus também paga em USDT (BEP-20, rede BSC). Esse fluxo é feito pelo painel, não pela API do lojista: ele exige verificação em duas etapas (TOTP) por ser uma operação irreversível para uma carteira externa.

Na resposta, um saque em cripto traz campos adicionais — wallet_address, network, tx_hash, usdt_amount, cancel_requested_at e cancel_reason. Os saques Pix não têm esses campos.

TODO(contrato)

Se o saque em USDT vai ser exposto na API do lojista (e como o segundo fator seria apresentado numa chamada servidor-a-servidor) é decisão da frente F0 — Contrato. Hoje ele existe apenas em /dashboard/withdrawals/crypto, autenticado por sessão do painel.

Veja também

• Formatos de chave Pix — o que cada key_type aceita.
• Status de saque — o ciclo de vida completo.
• Saldo e extrato — de onde sai o dinheiro do saque.