Saques

Criar saque

POST/api/v1/withdrawals

Pede 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ório

Bearer + chave com a permissão de saques.

Content-Typetextoobrigatório

application/json

Idempotency-Keytextoobrigatório

Um código seu, único por saque (até 80 caracteres). Sem ele: 400 idempotency_key_obrigatoria.

Corpo

valorinteiroobrigatório

Valor em centavos que a pessoa vai receber. A taxa de saque é cobrada à parte do seu saldo (veja total_debitado na resposta).

chavetexto

Chave 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ória

CPF ou CNPJ do dono da chave. Conferimos com o dono antes de enviar.

descricaotexto

Até 140 caracteres, para você identificar o saque.

taxa_do_destinatariotrue ou false

Só 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"
  }'

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

idinteiro

Número do saque. Use em GET /withdrawals/{id}.

statustexto

aguardando_sua_aprovacao, em_analise, processando, concluido ou cancelado. Veja Status.

valorinteiro

Valor do saque, em centavos.

taxainteiro

Taxa do saque, em centavos.

total_debitadointeiro

Quanto saiu do seu saldo.

destinoobjeto

tipo: chave_pix ou conta_cadastrada; chave: a chave Pix de destino.

motivotexto ou null

Em análise: "Em conferência de segurança". Cancelado: por que não saiu.

criado_emdata

Quando o saque foi pedido.

concluido_emdata ou null

Quando o dinheiro saiu.

Erros mais comuns

HTTPCódigoQuando
400idempotency_key_obrigatoriaFaltou a Idempotency-Key.
400json_invalidoCorpo não é JSON ou falta o valor inteiro.
403ip_obrigatorioNenhum IP autorizado cadastrado.
403sem_permissaoA chave não tem a permissão de saques.
4222fa_obrigatorioO 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.
422saque_recusadoSaldo insuficiente, abaixo do mínimo, saques pausados, pedido repetido…: a mensagem diz o motivo.
422sem_conta_bancaria e parecidosProblema 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, - _ : .)."
  }
}