Copy page

Pagamento por Referência

Webhooks de Comerciante

Webhooks de Comerciante

A IZI Pay pode notificar o seu sistema quando um pagamento por referência é pago com sucesso. A notificação é enviada como um pedido HTTP POST para o URL de webhook configurado na sua conta de comerciante.

Para ativar este serviço, forneça à IZI Pay o URL completo de callback hospedado pelo seu sistema e um Access-Key escolhido ou gerado por si. A IZI Pay irá incluir esse mesmo Access-Key em todos os pedidos de notificação de pagamento PPR.

Pedido

A IZI Pay envia a notificação para o URL configurado usando POST.

http
POST https://seu-dominio.com/your-ppr-webhook-path
Content-Type: application/json
Access-Key: <a-sua-chave-de-acesso>

Apenas o cabeçalho Access-Key é usado para este webhook. A IZI Pay não envia cabeçalho de tipo de evento nem cabeçalho de assinatura nos webhooks de pagamento por referência.

O seu endpoint deve validar o Access-Key antes de processar o pedido. A chave não é gerada pela IZI Pay; é o valor que o comerciante fornece à IZI Pay durante a configuração do webhook.

Corpo do Pedido

O corpo do pedido é JSON. Os nomes dos campos são fixos e sensíveis a maiúsculas/minúsculas.

json
{
  "idTransacao": "00000",
  "numLogSistema": "12967628",
  "idLogSistema": "8588",
  "dataTransaccaoCliente": "2026-06-08T11:52:56",
  "montantePago": 20.00,
  "tipoTerminal": "M",
  "iIdentTerminal": "0000000000",
  "localidadeTerminal": "Internet ",
  "refPagamento": "744757420",
  "nib": null,
  "banco": null,
  "Id": "f6701cf7-7fb8-4321-b4a1-eb5138ec9f88"
}

Campo	Tipo	Descrição
idTransacao	string	Identificador da transação.
numLogSistema	string	Número de log do sistema associado à notificação de pagamento.
idLogSistema	string	Identificador de período/log do sistema.
dataTransaccaoCliente	string	Data e hora em que o pagamento do cliente foi registado.
montantePago	number	Montante pago pelo cliente.
tipoTerminal	string	Tipo de terminal usado no pagamento.
iIdentTerminal	string	Identificador do terminal.
localidadeTerminal	string	Localidade do terminal.
refPagamento	string	Referência de pagamento paga pelo cliente.
nib	string/null	NIB da conta debitada, quando disponível.
banco	string/null	Nome do banco, quando disponível.
Id	string	Identificador único da notificação. Use este valor para idempotência.

Resposta Esperada

O seu endpoint deve devolver JSON válido.

json
{
  "Success": true,
  "Obs": "Pagamento processado com sucesso",
  "Id": "id-interno-do-seu-pagamento"
}

Campo	Tipo	Descrição
Success	boolean	Devolva true quando a notificação for processada com sucesso.
Obs	string	Nota curta sobre o processamento.
Id	string	O identificador interno do pagamento no seu sistema, quando disponível.

Notificações Duplicadas

O seu endpoint deve ser idempotente. A mesma notificação pode ser enviada mais de uma vez, por exemplo quando o seu endpoint demora demasiado a responder ou devolve uma resposta inválida.

Use o campo Id do pedido como chave principal de idempotência. Se o mesmo Id já tiver sido processado com sucesso, não crie um segundo registo de pagamento. Devolva Success: true novamente.

json
{
  "Success": true,
  "Obs": "Pagamento já processado",
  "Id": "id-interno-do-seu-pagamento"
}

Resultado da Entrega

A IZI Pay considera o webhook entregue apenas quando o seu endpoint devolve:

• código HTTP 2xx;
• JSON válido;
• Success: true.

A entrega é considerada falhada quando o endpoint devolve um estado diferente de 2xx, excede o tempo limite, devolve JSON inválido, omite Success ou devolve Success: false.

Fluxo Recomendado

1. Receba o pedido POST.
2. Valide o cabeçalho Access-Key.
3. Verifique se a notificação Id já foi processada.
4. Registe ou atualize o pagamento no seu sistema.
5. Devolva Success: true.