Copy page

Payment by Reference

Merchant Webhooks

Merchant Webhooks

IZI Pay can notify your system when a payment by reference is successfully paid. The notification is sent as an HTTP POST request to the webhook URL configured for your merchant account.

To enable this, provide IZI Pay with the full callback URL hosted by your system and an Access-Key chosen or generated by you. IZI Pay will include that same Access-Key in every PPR payment notification request.

Request

IZI Pay sends the notification to your configured URL using POST.

http
POST https://your-domain.com/your-ppr-webhook-path
Content-Type: application/json
Access-Key: <your-merchant-access-key>

Only the Access-Key header is used for this webhook. IZI Pay does not send an event type header or a signature header for payment reference webhooks.

Your endpoint should validate the Access-Key before processing the request. The key is not generated by IZI Pay; it is the value you give to IZI Pay during webhook setup.

Request Body

The request body is JSON. Field names are fixed and case-sensitive.

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"
}

Field	Type	Description
idTransacao	string	Transaction identifier.
numLogSistema	string	System log number associated with the payment notification.
idLogSistema	string	System period/log identifier.
dataTransaccaoCliente	string	Date and time when the customer payment was registered.
montantePago	number	Amount paid by the customer.
tipoTerminal	string	Terminal type used for the payment.
iIdentTerminal	string	Terminal identifier.
localidadeTerminal	string	Terminal location.
refPagamento	string	Payment reference paid by the customer.
nib	string/null	Debit account NIB, when available.
banco	string/null	Bank name, when available.
Id	string	Unique notification identifier. Use this value for idempotency.

Expected Response

Your endpoint must return valid JSON.

json
{
  "Success": true,
  "Obs": "Payment processed successfully",
  "Id": "your-internal-payment-id"
}

Field	Type	Description
Success	boolean	Return true when the notification was processed successfully.
Obs	string	Short processing note.
Id	string	Your internal payment identifier, when available.

Duplicate Notifications

Your endpoint must be idempotent. The same notification can be sent more than once, for example when your endpoint times out or returns an invalid response.

Use the request field Id as the main idempotency key. If the same Id was already processed successfully, do not create a second payment record. Return Success: true again.

json
{
  "Success": true,
  "Obs": "Payment already processed",
  "Id": "your-internal-payment-id"
}

Delivery Result

IZI Pay considers the webhook delivered only when your endpoint returns:

• an HTTP 2xx status code;
• valid JSON;
• Success: true.

The delivery is considered failed when the endpoint returns a non-2xx status, times out, returns invalid JSON, omits Success, or returns Success: false.

Recommended Processing Flow

1. Receive the POST request.
2. Validate the Access-Key header.
3. Check whether the notification Id was already processed.
4. Register or update the payment in your system.
5. Return Success: true.