Create and manage PPR payment references.
List PPR References
GET /api/references/ppr uses page (default 1) and pageSize (default 20). Its status filter accepts the payment status values above and filters the underlying payment records. Each result also has a separate referenceStatus. The current implementation accepts type but does not apply it as a filter. This endpoint requires ppr_entity_id and returns items, totalCount, page, and pageSize.
http
query Parameters
pagePage number.
pageSizeNumber of records per page.
typeAccepted by the API but currently has no effect on results.
statusOptional payment status filter. The response's referenceStatus is a separate field.
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
Returns an unpaginated array of payment history records for the exact reference. Requires ppr_entity_id. An unknown reference returns an empty array.
path Parameters
pprReferencePPR reference value.
Get PPR Reference History › Responses
Payment history rows.
referenceamountstatuscreatedAtcompletedAtisPaidList PPR Attempts
GET /api/references/ppr/{reference}/attempts looks up attempts for the exact reference, scoped to the merchant and PPR entity identified by the token's tenant_id and ppr_entity_id. This endpoint is available when PPR attempt tracking is enabled in the environment.
All query parameters are optional and can be combined. The response contains items, totalCount, pageNumber, and pageSize, newest attempted time first. An item can contain errorCode and errorMessage. If paymentId is present, it identifies a linked payment and can be passed to GET /api/payments/{paymentId}. Failed or unconfirmed attempts can have paymentId: null.
http
The endpoint returns 400 with INVALID_DATE_RANGE if fromUtc is at or after toUtc. It returns 503 with PPR_ATTEMPTS_DISABLED when attempt tracking is disabled, and 403 when the token lacks a required merchant or PPR entity claim.
path Parameters
referenceExact PPR reference.
query Parameters
statusCompleted, Failed, or Unconfirmed. Unconfirmed means the outcome is still unknown.
attemptIdExact GUID of an attempt, as returned in items[].attemptId.
referenceIdExact GUID of the PPR reference record, as returned in items[].referenceId. Useful when a reference number has been reused.
fromUtcInclusive lower bound on attemptedAtUtc. Send an ISO 8601 timestamp with a time zone.
toUtcExclusive upper bound on attemptedAtUtc. Send an ISO 8601 timestamp with a time zone.
pageNumberFrom 1 to 1000000. Defaults to 1.
pageSizeFrom 1 to 100. Defaults to 25.
List PPR Attempts › Responses
Paginated attempts.
totalCountpageNumberpageSize