Webhooks & Notificações em Tempo Real

A KavroPay utiliza webhooks assíncronos e de alta confiabilidade para notificar seu servidor no momento exato em que transações mudam de estado (pagamentos aprovados, expirações de QR Code ou reembolsos).

Webhooks Globais

Cadastrados via painel ou API (POST /v1/webhooks) para escutar todos os eventos da conta (cobranças e saques).

Webhooks por Cobrança (notification_url)

Passados diretamente no parâmetro notification_url da cobrança. Ficam isolados com escopo estrito à transação (tx:<id>) e utilizam segredo criptográfico próprio (notification_secret).

Eventos Suportados

Evento (`event`)	Status da Transação	Descrição
`payment.paid`	`paid`	Cobrança PIX paga e liquidada com sucesso pelo Banco Central. Saldo liberado instantaneamente na conta.
`payment.confirmed`	`paid`	Alias canônico de `payment.paid`. Ambos são idênticos e representam a confirmação de liquidação.
`payment.expired`	`expired`	O prazo limite do QR Code (`expires_at`) venceu sem pagamento pelo pagador.
`payment.refunded`	`refunded`	Pagamento PIX foi reembolsado/estornado (via devolução ou resolução de disputa MED).
`withdrawal.completed`	`paid_out`	Transferência PIX de saque entregue com sucesso à chave PIX de destino.
`withdrawal.failed`	`failed`	Saque rejeitado pelo banco receptor (valor e taxa estornados na carteira).

Qual é a diferença entre payment.confirmed e payment.paid?No PIX (Sistema de Pagamentos Instantâneos do Banco Central do Brasil), a liquidação entre instituições financeiras ocorre em tempo real no SPI. Não existe o fluxo de cartão de crédito (onde há pré-autorização e posterior captura). Portanto, payment.paid e payment.confirmed representam exatamente o mesmo evento: o PIX foi pago e liquidado. Ambos os eventos são suportados e podem ser selecionados no painel ou via API.

Identificação do Ambiente (Sandbox vs Produção)

Para que seu sistema identifique com total segurança se o webhook recebido é de teste (Sandbox) ou transação real (Produção), a KavroPay disponibiliza duas formas nativas:

Pelo Cabeçalho HTTP:
- X-Kavro-Environment: sandbox (para cobranças geradas com chave kvk_test_...)
- X-Kavro-Environment: live (para cobranças geradas com chave kvk_live_...)
Pelo Payload JSON:
- "environment": "sandbox" ou "environment": "live"
- "livemode": false (Sandbox) ou "livemode": true (Produção)

Cabeçalhos Enviados em Cada Webhook

Todas as requisições enviadas pela KavroPay para a sua URL de notificação contêm os seguintes cabeçalhos HTTP:

POST /seu-endpoint-de-webhook HTTP/1.1
Host: seu-dominio.com.br
Content-Type: application/json
User-Agent: KavroPay-Webhook/1.0
X-Kavro-Event: payment.paid
X-Kavro-Signature: t=1729034291,v1=9f82c3d4e5f6...
X-Kavro-Timestamp: 1729034291
X-Kavro-Delivery-Id: del_a1b2c3d4-e5f6-7890-abcd-ef1234567890
X-Kavro-Environment: live

Para garantir máxima compatibilidade com bibliotecas e versões anteriores, a KavroPay também envia em paralelo os headers minúsculos x-kavropay-signature e x-kavropay-event. Veja o guia completo em Validação de Assinatura HMAC.

Payloads dos Eventos

1. Pagamento Confirmado (`payment.paid` / `payment.confirmed`)

Disparado no instante em que o cliente conclui o pagamento do PIX no banco dele.

{
  "event": "payment.paid",
  "id": "PAY8829F1A4BC912D",
  "amount": 149.90,
  "fee": 0.50,
  "net": 149.40,
  "status": "paid",
  "externalId": "pedido_84920",
  "external_reference": "pedido_84920",
  "end_to_end_id": "E12345678202610152130abc123def456",
  "paid_at": "2026-10-15T21:30:45.000Z",
  "environment": "live",
  "livemode": true,
  "customer": {
    "id": "cus_99182371a",
    "name": "Mariana Costa Ribeiro",
    "document": "52998224725",
    "email": "mariana.ribeiro@email.com",
    "phone": "11987654321"
  },
  "metadata": {
    "order_id": "pedido_84920",
    "sku": "prod_curso_2026"
  }
}

