Criar saque
/api/v1/withdrawalsPede um saque do seu saldo disponível: para a sua conta bancária cadastrada ou para uma chave Pix de outra pessoa. Permissão: Criar/consultar saques.
Saque pela API só funciona com: chave com a permissão de saques (ela sempre tem validade), pelo menos um IP autorizado cadastrado em Integrações › API e o cabeçalho Idempotency-Key. Repetir o pedido com a mesma Idempotency-Key nunca cria dois saques.
Cabeçalhos
AuthorizationtextoobrigatórioBearer + chave com a permissão de saques.
Content-Typetextoobrigatórioapplication/json
Idempotency-KeytextoobrigatórioUm código seu, único por saque (até 80 caracteres). Sem ele: 400 idempotency_key_obrigatoria.
Corpo
valorinteiroobrigatórioValor em centavos que a pessoa vai receber. A taxa de saque é cobrada à parte do seu saldo (veja total_debitado na resposta).
chavetextoChave Pix de terceiro (e-mail, celular, CPF, CNPJ ou chave aleatória). Só com a liberação do suporte (peça ao suporte); sem a liberação, o pedido com chave é recusado (422 saque_recusado). Sem ela, o dinheiro vai para a sua conta bancária cadastrada e aprovada.
documentotextocom chave de e-mail, celular ou aleatóriaCPF ou CNPJ do dono da chave. Conferimos com o dono antes de enviar.
descricaotextoAté 140 caracteres, para você identificar o saque.
taxa_do_destinatariotrue ou falseSó com chave: true desconta a taxa do valor enviado. Precisa ser booleano de verdade (sem aspas).
Exemplo
curl -X POST https://app.grinnypay.com/api/v1/withdrawals \
-H "Authorization: Bearer $GRINNY_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: saque-2026-10-15-1" \
-d '{
"valor": 15000,
"chave": "[email protected]",
"documento": "52998224725",
"descricao": "Pagamento do fornecedor"
}'<?php
$ch = curl_init('https://app.grinnypay.com/api/v1/withdrawals');
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . getenv('GRINNY_KEY'),
'Content-Type: application/json',
'Idempotency-Key: saque-2026-10-15-1',
],
CURLOPT_POSTFIELDS => json_encode(['valor' => 15000]), // sem "chave": vai pra sua conta cadastrada
]);
$saque = json_decode(curl_exec($ch), true);Resposta 201
{
"id": 482,
"status": "processando",
"valor": 15000,
"taxa": 367,
"total_debitado": 15367,
"destino": { "tipo": "chave_pix", "chave": "[email protected]" },
"motivo": null,
"criado_em": "2026-10-15T14:40:00-03:00",
"concluido_em": null
}O objeto saque
idinteiroNúmero do saque. Use em GET /withdrawals/{id}.
statustextoaguardando_sua_aprovacao, em_analise, processando, concluido ou cancelado. Veja Status.
valorinteiroValor do saque, em centavos.
taxainteiroTaxa do saque, em centavos.
total_debitadointeiroQuanto saiu do seu saldo.
destinoobjetotipo: chave_pix ou conta_cadastrada; chave: a chave Pix de destino.
motivotexto ou nullEm análise: "Em conferência de segurança". Cancelado: por que não saiu.
criado_emdataQuando o saque foi pedido.
concluido_emdata ou nullQuando o dinheiro saiu.
Erros mais comuns
| HTTP | Código | Quando |
|---|---|---|
| 400 | idempotency_key_obrigatoria | Faltou a Idempotency-Key. |
| 400 | json_invalido | Corpo não é JSON ou falta o valor inteiro. |
| 403 | ip_obrigatorio | Nenhum IP autorizado cadastrado. |
| 403 | sem_permissao | A chave não tem a permissão de saques. |
| 422 | 2fa_obrigatorio | O vendedor não ligou o 2FA (verificação em 2 etapas) na conta. Sem ele, não há saque, nem pela API. Ligue em Configurações › Segurança. |
| 422 | saque_recusado | Saldo insuficiente, abaixo do mínimo, saques pausados, pedido repetido…: a mensagem diz o motivo. |
| 422 | sem_conta_bancaria e parecidos | Problema na sua conta bancária cadastrada. |
Exemplos de resposta de erro
{
"erro": {
"codigo": "idempotency_key_obrigatoria",
"mensagem": "Saque pela API exige o cabeçalho Idempotency-Key (até 80 letras, números, - _ : .)."
}
}{
"erro": {
"codigo": "ip_obrigatorio",
"mensagem": "Saque pela API precisa de pelo menos um IP autorizado em Integrações → API."
}
}{
"erro": {
"codigo": "saque_recusado",
"mensagem": "Saldo disponível insuficiente: você tem R$ 100,00 e o saque + taxa dá R$ 153,67."
}
}