Saldo e saques
Consulte o saldo e saque para uma chave Pix pela API, com segurança.
Saldo
GET /api/v1/balance (permissão balance:read):
{
"availableCents": 125000,
"pendingCents": 8900,
"blockedCents": 0,
"withdrawableNowCents": 124900,
"withdrawFeeCents": 100,
"livemode": true
}availableCents: o que já pode sair.pendingCents: vendas pagas ainda no prazo de liberação.blockedCents: retido, por exemplo, por um MED.withdrawableNowCents: quanto dá para sacar agora, num saque só.
Sacar
POST /api/v1/withdrawals tira o valor do saldo e envia para uma chave Pix.
Esta permissão tira dinheiro da conta
withdrawals:write vem desligada em toda chave. Antes de ligar, em Chaves de API:
- libere só o IP do servidor que vai sacar;
- defina um limite diário de saque para a chave;
- use essa chave só para sacar, separada da que cria cobranças.
curl -X POST https://api.wysepay.com.br/api/v1/withdrawals \
-H "x-api-key: wyp_test_sua_chave_de_saque" \
-H "Content-Type: application/json" \
-H "idempotency-key: repasse-2026-10-05" \
-d '{
"amountCents": 50000,
"pixKey": "12345678000190",
"pixKeyType": "CNPJ"
}'| Campo | O que é |
|---|---|
amountCents | Quanto sai do saldo, já incluindo a taxa de saque. Mínimo 600 (R$ 6,00). O que chega no destino é amountCents − taxa. |
pixKey | A chave Pix de destino. |
pixKeyType | CPF, CNPJ, PHONE (celular com DDD), EMAIL ou EVP (chave aleatória). |
- Idempotência: envie sempre a
idempotency-key. Repetindo com a mesma chave, o mesmo saque volta e nada sai duas vezes. - Conta verificada: em produção, o saque exige a conta verificada, como no painel.
- Aviso por e-mail: o dono da conta recebe o mesmo e-mail de um saque feito no painel.
Limite diário
Com limite definido, a chave só saca até esse valor por dia, contado no horário de Brasília (o dia vira à meia-noite). Entram na conta os saques daquela chave no dia, menos os que falharam. Passou do limite, a resposta é 403 com code: "WITHDRAW_DAILY_LIMIT" e diz quanto ainda resta.
Acompanhar
O saque começa PENDING e termina PAID, PARTIALLY_PAID (parte voltou ao saldo) ou FAILED (tudo voltou). Ele pode ser pago em mais de uma transferência Pix. Use os webhooks withdrawal.paid, withdrawal.partially_paid e withdrawal.failed, ou consulte GET /api/v1/withdrawals/{id}.
A chave de destino aparece parcialmente escondida nas respostas.
No modo teste
Com uma chave wyp_test_, o saque é simulado: sai do saldo de teste, fica PAID na hora e envia withdrawal.created e withdrawal.paid aos endpoints de teste. Para ter saldo de teste, simule pagamentos.