COMECE AQUI

Webhooks

Webhooks permitem que sua aplicação receba notificações em tempo real sobre eventos que ocorrem na plataforma ValidaPay. Ao configurar uma URL de webhook, enviaremos uma requisição POST com o payload do evento sempre que ele ocorrer.

Como funciona

Configure a URL de webhook no painel em https://app.validapay.com.br/integracao/webhooks

Quando um evento ocorre, enviamos um POST para sua URL com o payload em JSON.

Sua aplicação deve responder com status 200 para confirmar o recebimento.

Eventos disponíveis

Evento	Descrição
`payment.success`	Disparado quando um pagamento é confirmado com sucesso.

Documentação em andamento

Os eventos abaixo já estão disponíveis para uso na API. A documentação detalhada com exemplos de payload será adicionada em breve:

payment.failedsubscription.createdsubscription.activatedsubscription.canceledsubscription.renewedsubscription.trial

payment.success

Disparado quando um pagamento é confirmado com sucesso.

Campos do payload

Campo	Tipo	Descrição
event	`string`	Tipo do evento
chargeId	`string`	Identificador da cobrança
amount	`number`	Valor pago
paymentMethod	`string`	Método de pagamento utilizado
paymentId	`string`	Identificador do pagamento (End-to-End ID para Pix)
paidAt	`string`	Data e hora do pagamento (ISO 8601)
payer.name	`string`	Nome do pagador
payer.taxId	`string`	CPF/CNPJ do pagador
payer.bank	`string`	Código do banco do pagador
payer.account	`string`	Número da conta do pagador
payer.branch	`string`	Agência do pagador
payer.accountType	`string`	Tipo da conta (CACC = Conta Corrente, SVGS = Poupança)

Exemplo de payload

{
  "event": "payment.success",
  "chargeId": "cha_1771453171013_fp6iocaxb",
  "amount": 150,
  "paymentMethod": "PIX",
  "paymentId": "E1234567820260215120000000000001",
  "paidAt": "2026-02-15T15:30:00.000Z",
  "payer": {
    "name": "Issac Newton",
    "taxId": "12345678900",
    "bank": "260",
    "account": "12345678",
    "branch": "0001",
    "accountType": "CACC"
  }
}