Eventos de webhook

A INFI usa nomes de evento canônicos e estáveis. O nome é entregue no header X-Infi-Event e no campo event do corpo, sempre no mesmo formato (lowercase, com pontos).

Compare por igualdade exata

Os nomes de evento listados abaixo são estáveis entre versões. Você pode comparar diretamente: if (req.headers['x-infi-event'] === 'transaction.paid') { ... }. Sem necessidade de normalização.

Cobranças PIX (`type: "transaction"`)

Eventos do ciclo de uma cobrança recebida.

Evento	Quando ocorre
`transaction.paid`	Pagamento confirmado e creditado em saldo.
`transaction.failed`	Falha no pagamento (timeout, recusa do pagador).
`transaction.cancelled`	Cobrança cancelada antes do pagamento.
`transaction.expired`	Prazo expirou sem pagamento.
`transaction.refunded`	Estorno total. Saldo do lojista debitado.
`transaction.partially_refunded`	Estorno parcial.
`transaction.infraction`	MED (Mecanismo Especial de Devolução) aberto — saldo bloqueado preventivamente.
`transaction.dispute`	Disputa aberta pelo pagador.
`transaction.protest`	Protesto registrado contra a transação.
`transaction.blocked`	Fundos bloqueados por ordem judicial ou compliance.
`transaction.chargeback`	Chargeback aplicado — saldo debitado em definitivo.

Saques PIX (`type: "transfer"`)

Eventos do ciclo de uma transferência (saque) iniciada pela sua API key ou pelo painel.

Evento	Quando ocorre
`transfer.created`	Saque criado, aguardando processamento.
`transfer.processing`	Saque em processamento no banco.
`transfer.pending_approval`	Saque acima do limite — aguarda aprovação manual interna.
`transfer.approved`	Saque aprovado manualmente, segue para processamento.
`transfer.rejected`	Saque rejeitado manualmente. Saldo devolvido.
`transfer.paid`	Saque concluído com sucesso.
`transfer.failed`	Saque falhou (chave PIX inválida, etc.). Saldo devolvido.
`transfer.cancelled`	Saque cancelado antes do processamento. Saldo devolvido.
`transfer.refunded`	Destinatário devolveu o valor (PIX Reversal). Saldo re-creditado.
`transfer.partially_refunded`	Destinatário devolveu parte do valor. Saldo re-creditado proporcionalmente.

Headers em todo POST

Header	Descrição
`X-Infi-Event`	Nome canônico do evento (ex.: `transaction.paid`).
`X-Infi-Timestamp`	Unix timestamp em segundos, parte da assinatura.
`X-Infi-Signature`	`sha256=<hex>` — HMAC-SHA256 sobre `${timestamp}.${rawBody}`. Veja Assinatura.
`X-Infi-Event-Id`	ID único do evento (`evt_<ts>_<rand>`). Use para dedupe entre múltiplas URLs e reenvios manuais.

Campos opcionais (PIX)

Em eventos onde o pagamento foi efetivamente liquidado, o webhook traz dados do PIX vindos da rede SPI/BACEN:

Campo	Onde aparece	Conteúdo
`endToEndId`	`transaction.paid` / `transaction.refunded` / `transaction.partially_refunded` / `transfer.paid` / `transfer.refunded` / `transfer.partially_refunded`	E2E ID padrão BACEN (formato `E<ISPB><YYYYMMDDhhmm><id>`). Único por PIX.
`payer`	`transaction.*` (PIX recebido — quem pagou você)	Objeto com `name`, `document`, `documentType` e `bankAccount`.
`beneficiary`	`transfer.*` (PIX enviado — quem recebeu seu saque)	Objeto com `name`, `document`, `documentType` e `bankAccount`.
`refundEndToEndId`	`transfer.refunded` / `transfer.partially_refunded` apenas	E2E ID do PIX de devolução (diferente do `endToEndId` do PIX original).

Estrutura de payer e beneficiary:

{
  "name": "Maria Santos",
  "document": "98765432100",
  "documentType": "cpf",
  "bankAccount": {
    "ispb": "18236120",
    "branch": "1",
    "account": "914453272"
  }
}

Privacidade (LGPD)

Os campos payer.* e beneficiary.* contêm dados pessoais (nome, CPF/CNPJ, conta bancária). Trate-os como qualquer dado pessoal: armazene apenas o necessário, com acesso restrito, e respeite o direito de exclusão do titular. A INFI entrega esses dados porque eles vêm da rede PIX — você é o controlador do tratamento posterior.

Eventos que não trazem esses campos: transaction.failed, transaction.cancelled, transaction.expired, transfer.created, transfer.processing, transfer.pending_approval, transfer.approved, transfer.rejected, transfer.failed, transfer.cancelled. Os campos são omitidos do JSON quando não disponíveis (não vêm como null).

