Create and manage payment references.
List Payment 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 Payment References › Responses
payment references.
Create a Payment Reference
Method and route: POST /api/references/ppr. Creates a 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 payment reference creation, detail, and list endpoints.
Create a Payment Reference › Request Body
reference^[0-9]{9,15}$Optional merchant-defined payment 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 payment reference 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 payment reference 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 Payment Reference › Responses
payment 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 payment reference 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 Payment Reference
Method and route: POST /api/references/ppr/legacy. Creates a payment reference using the legacy integration path. Use this when the merchant or provider flow still depends on the legacy payment reference contract.
Create a Legacy Payment Reference › Request Body
reference^[0-9]{9,15}$Optional merchant-defined payment 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 payment reference 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 payment reference 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 Payment Reference › Responses
Legacy payment 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 payment reference 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 Payment References in Bulk
Method and route: POST /api/references/ppr/bulk. Creates several payment references in one request. Use it for batch billing workflows where many payable references need to be generated together.
Create Payment References in Bulk › Request Body
Create Payment References in Bulk › Responses
Bulk payment references created.
Get Payment Reference Status
Method and route: GET /api/references/ppr/{pprReference}. Returns the current status of a payment reference. Use this before showing a customer or merchant whether a reference is still pending, paid, canceled, or expired.
path Parameters
pprReferencepayment reference value.
Get Payment Reference Status › Responses
payment 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 payment reference 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 Payment Reference
Method and route: DELETE /api/references/ppr/{pprReference}. Cancels an existing payment reference when it should no longer be payable.
path Parameters
pprReferencepayment reference value.
Cancel Payment Reference › Responses
Reference cancelled. The response has no body.
Get Payment 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
pprReferencepayment reference value.
Get Payment Reference History › Responses
Payment history rows.
referenceamountstatuscreatedAtcompletedAtisPaidList Payment Reference Attempts
GET /api/references/ppr/{reference}/attempts looks up attempts for the exact reference, scoped to the merchant and reference entity identified by the token's tenant_id and ppr_entity_id. This endpoint is available when reference 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 reference entity claim.
path Parameters
referenceExact payment 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 payment 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 Payment Reference Attempts › Responses
Paginated attempts.
totalCountpageNumberpageSize