Skip to main content
Webhooks permitem que sua aplicação receba notificações assíncronas quando eventos relevantes ocorrem (por exemplo, a liquidação de um pagamento ou a mudança de status de um KYC).
Os nomes de eventos e o formato exato do payload dependem da configuração da sua conta. Confirme os campos disponibilizados no painel do PagFinance ou com o suporte antes de ir para produção.

​
Como funciona

1

Configurar o endpoint

Cadastre uma URL HTTPS da sua aplicação para receber os eventos.
2

Receber o evento

O PagFinance envia uma requisição POST com o payload do evento para a sua URL.
3

Responder rapidamente

Responda 2xx o mais rápido possível. Processe a lógica pesada de forma assíncrona.
4

Tratar reenvios

Em falha ou timeout, o evento pode ser reenviado. Trate os eventos de forma idempotente.

​
Tipos de evento

​
evento
Um pagamento foi criado.
​
evento
A transação on-chain do pagamento foi submetida.
​
evento
O pagamento foi liquidado na moeda local (PIX, boleto ou giftcard).
​
evento
O pagamento falhou ou foi rejeitado.
​
evento
O status de uma verificação de KYC mudou.

​
Exemplo de payload

​
Boas práticas

Idempotência

Use o identificador do evento para evitar processamento duplicado em reenvios.

Verificação

Valide a autenticidade da requisição (assinatura ou segredo compartilhado) antes de confiar no payload.

Resposta rápida

Responda 2xx imediatamente e processe em background.

HTTPS

Exponha apenas endpoints HTTPS para receber eventos.
Esta seção descreve o comportamento típico de webhooks do PagFinance. Os eventos e campos exatos devem ser confirmados com a documentação operacional da sua conta.