Notificação de pagamento via Webhook — PIX (LC Pay)

Este documento descreve como o LC Pay notifica o seu sistema, em tempo real, quando um
PIX gerado através da nossa API é pago. A notificação permite que você concilie o
pagamento automaticamente, sem precisar ficar consultando o status da transação.

Aplica-se tanto ao PIX dinâmico/imediato (sem data de vencimento, gerado via integração
de PDV) quanto ao PIX com vencimento (cobrança).

Visão geral

1. Você gera um PIX na API do LC Pay, informando a sua URL de callback.
2. O LC Pay devolve um transactionId e o QR Code / copia-e-cola.
3. O pagador paga o PIX.
4. O LC Pay envia um POST para a sua URL de callback avisando do pagamento.
5. O seu sistema confirma o recebimento respondendo HTTP 2xx.

1. Como ativar a notificação

A notificação é ativada por transação: basta informar a sua URL de callback no momento
em que o PIX é criado, no campo urlCallBackIntegrador.

Exemplo de geração de um PIX dinâmico:

{
  "valorTotal": 149.90,
  "numeroPedido": "PEDIDO-2026-0042",
  "conteudo": "Venda balcão - Loja Centro",
  "urlCallBackIntegrador": "https://seu-sistema.com.br/webhooks/pix"
}

Resposta (trecho relevante):

{
  "data": {
    "transactionId": "b2f7c1e0-9a3d-4c11-8e5a-1f2d3c4b5a6e",
    "instantPayment": {
      "textContent": "00020126580014br.gov.bcb.pix...6304ABCD",
      "dynamicQrCodeType": "IMMEDIATE"
    }
  }
}

Guarde o transactionId. Ele é a chave que identifica a transação e que será
devolvida na notificação de pagamento.

Observações:

Se o campo urlCallBackIntegrador não for informado (ou vier vazio), o PIX é gerado
normalmente, mas nenhuma notificação será enviada quando ele for pago.

Use sempre uma URL HTTPS válida e acessível publicamente.

2. A requisição de notificação

Quando o pagamento é confirmado, o LC Pay envia uma requisição para a sua URL de callback.

Método: POST

Corpo (body): vazio — todas as informações são enviadas nos cabeçalhos (headers).

Cabeçalhos enviados

Cabeçalho	Descrição
`webhook-event-type`	Tipo do evento. Atualmente: `pix.payment` (pagamento de PIX confirmado).
`webhook-transaction-id`	O `transactionId` da transação — use-o para conciliar o pagamento.
`webhook-external-code`	Código externo da cobrança. Preenchido no PIX com vencimento; vazio no PIX dinâmico/imediato.
`X-Api-Key`	Chave de autenticação da notificação. Use-a para validar que a chamada partiu do LC Pay.
`Content-Type`	`application/json`

Exemplo

O valor real da X-Api-Key é fornecido pela equipe LC Pay no processo de integração e
não deve ser divulgado publicamente. Guarde-o de forma segura no seu sistema.

3. Como o seu sistema deve responder

Responda com um status HTTP 2xx (por exemplo, 200 OK) assim que receber a notificação.

Uma resposta 2xx sinaliza ao LC Pay que a notificação foi entregue com sucesso.

Qualquer outra resposta (4xx, 5xx), timeout ou erro de conexão faz a notificação entrar
na fila de reenvio automático (veja a seção seguinte).

Boas práticas

Valide a X-Api-Key antes de processar a notificação, descartando chamadas com chave
divergente.

Trate a notificação de forma idempotente, usando o webhook-transaction-id como chave.
A mesma notificação pode ser recebida mais de uma vez (por exemplo, em cenários de reenvio),
e o seu sistema deve processá-la uma única vez por transactionId.

Responda rápido. Faça o processamento pesado de forma assíncrona; devolva o 2xx primeiro.

4. Política de reenvio (retry)

Se a entrega falhar (resposta não-2xx, timeout ou erro de rede), o LC Pay reenvia a
notificação automaticamente:

Novas tentativas a cada 1 minuto, aproximadamente.

Até 30 tentativas.

Após esgotar as tentativas, a notificação é marcada como falha e não é mais reenviada.

Por isso é importante que a sua URL de callback esteja disponível e responda 2xx o quanto antes.

5. Segurança — recomendações

Exponha a URL de callback apenas via HTTPS.

Autentique cada chamada validando o cabeçalho X-Api-Key.

Não confie apenas no recebimento: mantenha a lógica idempotente por transactionId.

Se suspeitar que a sua X-Api-Key foi exposta, solicite a rotação à equipe LC Pay.

6. Resumo

Etapa	O que acontece
Criação do PIX	Você informa `urlCallBackIntegrador` e recebe o `transactionId`.
Pagamento	O pagador paga o PIX.
Notificação	LC Pay faz `POST` na sua URL, com os dados nos cabeçalhos.
Confirmação	Seu sistema responde `2xx`.
Falha na entrega	LC Pay reenvia automaticamente (≈1 min, até 30 vezes).

Notificação de pagamento via Webhook — PIX (LC Pay)

Visão geral#

1. Como ativar a notificação#

2. A requisição de notificação#

Cabeçalhos enviados#

Exemplo#

3. Como o seu sistema deve responder#

Boas práticas#

4. Política de reenvio (retry)#

5. Segurança — recomendações#

6. Resumo#