Create, list, sync, and cancel payment operations.
List payments
Method and route: GET /api/payments. Returns a paged list of payments. Use it for back-office screens, merchant payment history, or reconciliation workflows.
query Parameters
pagePage number.
pageSizeNumber of records per page.
List payments › Responses
Paged payments.
Create a payment
Method and route: POST /api/payments. Creates a payment through the payment gateway. Use the request body to choose the payment type, such as GPO mobile/QR payments or PPR payments.
Payment types:
GPOis used for mobile money and QR Code checkout flows. The request usually includes GPO-specific metadata such as the payment method, phone number or QR Code settings, provider, merchant ID, and POS ID.PPRis used for payment reference flows. UsereferenceType: Dynamicfor fixed-amount references; you can leavereferenceempty so the API generates it, or provide your own reference number when the merchant needs to define it. UsereferenceType: Chargingfor a defined reference number with an open amount, usuallyamount: 0; charging references can receive multiple transactions under the same reference.
Create a payment › Request Body
amountPayment 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.
currency^[A-Z]{3}$ · requiredThree-letter uppercase ISO-style currency code. Use AOA for kwanza payments.
paymentTypePayment rail to use. GPO creates a mobile money, authorization, or QR Code payment; PPR creates a payment reference.
referenceMerchant 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.
descriptionLegacy top-level description. Connector-specific descriptions are read from metadata.description; use that field for new integrations.
Create a payment › Responses
QR Code image returned for QR payment creation.
Get payment details
Method and route: GET /api/payments/{paymentId}. Retrieves the current details of a payment.
For PPR payments, pass the returned payment reference (for example, 584923109). You may also pass the payment internalId when available. The UUID returned as id by the compact PPR creation response identifies the PPR reference record and is not the lookup value for this endpoint.
path Parameters
paymentIdExternal payment identifier.
Get payment details › Responses
Payment details.
idinternalIdmerchantIdreferenceamountcurrencypaymentTypestatuscreatedAtcompletedAtdescriptioncustomerEmailcustomerNamecustomerTelephonedocumentNumberA 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.
Sync payment status
Method and route: POST /api/payments/{paymentId}/sync. Refreshes a payment's status from the provider. Use it when a payment state may have changed outside your last stored gateway response.
path Parameters
paymentIdExternal payment identifier.
Sync payment status › Responses
Payment status synced.
messageCancel authorization
Method and route: POST /api/payments/{internalPaymentId}/cancel. Cancels an authorization using the internal payment GUID. Use this for authorized payments that should not be captured.
path Parameters
internalPaymentIdInternal payment GUID.
Cancel authorization › Responses
Authorization canceled.
messageReceive QR Code 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 GPO QR Code payments created through the Payments 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 QR Code payment webhook › Request Body
creationDateDate and time when the QR Code transaction was created.
updatedDateDate and time when the QR Code transaction status was updated.
idUnique provider transaction identifier. Use this value for idempotency.
amountAmount paid by the customer.
clearingPeriodClearing period associated with the transaction.
transactionNumberProvider transaction number.
statusQR Code payment status.
transactionTypeTransaction type.
orderOriginPayment order origin.
currencyPayment currency.
merchantReferenceNumberMerchant reference number associated with the QR Code payment.
Receive QR Code 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.