Schemas

MFA method identifier.

Payment amount expressed in the selected currency. Decimals are supported.

For GPO and PPR with metadata.referenceType: Dynamic, the amount must be between 0.01 and 10,000,000. For a PPR charging reference, use 0 for an open amount that the customer enters when paying; a positive amount is also accepted. Negative values are never allowed.

Three-letter uppercase ISO-style currency code. Use AOA for kwanza payments.

Payment rail to use. GPO creates a mobile money, authorization, or QR Code payment; PPR creates a payment reference.

Merchant payment identifier. It is required for GPO and may contain up to 15 characters (individual GPO methods can impose a stricter format).

For PPR, omit it or send an empty string to have IZI Pay generate a 9-digit reference. To define the reference yourself, send only digits and use between 9 and 15 digits. A merchant-defined dynamic reference cannot be reused while the same reference is active and unpaid for the entity.

Payment-type-specific settings for POST /api/payments.

Connector settings such as paymentMethod, referenceType, expiryDate, and customer fields belong directly in this object. Merchant-defined fields must be grouped inside metadata.custom; do not place arbitrary merchant keys alongside connector settings.

Values sent in metadata.custom are stored with the payment and returned as the top-level customMetadata property in creation and lookup responses. Do not send a top-level customMetadata field to /api/payments.

GPO flow to start. Use webframe for hosted checkout, onetimepurchase for an immediate mobile payment, authorization to reserve funds, capture to complete a previous authorization, or qrcode to create a QR Code. Defaults to webframe when omitted or unrecognized.

Customer mobile number used by mobile payment and authorization flows.

Mobile network/payment provider used for the transaction.

GPO merchant identifier assigned during onboarding. It can also be supplied by the authenticated merchant configuration.

GPO point-of-sale identifier assigned during onboarding. It can also be supplied by the authenticated merchant configuration.

Requested QR Code image size. Used only when paymentMethod is qrcode; defaults to MEDIUM.

QR Code behavior. Used only when paymentMethod is qrcode; defaults to STATIC.

Maximum number of payments accepted by the QR Code. Used only for QR Code payments and defaults to 1.

Optional QR Code expiry in ISO 8601 format. Defaults to 24 hours after creation.

Identifier returned by a previous authorization. Required when paymentMethod is capture.

Description sent to GPO. For QR Code payments, the top-level reference is used when this value is omitted.

Optional merchant-defined JSON object for internal reconciliation data.

The merchant chooses the property names. Values may be strings, numbers, booleans, arrays, nested objects, or null. IZI Pay does not use these properties to select or configure the GPO payment method.

The object is returned as customMetadata in payment detail and list responses. Do not include credentials, card details, access tokens, or other secrets.

PPR reference behavior. Dynamic is a fixed-amount reference and requires amount greater than zero. Charging is reusable and can receive multiple transactions; use amount: 0 when the payer should choose the amount. Defaults to Dynamic when omitted.

Optional ISO 8601 expiry date. If omitted, a dynamic reference expires one month after creation and a charging reference defaults to the end of 2099.

Merchant-facing reason or label for the reference.

Optional customer email stored with the reference and returned in the PPR payment response.

Optional customer name stored with the reference and returned in the PPR payment response.

Optional customer telephone number returned in the PPR payment response.

Optional customer identity document number returned in payment details.

Optional merchant-defined JSON object for linking the PPR payment to your internal records.

The merchant chooses the property names. Values may be strings, numbers, booleans, arrays, nested objects, or null. These values do not affect the generated entity, reference, amount, expiry, or payment status.

Send this object as metadata.custom when using POST /api/payments. IZI Pay stores it and returns it as the top-level customMetadata property in PPR creation and lookup responses. Do not include credentials, card details, access tokens, or other secrets.

Optional merchant-defined PPR reference containing 9 to 15 digits. Omit it to generate the reference automatically.

Dynamic creates a fixed-amount reference. Charging creates a reusable reference and allows an open amount. Defaults to Dynamic when omitted.

Required and greater than zero for Dynamic; optional for Charging, where 0 represents an open amount.

Optional future expiry in ISO 8601 format.

Optional merchant-facing reason or label for the reference.

Optional customer email stored with the reference.

Optional customer full name stored with the reference.

Optional customer telephone number stored with the reference.

Optional 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.

For compact PPR responses, this identifies the PPR reference record. Use reference, not this field, to call GET /api/payments/{paymentId}.

Internal payment identifier when included by the selected payment flow.

Provider/payment reference. For PPR, use this value to retrieve payment details.

A 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.

A 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.

A 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.

Transaction identifier.

System log number associated with the payment notification.

System period/log identifier.

Date and time when the customer payment was registered.

Amount paid by the customer.

Terminal type used for the payment.

Terminal identifier.

Terminal location.

Payment reference paid by the customer.

Unique notification identifier. Use this value for idempotency.

Debit account NIB, when available.

Bank name, when available.

Date and time when the QR Code transaction was created.

Date and time when the QR Code transaction status was updated.

Unique provider transaction identifier. Use this value for idempotency.

Amount paid by the customer.

Clearing period associated with the transaction.

Provider transaction number.

QR Code payment status.

Transaction type.

Payment order origin.

Payment currency.

Merchant reference number associated with the QR Code payment.

Return true when the notification was processed successfully or was already processed before.

Short processing note.

Merchant internal payment identifier.

Sender name configured for SMS messages.

Current available SMS units.

Ledger entry type, such as credit or debit.

Destination phone number in the format accepted by the SMS service.

SMS template identifier.