$izipay->payments creates payments with every IZI Pay payment method and lets you follow them. Each example below shows every parameter. Lines marked Required must be sent; lines marked Optional can be left out, and the comment says what happens if you do.
Method
The customer
Learn more
createReference
Pays an entity and reference at an ATM or in their banking app
Every create method returns a CreatedPayment. Always check its status. A payment the customer declined is returned with statusPaymentStatus::Failed and an errorCode and errorMessage; it is not thrown as an exception.
Each request is checked as soon as you create it: a missing or wrong value throws an InvalidArgumentException before anything is sent.
$payment = $izipay->payments->createReference(new ReferencePaymentRequest( // Required. Amount in kwanzas (AOA), not cents. Must be more than 0 for a Dynamic reference. // For a Charging reference, 0 lets the customer choose the amount. amount: 15000, // Optional. ReferenceType::Dynamic (default): one payment of a fixed amount, such as an order. // ReferenceType::Charging: a long-lived reference that can receive several payments, such as a customer account. referenceType: ReferenceType::Dynamic, // Optional. Your own reference number. Leave it out and IZI Pay generates one. reference: null, // Optional. When the reference stops accepting payments. // Default: one month after creation for Dynamic, end of 2099 for Charging. expiryDate: new DateTimeImmutable('+3 days'), // Optional. Customer details, kept with the payment. customerName: 'Ana Silva', customerEmail: 'ana@example.com', customerTelephone: '923000000', // Optional. Your invoice or document number. documentNumber: 'FT 2026/1042', // Optional. What is being paid. description: 'Order 1042', // Optional. Your own data, returned when you read the payment. custom: ['orderId' => '1042'], // Optional, recommended. Sending the same request again with this key never creates a second reference. // Leave it out and the SDK makes one (returned in $payment->idempotencyKey). idempotencyKey: 'order-1042',));echo "Entity {$payment->entity}, reference {$payment->reference}, expires {$payment->expiresAt?->format('d/m/Y H:i')}";
Show the entity and reference to the customer. The webhook tells you when they have paid. To read the payment later, use $payment->id: for a payment by reference it is the reference number.
One-time purchase on the customer's phone
PHP
$purchase = $izipay->payments->createMobile(new MobilePaymentRequest( // Required. Amount in kwanzas, more than 0. amount: 2500, // Required. Your reference for this payment, such as the order number. Up to 100 characters. reference: 'ORDER-1043', // Required. The customer's Multicaixa Express phone number. phoneNumber: '923000000', // Optional. The mobile provider agreed during onboarding, for example 'UNITEL'. Left out: not sent. provider: 'UNITEL', // Optional. What is being paid. description: 'Order 1043', // Optional. Your own data, returned when you read the payment. custom: ['orderId' => '1043'], // Optional, recommended. See Idempotency keys on the overview page. idempotencyKey: 'order-1043',));if ($purchase->status === PaymentStatus::Completed) { // Paid. Confirm the order.} elseif ($purchase->status === PaymentStatus::Failed) { // Declined or not completed. echo "{$purchase->errorCode}: {$purchase->errorMessage}";} else { // Pending or Processing. Wait for the webhook, or read the payment again later.}
The answer can take up to about 90 seconds while the customer approves on their phone. Check your server's time-outs: see Time-outs on your server.
QR Code
PHP
$qr = $izipay->payments->createQrCode(new QrCodePaymentRequest( // Required. Amount in kwanzas, more than 0. amount: 1200, // Required. Your reference for this payment. Up to 100 characters. reference: 'TABLE-7', // Optional. Image size. Default: 'MEDIUM'. qrSize: 'MEDIUM', // Optional. QR Code behaviour. Default: 'STATIC'. qrType: 'STATIC', // Optional. How many payments the code accepts, at least 1. Default: 1. maxTransactions: 1, // Optional. When the code stops working. Default: 24 hours after creation. endDate: new DateTimeImmutable('+2 hours'), // Optional. true (default): the answer includes the payment ID, the image and a deep link for phones. // false: IZI Pay answers with the image only, without a payment ID. Keep the default. includeDeepLink: true, // Optional. What is being paid. description: 'Table 7', // Optional. Your own data, returned when you read the payment. custom: ['table' => '7'], // Optional, recommended. idempotencyKey: 'bill-7781',));file_put_contents('qr.png', $qr->qrCodePng); // show it on screen or print itecho "Payment ID {$qr->id}"; // keep it to check the status laterecho "On a phone, open {$qr->deepLink}"; // opens the Multicaixa Express app directly
To show the image in a web page without saving a file: <img src="data:image/png;base64,<?= base64_encode($qr->qrCodePng) ?>">.
Webframe checkout page
PHP
$checkout = $izipay->payments->createWebframe(new WebframePaymentRequest( // Required. Amount in kwanzas, more than 0. amount: 8900, // Required. Your reference for this payment. Up to 100 characters. reference: 'ORDER-1044', // Optional. A public HTTPS stylesheet ending in .css for the payment page. Leave it out for the standard look. cssUrl: 'https://shop.example.ao/izipay-checkout.css', // Optional. Page settings agreed for your merchant. Leave them out for the defaults: // qrCode 'DISABLED', mobile 'AUTHORIZATION', card 'AUTHORIZATION'. qrCode: 'DISABLED', mobile: 'AUTHORIZATION', card: 'AUTHORIZATION', // Optional. What is being paid. description: 'Order 1044', // Optional. Your own data, returned when you read the payment. custom: ['orderId' => '1044'], // Optional, recommended. idempotencyKey: 'order-1044',));header('Location: ' . $checkout->paymentUrl); // send the customer to the payment pageexit;
$checkout->expiresAt says until when the page can be used. Creating the page does not mean the customer paid: follow the payment's status.
Reserve now, collect later
An authorization reserves money on the customer's account. A capture collects all or part of it. If you will not collect it, cancel the authorization to release the money.
PHP
// 1. Reserve$hold = $izipay->payments->createAuthorization(new AuthorizationRequest( amount: 50000, // Required. Amount to reserve, in kwanzas. reference: 'BOOKING-88', // Required. Your reference. Up to 100 characters. phoneNumber: '923000000', // Required. The customer's Multicaixa Express phone number. provider: 'UNITEL', // Optional. The mobile provider agreed during onboarding. description: 'Room 12, 3 nights', // Optional. custom: ['bookingId' => '88'], // Optional. idempotencyKey: 'booking-88-hold', // Optional, recommended.));if ($hold->status === PaymentStatus::Authorized) { // Keep both IDs: authorizationId to capture, internalId to cancel. echo "{$hold->authorizationId} / {$hold->internalId}";}// 2a. Collect all or part of it$capture = $izipay->payments->capture(new CaptureRequest( amount: 42000, // Required. Amount to collect, up to what was reserved. reference: 'BOOKING-88-CHECKOUT', // Required. Your reference for this capture. authorizationId: $hold->authorizationId, // Required. From the authorization. Not its internalId. description: 'Check-out', // Optional. custom: ['bookingId' => '88'], // Optional. idempotencyKey: 'booking-88-capture-1', // Optional, recommended. A new key for each capture.));// 2b. Or release the reservation without collecting$cancellation = $izipay->payments->cancelAuthorization( $hold->internalId, // Required. The authorization's internalId. Not its authorizationId.);
Capture uses authorizationId; cancel uses internalId. The SDK never repeats a cancellation after it was sent. If it throws OutcomeUnknownException, read the payment before trying again.
What a created payment contains
Which fields are filled depends on the method.
Field
Filled for
Meaning
id
All (except an image-only QR Code)
Use it with get and requestStatusSync. For a payment by reference, it is the reference number
referenceRecordId
Payment by reference
The ID IZI Pay gave the reference record. You can't read the payment with it; use id
internalId
Most methods
IZI Pay's own ID. Needed to cancel an authorization
True when IZI Pay returned an existing payment for a repeated key
customMetadata, additionalData
When IZI Pay returns them
Your custom data, and any other data, as arrays
Send the same payment again
If creating a payment throws OutcomeUnknownException, send the same request with the key from the exception. IZI Pay returns the existing payment instead of charging again.
PHP
$request = new MobilePaymentRequest(amount: 2500, reference: 'ORDER-1043', phoneNumber: '923000000');try { $purchase = $izipay->payments->createMobile($request);} catch (OutcomeUnknownException $e) { // Later, for example from a queued job: $purchase = $izipay->payments->createMobile( $request->withIdempotencyKey($e->idempotencyKey), // Required. The key from the exception. );}
Every filter is optional. Without any, you get the 20 most recent payments.
PHP
$page = $izipay->payments->list( pageNumber: 1, // Optional. Default 1. pageSize: 50, // Optional. 1 to 100. Default 20. status: PaymentStatus::Completed, // Optional. Only this status. paymentType: PaymentType::Ppr, // Optional. Ppr (references) or Gpo (Multicaixa Express). startDate: new DateTimeImmutable('today'), // Optional. Created on or after. endDate: new DateTimeImmutable(), // Optional. Created on or before. search: 'ORDER-1042', // Optional. Free text, such as your reference.);foreach ($page->items as $p) { echo "{$p->reference}: {$p->status->value} {$p->amount}\n";}// $page->hasMore() is true when there is another page: ask for pageNumber + 1.
Ask IZI Pay to check a payment again
If you expected a webhook and it has not arrived, ask IZI Pay to check the status with the provider. The check runs in the background: read the payment a few seconds later.
PHP
$izipay->payments->requestStatusSync( '497693862', // Required. The payment's id.);