🔔 Webhooks - Cash API

📡 Visão Geral

A Cash API envia webhooks para notificar sua aplicação sobre mudanças de status em tempo real.

💰 Cash-In: Depósitos PIX

Webhooks enviados quando o status de um depósito PIX muda.

Fluxo de Status

Eventos e Status

Status	Evento	Descrição	Webhook
pending	Depósito criado	QR Code gerado, aguardando pagamento	ENVIA
paid	Pagamento confirmado	PIX recebido e confirmado pelo banco	ENVIA
expired	QR Code expirado	Tempo limite do QR Code atingido sem pagamento	ENVIA
refunded	Estorno realizado	Valor devolvido ao pagador	ENVIA

Campos do Payload

Campo	Tipo	Descrição
id	string	Hash único do depósito
externalId	string|null	ID externo informado na criação
method	string	Método de pagamento (pix)
status	string	Status atual: pending, paid, expired, refunded
pix.code	string	Código PIX copia e cola
pix.imageBase64	string	QR Code em base64
payer.name	string|null	Nome do pagador (preenchido após pagamento)
payer.document	string|null	CPF/CNPJ do pagador
payer.email	string|null	E-mail do pagador
amount	integer	Valor bruto em centavos
netAmount	integer	Valor líquido em centavos (após taxa)
fee	integer	Taxa em centavos
endToEndId	string|null	ID E2E do PIX (preenchido após pagamento)
postbackUrl	string	URL de callback configurada
createdAt	datetime	Data de criação
updatedAt	datetime	Data da última atualização

Exemplo de Payload

{
    "id": "dep_01HXXXXXXXXXXXXXXXXX",
    "externalId": "pedido_123",
    "method": "pix",
    "status": "paid",
    "pix": {
        "code": "00020126580014br.gov.bcb.pix0136123e4567-e89b-12d3-a456-426614174000...",
        "imageBase64": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..."
    },
    "payer": {
        "name": "João Silva",
        "document": "12345678900",
        "email": "joao@email.com"
    },
    "amount": 10000,
    "netAmount": 9900,
    "fee": 100,
    "endToEndId": "E12345678202301011234abcdefghijkl",
    "postbackUrl": "https://seusite.com/webhooks/cash",
    "createdAt": "2026-10-23 02:11:02",
    "updatedAt": "2026-10-23 02:11:02"
}

💸 Cash-Out: Saques e Transferências

Webhooks enviados quando o status de um saque/transferência muda.

Fluxo de Status

Em caso de erro: failed, refused, returned ou cancelled

Eventos e Status

Status	Evento	Descrição	Webhook
pending_approval	Saque solicitado	Saque criado, aguardando aprovação	—
scheduled	Saque agendado	Saque agendado para processamento	ENVIA
processing	Processando transferência	Transferência em processamento no banco	ENVIA
transferred	Transferência concluída	Valor transferido com sucesso para a conta destino	ENVIA
returned	Transferência devolvida	Valor devolvido (conta destino inválida ou rejeitada)	ENVIA
cancelled	Saque cancelado	Saque cancelado antes do processamento	ENVIA
refused	Saque recusado	Saque recusado pelo banco ou sistema	ENVIA
failed	Falha na transferência	Erro no processamento pelo banco/BaaS	ENVIA

Campos do Payload

Campo	Tipo	Descrição
id	string	Hash único do saque
amount	integer	Valor solicitado em centavos
fee	integer	Taxa de transferência em centavos
description	string|null	Descrição/mensagem do saque
status	string	Status atual da transferência
statusLabel	string	Label do status em português
type	string	Tipo da transferência (pix, ted)
approvedIn	datetime|null	Data de aprovação (se aplicável)
createdAt	datetime	Data de criação do saque
updatedAt	datetime	Data da última atualização

Exemplo de Payload

{
    "id": "wth_01HXXXXXXXXXXXXXXXXX",
    "amount": 50000,
    "fee": 200,
    "description": "Saque para conta bancária",
    "status": "transferred",
    "statusLabel": "Transferido",
    "type": "pix",
    "approvedIn": "2026-10-23 02:11:02",
    "createdAt": "2026-10-23 02:11:02",
    "updatedAt": "2026-10-23 02:11:02"
}

📋 Informações Técnicas

Headers Enviados

Header	Valor
Content-Type	application/json
Accept	application/json

Boas Práticas

• Use HTTPS na URL do webhook
• Responda rapidamente (menos de 30 segundos)
• Retorne status 2xx para confirmar recebimento
• Implemente idempotência (webhooks podem ser reenviados)