Create and manage PPR payment references.
List PPR references
Method and route: GET /api/references/ppr. Returns a paged list of PPR references, with optional filters for reference type and status.
query Parameters
pagePage number.
pageSizeNumber of records per page.
typeOptional PPR reference type filter.
statusOptional PPR reference status filter.
List PPR references › Responses
PPR references.
Create a PPR reference
Method and route: POST /api/references/ppr. Creates a PPR payment reference. Dynamic references are usually tied to a specific amount and customer, while charging references can be reused according to business rules. Merchant-defined values supplied in customMetadata are stored with the payment and returned by PPR creation, detail, and list endpoints.
Create a PPR reference › Request Body
reference^[0-9]{9,15}$Optional merchant-defined PPR reference containing 9 to 15 digits. Omit it to generate the reference automatically.
referenceTypeDynamic creates a fixed-amount reference. Charging creates a reusable reference and allows an open amount. Defaults to Dynamic when omitted.
amountRequired and greater than zero for Dynamic; optional for Charging, where 0 represents an open amount.
expiryDateOptional future expiry in ISO 8601 format.
descriptionOptional merchant-facing reason or label for the reference.
customerEmailOptional customer email stored with the reference.
customerNameOptional customer full name stored with the reference.
customerTelephoneOptional customer telephone number stored with the reference.
documentNumberOptional customer identity document number stored with the reference.
Optional merchant-defined JSON object for internal reconciliation and record linking.
This is the direct PPR endpoint form: send customMetadata at the request root for POST /api/references/ppr, /api/references/ppr/legacy, and each item in /api/references/ppr/bulk. Do not wrap it in metadata or custom.
Property names are chosen by the merchant. Values may be strings, numbers, booleans, arrays, nested objects, or null. The values do not affect PPR processing and are returned unchanged as customMetadata in creation, detail, and list responses.
Do not include credentials, card details, access tokens, or other secrets.
Create a PPR reference › Responses
PPR reference created.
referenceamountstatusreferenceStatusentityexpiresAtcreatedAtdescriptioncustomerEmailcustomerNamecustomerTelephonedocumentNumberA merchant-defined JSON object for linking an IZI Pay payment to records in your own systems.
Property names are chosen by the merchant; the example keys are illustrative and are not a fixed list. Each property may contain a JSON string, number, boolean, array, nested object, or null. Key spelling and casing are preserved.
IZI Pay stores these values without using them to control payment processing. They are returned as customMetadata by payment creation/detail/list and PPR creation/detail/list responses.
Use this object for internal identifiers such as invoice numbers, purchase orders, departments, customer codes, or source-system references. Do not include passwords, access tokens, card details, or other secrets.
Create a legacy PPR reference
Method and route: POST /api/references/ppr/legacy. Creates a PPR reference using the legacy integration path. Use this when the merchant or provider flow still depends on the legacy PPR contract.
Create a legacy PPR reference › Request Body
reference^[0-9]{9,15}$Optional merchant-defined PPR reference containing 9 to 15 digits. Omit it to generate the reference automatically.
referenceTypeDynamic creates a fixed-amount reference. Charging creates a reusable reference and allows an open amount. Defaults to Dynamic when omitted.
amountRequired and greater than zero for Dynamic; optional for Charging, where 0 represents an open amount.
expiryDateOptional future expiry in ISO 8601 format.
descriptionOptional merchant-facing reason or label for the reference.
customerEmailOptional customer email stored with the reference.
customerNameOptional customer full name stored with the reference.
customerTelephoneOptional customer telephone number stored with the reference.
documentNumberOptional customer identity document number stored with the reference.
Optional merchant-defined JSON object for internal reconciliation and record linking.
This is the direct PPR endpoint form: send customMetadata at the request root for POST /api/references/ppr, /api/references/ppr/legacy, and each item in /api/references/ppr/bulk. Do not wrap it in metadata or custom.
Property names are chosen by the merchant. Values may be strings, numbers, booleans, arrays, nested objects, or null. The values do not affect PPR processing and are returned unchanged as customMetadata in creation, detail, and list responses.
Do not include credentials, card details, access tokens, or other secrets.
Create a legacy PPR reference › Responses
Legacy PPR reference created.
referenceamountstatusreferenceStatusentityexpiresAtcreatedAtdescriptioncustomerEmailcustomerNamecustomerTelephonedocumentNumberA merchant-defined JSON object for linking an IZI Pay payment to records in your own systems.
Property names are chosen by the merchant; the example keys are illustrative and are not a fixed list. Each property may contain a JSON string, number, boolean, array, nested object, or null. Key spelling and casing are preserved.
IZI Pay stores these values without using them to control payment processing. They are returned as customMetadata by payment creation/detail/list and PPR creation/detail/list responses.
Use this object for internal identifiers such as invoice numbers, purchase orders, departments, customer codes, or source-system references. Do not include passwords, access tokens, card details, or other secrets.
Create bulk PPR references
Method and route: POST /api/references/ppr/bulk. Creates several PPR references in one request. Use it for batch billing workflows where many payable references need to be generated together.
Create bulk PPR references › Request Body
Create bulk PPR references › Responses
Bulk PPR references created.
Get PPR reference status
Method and route: GET /api/references/ppr/{pprReference}. Returns the current status of a PPR reference. Use this before showing a customer or merchant whether a reference is still pending, paid, canceled, or expired.
path Parameters
pprReferencePPR reference value.
Get PPR reference status › Responses
PPR reference status.
referenceamountstatusreferenceStatusentityexpiresAtcreatedAtdescriptioncustomerEmailcustomerNamecustomerTelephonedocumentNumberA merchant-defined JSON object for linking an IZI Pay payment to records in your own systems.
Property names are chosen by the merchant; the example keys are illustrative and are not a fixed list. Each property may contain a JSON string, number, boolean, array, nested object, or null. Key spelling and casing are preserved.
IZI Pay stores these values without using them to control payment processing. They are returned as customMetadata by payment creation/detail/list and PPR creation/detail/list responses.
Use this object for internal identifiers such as invoice numbers, purchase orders, departments, customer codes, or source-system references. Do not include passwords, access tokens, card details, or other secrets.
Cancel PPR reference
Get PPR reference history
Method and route: GET /api/references/ppr/{pprReference}/history. Returns the event history for a PPR reference. Use it to audit status changes and provider updates over time.
path Parameters
pprReferencePPR reference value.
Get PPR reference history › Responses
PPR reference history.
messageReceive PPR payment webhook
Merchant Callback Endpoint
The callback endpoint is an HTTPS URL hosted by the merchant and provided to the IZI Pay development team during setup. This is the endpoint where IZI Pay sends payment status updates and notifications.
Along with the callback URL, the merchant must also provide an Access-Key. IZI Pay includes this key in the request headers of every callback request so that the merchant can authenticate and validate incoming notifications.
The merchant is responsible for ensuring that the callback endpoint is publicly accessible and capable of receiving and processing requests from IZI Pay.
This callback applies to PPR references created through the current API.
Summary
During onboarding, the merchant must provide the following details to the IZI Pay development team:
- Callback URL: The HTTPS endpoint where IZI Pay will send payment status notifications.
- Access-Key: A secret value chosen and provided by the merchant. IZI Pay includes this value in the request headers of every callback request, allowing the merchant to verify that the notification originated from IZI Pay.
Headers
Access-KeyAccess key chosen or generated by the merchant for this webhook. IZI Pay sends this same value in the Access-Key header so your endpoint can authenticate the notification.
Receive PPR payment webhook › Request Body
idTransacaoTransaction identifier.
numLogSistemaSystem log number associated with the payment notification.
idLogSistemaSystem period/log identifier.
dataTransaccaoClienteDate and time when the customer payment was registered.
montantePagoAmount paid by the customer.
tipoTerminalTerminal type used for the payment.
iIdentTerminalTerminal identifier.
localidadeTerminalTerminal location.
refPagamentoPayment reference paid by the customer.
IdUnique notification identifier. Use this value for idempotency.
nibDebit account NIB, when available.
bancoBank name, when available.
Receive PPR payment webhook › Responses
Return HTTP 2xx with Success: true when the notification was processed successfully or was already processed before.
SuccessReturn true when the notification was processed successfully or was already processed before.
ObsShort processing note.
IdMerchant internal payment identifier.