Exemplo: `transaction.paid`

{
  "event": "transaction.paid",
  "eventId": "evt_1715000000000_abcdef12",
  "transactionId": "Q4t9aV...",
  "status": "paid",
  "amountCents": 1000,
  "feeCents": 8,
  "netCents": 992,
  "paidAt": "2026-05-08T03:30:00.000Z",
  "timestamp": "1715000000",
  "endToEndId": "E18236120202605080330abc123",
  "payer": {
    "name": "Maria Santos",
    "document": "98765432100",
    "documentType": "cpf",
    "bankAccount": {
      "ispb": "18236120",
      "branch": "1",
      "account": "914453272"
    }
  }
}

Exemplo: `transaction.refunded`

{
  "event": "transaction.refunded",
  "eventId": "evt_1715003600000_def456",
  "transactionId": "Q4t9aV...",
  "status": "refunded",
  "amountCents": 1000,
  "feeCents": 8,
  "netCents": 992,
  "paidAt": null,
  "timestamp": "1715003600",
  "endToEndId": "E18236120202605080330abc123",
  "payer": {
    "name": "Maria Santos",
    "document": "98765432100",
    "documentType": "cpf",
    "bankAccount": {
      "ispb": "18236120",
      "branch": "1",
      "account": "914453272"
    }
  }
}

O saldo do estorno (parcial ou total) é debitado automaticamente do seu saldo INFI. Sem ação adicional. transaction.partially_refunded tem o mesmo schema.

Exemplo: `transfer.paid`

{
  "event": "transfer.paid",
  "eventId": "evt_1715000300000_345678ab",
  "transactionId": "...",
  "status": "paid",
  "amountCents": 5000,
  "feeCents": 4,
  "netCents": 4996,
  "paidAt": "2026-05-08T03:35:00.000Z",
  "timestamp": "1715000300",
  "endToEndId": "E04838403202605080335ABCDEF",
  "beneficiary": {
    "name": "João Silva",
    "document": "12345678901",
    "documentType": "cpf",
    "bankAccount": {
      "ispb": "18236120",
      "branch": "0001",
      "account": "123456789"
    }
  }
}

Exemplo: `transfer.refunded` (devolução de saque)

{
  "event": "transfer.refunded",
  "eventId": "evt_1715004000000_999",
  "transactionId": "...",
  "status": "transfer_refunded",
  "amountCents": 5000,
  "feeCents": 4,
  "netCents": 4996,
  "paidAt": null,
  "timestamp": "1715004000",
  "endToEndId": "E04838403202605080335ABCDEF",
  "refundEndToEndId": "D18236120202605080500abc789",
  "beneficiary": {
    "name": "João Silva",
    "document": "12345678901",
    "documentType": "cpf",
    "bankAccount": {
      "ispb": "18236120",
      "branch": "0001",
      "account": "123456789"
    }
  }
}

Quando o destinatário devolve um PIX que você enviou, o saldo é re-creditado automaticamente. transfer.partially_refunded tem o mesmo schema com amountCents igual ao valor parcialmente devolvido.

Exemplo: `transfer.failed`

{
  "event": "transfer.failed",
  "eventId": "evt_1715000600000_9abc1234",
  "transactionId": "...",
  "status": "failed",
  "amountCents": 5000,
  "feeCents": 4,
  "netCents": 4996,
  "paidAt": null,
  "timestamp": "1715000600"
}

Em saques que terminam em failed, cancelled ou rejected, o saldo é automaticamente devolvido. Sem ação adicional do seu lado além de marcar a operação. Esses eventos não trazem endToEndId nem beneficiary (não houve liquidação).

Categorias para multi-webhook

Você pode configurar uma URL por categoria ou misturar como quiser usando filtros de evento. Veja Configurando para o setup completo.

Categoria	Eventos cobertos
`cashin` (pagamentos)	`transaction.paid`, `transaction.failed`, `transaction.cancelled`, `transaction.expired`
`refund` (estornos)	`transaction.refunded`, `transaction.partially_refunded`
`dispute` (disputas / holds)	`transaction.infraction`, `transaction.dispute`, `transaction.protest`, `transaction.blocked`
`chargeback`	`transaction.chargeback`
`cashout` (saques)	`transfer.*` (todos os 10 eventos)

Configurando Assinatura HMAC

Eventos de webhook

Cobranças PIX (type: "transaction")

Saques PIX (type: "transfer")

Headers em todo POST

Campos opcionais (PIX)

Exemplo: transaction.paid

Exemplo: transaction.refunded

Exemplo: transfer.paid

Exemplo: transfer.refunded (devolução de saque)

Exemplo: transfer.failed