Webhooks

Webhooks — Cashouts PIX

Receba notificações em tempo real sempre que o status de um cashout PIX mudar. Configure a URL de webhook ao criar o cashout.

Configuração do Endpoint

Método	POST
Content-Type	application/json
Resposta esperada	HTTP 200

Status Possíveis do Cashout

approvedCashout aprovado e transferência concluída

pendingCashout aguardando processamento

processingCashout em processamento pelo banco

failedFalha no processamento

rejectedCashout rejeitado pela instituição financeira

Exemplo de Payload

Notificação de Cashout Aprovadojson

{
  "id": "f2c5f6e7-f710-437f-ad8c-44022316123e",
  "external_id": "saque_12345",
  "status": "approved",
  "total_amount": 250.00,
  "pix_key": "joao.silva@exemplo.com"
}

Campos do Payload

Campo	Tipo	Descrição
`id`	`string (UUID)`	ID único do cashout
`external_id`	`string \| null`	Sua referência interna informada na criação
`status`	`string`	Novo status: approved, pending, processing, failed ou rejected
`total_amount`	`number`	Valor do cashout em BRL
`pix_key`	`string`	Chave PIX de destino utilizada

Implementação de Exemplo

Node.js + Expressjavascript

app.post('/webhooks/cashouts', (req, res) => {
  const { id, external_id, status, total_amount, pix_key } = req.body;
  
  // Responda imediatamente com 200
  res.status(200).json({ received: true });

  setImmediate(() => {
    switch (status) {
      case 'approved':
        // Saque aprovado — atualize o saldo no seu sistema
        atualizarSaldo(id, external_id, total_amount);
        break;
      case 'failed':
      case 'rejected':
        // Falha — notifique ou agende retry
        notificarFalhaCashout(id, external_id);
        break;
    }
  });
});

Configure o campo webhook_url ao criar o cashout com POST /v1/cashout.