Visão Geral
Este guia apresenta os diferentes cenários de payload que podem ser enviados via Webhook pela Pronttus, com base no tipo de operação configurado.
Cada tipo de evento é projetado para permitir integrações rápidas, rastreáveis e seguras. Certifique-se de validar o campo event e processar o payload conforme o tipo de operação.
Estrutura Padrão
Todos os webhooks seguem esta estrutura base:
{
"webhook_id": "string",
"event": "transactions.credit | transactions.debit | transactions.refunded",
"data": {
// Dados específicos do evento
}
}
Recebimento (Cash In)
transactions.credit
Este evento é disparado quando há um recebimento via PIX na sua conta. O payload inclui detalhes da transação, dados do pagador e do recebedor.
Exemplo de Payload - Sucesso
{
"webhook_id": "f8abc23c4c4d68c60e796353744c2a2892990ff09b97a37123d4c549882db483",
"event": "transactions.credit",
"data": {
"id": "740b60d5-9bf4-4a4d-901c-396ac860f573",
"status": "COMPLETED",
"amount": 5000,
"currency_code": "BRL",
"method": "pix",
"operation": "pix.cash_in",
"pix": {
"end_to_end_id": "E18236120202506220437s06b731c46a",
"tx_id": "522dfc1ec7418fae15af966aab4c7a"
},
"payer": {
"name": "John Doe",
"document": "12345678910",
"ispb": "00000001",
"account_number": "00000000000000000000",
"account_type": "00000000000000000000"
}
}
}
Campos do Payload
Hash único do webhook para rastreamento
Sempre transactions.credit para recebimentos
Status da transação: COMPLETED
Valor em centavos (5000 = R$ 50,00)
Tipo de operação: pix.cash_in
ID fim-a-fim do PIX (identificador único do Banco Central)
Dados completos do pagador (nome, documento, ISPB, conta)
Use este evento para liberar produtos, enviar e-mails de confirmação, atualizar status de pedidos, etc.
Reembolso (Refund)
transactions.refunded
Evento de reembolso de uma transação PIX previamente realizada. Indica que o valor foi devolvido ao pagador.
Exemplo de Payload - Sucesso
{
"webhook_id": "ac4db6f2cde84c3c6a563ccbfb120ac8554dadb339c1b67f29e186973ac0b94d",
"event": "transactions.refunded",
"data": {
"id": "3e02ee0e-2ec5-41d2-bae0-0c3d2bab8985",
"status": "REFUNDED",
"amount": 1999,
"currency_code": "BRL",
"method": "pix",
"operation": "pix.refund",
"pix": {
"end_to_end_id": "D487561212025103020598IPTgNEbVkO"
},
"receiver": {
"name": "John Doe",
"document": "12345678910",
"ispb": "00000001",
"account_number": "00000000000000000000",
"account_type": "00000000000000000000"
}
}
}
Campos do Payload
Sempre transactions.refunded para reembolsos
Status do reembolso: REFUNDED
Tipo de operação: pix.refund
ID fim-a-fim do PIX associado ao reembolso
Dados do destinatário da devolução (nome, documento, ISPB, conta)
Use este evento para atualizar o status do pedido, estornar comissões e notificar o cliente sobre o reembolso.
Transferência (Cash Out)
transactions.debit
Evento de saída de valores da conta. Representa um débito e contém os dados das contas envolvidas.
Exemplo de Payload - Sucesso
{
"webhook_id": "84525845d10ead2473c4926b70fec85bb36ae983efe9e7c536de9d8472d1bb5c",
"event": "transactions.debit",
"data": {
"id": "07c21b7b-9ed5-4912-9022-462c5db6559a",
"status": "COMPLETED",
"amount": 15000,
"currency_code": "BRL",
"method": "pix",
"operation": "pix.cash_out",
"pix": {
"end_to_end_id": "E3186100520250622201431236a2aad6",
"tx_id": "PE202506220000356266"
},
"receiver": {
"name": "John Doe",
"document": "12345678910",
"ispb": "18236120",
"account_number": "00000000000000000000",
"account_type": "00000000000000000000"
}
}
}
Campos do Payload
Sempre transactions.debit para transferências
Status da transação: COMPLETED ou FAILED
Tipo de operação: pix.cash_out
Dados completos do destinatário (nome, documento, ISPB, conta)
A estrutura é similar ao recebimento, mas usa receiver em vez de payer e o event é transactions.debit.
Erro em Transferência (Cash Out Error)
Disparado quando há falha no processo de transferência, como saldo insuficiente ou chave PIX inválida.
Exemplo 1: Saldo Insuficiente
{
"webhook_id": "84525845d10ead2473c4926b70fec85bb36ae983efe9e7c536de9d8472d1bb5c",
"event": "transactions.debit",
"data": {
"id": "07c21b7b-9ed5-4912-9022-462c5db6559a",
"status": "FAILED",
"amount": 15000,
"currency_code": "BRL",
"method": "pix",
"operation": "pix.cash_out",
"failure_reason": "Saldo insuficiente"
}
}
Exemplo 2: Chave PIX Não Encontrada
{
"webhook_id": "84525845d10ead2473c4926b70fec85bb36ae983efe9e7c536de9d8472d1bb5c",
"event": "transactions.debit",
"data": {
"id": "07c21b7b-9ed5-4912-9022-462c5db6559a",
"status": "FAILED",
"amount": 15000,
"currency_code": "BRL",
"method": "pix",
"operation": "pix.cash_out",
"failure_reason": "Chave Pix não encontrada"
}
}
Campos de Erro
Sempre FAILED para transações com erro
Descrição legível do motivo da falha
Quando o status é FAILED, os campos pix e receiver podem não estar presentes no payload.
Próximos Passos