2. Cobrança Expirada (`payment.expired`)

Disparado quando o tempo de tolerância (expires_at) do QR Code se esgota sem que o pagamento tenha sido efetuado.

{
  "event": "payment.expired",
  "id": "PAY8829F1A4BC912D",
  "amount": 149.90,
  "fee": 0.50,
  "net": 149.40,
  "status": "expired",
  "externalId": "pedido_84920",
  "external_reference": "pedido_84920",
  "expired_at": "2026-10-15T21:21:14.000Z",
  "environment": "sandbox",
  "livemode": false,
  "customer": {
    "id": "cus_99182371a",
    "name": "Mariana Costa Ribeiro",
    "document": "52998224725",
    "email": "mariana.ribeiro@email.com",
    "phone": "11987654321"
  },
  "metadata": {
    "order_id": "pedido_84920"
  }
}

3. Pagamento Reembolsado (`payment.refunded`)

Disparado quando uma cobrança anteriormente paga passa pelo processo de reembolso ou estorno MED.

{
  "event": "payment.refunded",
  "id": "PAY8829F1A4BC912D",
  "amount": 149.90,
  "fee": 0.50,
  "net": 149.40,
  "status": "refunded",
  "externalId": "pedido_84920",
  "external_reference": "pedido_84920",
  "refunded_at": "2026-10-15T21:45:00.000Z",
  "environment": "live",
  "livemode": true,
  "customer": {
    "id": "cus_99182371a",
    "name": "Mariana Costa Ribeiro",
    "document": "52998224725",
    "email": "mariana.ribeiro@email.com",
    "phone": "11987654321"
  },
  "metadata": {
    "order_id": "pedido_84920"
  }
}

4. Saque PIX Concluído (`withdrawal.completed`)

Disparado quando uma solicitação de retirada/saque (POST /v1/withdrawals) é processada e o Banco Central confirma o depósito na conta de destino.

{
  "event": "withdrawal.completed",
  "id": "WIT91283912AA",
  "amount": 500.00,
  "fee": 1.50,
  "net": 498.50,
  "status": "paid_out",
  "pix_key": "12345678909",
  "pix_key_type": "CPF",
  "beneficiary_document": "12345678909",
  "end_to_end_id": "E12345678202610152150abc123def789",
  "created_at": "2026-10-15T21:49:00.000Z",
  "environment": "live",
  "livemode": true
}

Política de Retentativas (Retry Policy)

Caso seu servidor retorne status HTTP diferente de 2xx (como 500, 502, 504 ou timeout), a KavroPay aciona uma política de retentativa com backoff exponencial:

Total de tentativas: até 18 retentativas.
Intervalo: de 15 segundos até horas, cobrindo até 72 horas de tentativas.
Resposta esperada: Seu endpoint deve responder com HTTP 200 ou 204 em menos de 10 segundos.

Primeiros Passos

Endpoints API

Infraestrutura

Referência

Webhooks & Notificações em Tempo Real

Webhooks Globais

Webhooks por Cobrança (notification_url)

Eventos Suportados

Identificação do Ambiente (Sandbox vs Produção)

Cabeçalhos Enviados em Cada Webhook

Payloads dos Eventos

1. Pagamento Confirmado (`payment.paid` / `payment.confirmed`)

2. Cobrança Expirada (`payment.expired`)

3. Pagamento Reembolsado (`payment.refunded`)

4. Saque PIX Concluído (`withdrawal.completed`)

Política de Retentativas (Retry Policy)

Webhooks Globais

Webhooks por Cobrança (notification_url)

Eventos Suportados

Identificação do Ambiente (Sandbox vs Produção)

Cabeçalhos Enviados em Cada Webhook

Payloads dos Eventos

1. Pagamento Confirmado (payment.paid / payment.confirmed)

2. Cobrança Expirada (payment.expired)

3. Pagamento Reembolsado (payment.refunded)

4. Saque PIX Concluído (withdrawal.completed)

Política de Retentativas (Retry Policy)

1. Pagamento Confirmado (`payment.paid` / `payment.confirmed`)

2. Cobrança Expirada (`payment.expired`)

3. Pagamento Reembolsado (`payment.refunded`)

4. Saque PIX Concluído (`withdrawal.completed`)