This page covers everything in the PHP SDK besides creating payments. As on the other pages, each example shows every parameter, marked Required or Optional.
Never repeated automatically
Creating or cancelling a reference, creating a refund, and opening or closing a terminal have no idempotency key. The SDK never sends them twice. If one throws OutcomeUnknownException, look it up before trying again.
Payment references
$izipay->references works with payment references directly. To create a reference as a payment, with an idempotency key, you can also use payments->createReference.
PHP
use IziPay\PaymentStatus;use IziPay\References\CreateReferenceRequest;use IziPay\ReferenceType;
Create a reference
PHP
$reference = $izipay->references->create(new CreateReferenceRequest( // Required for Dynamic (more than 0). For Charging, 0 or null lets the customer choose the amount. amount: 15000, // Optional. ReferenceType::Dynamic (default): one payment of a fixed amount. // ReferenceType::Charging: a long-lived reference that can receive several payments. 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. expiryDate: new DateTimeImmutable('+3 days'), // Optional. What is being paid. description: 'Invoice FT 2026/1042', // Optional. Customer details. customerName: 'Ana Silva', customerEmail: 'ana@example.com', customerTelephone: '923000000', // Optional. Your invoice or document number. documentNumber: 'FT 2026/1042', // Optional. Your own data, returned when you read the reference. customMetadata: ['invoiceId' => '1042'],));echo "Entity {$reference->entity}, reference {$reference->reference}, {$reference->referenceStatus->value}";
Create up to 100 references at once
Each item has the same parameters as above. Some can succeed while others fail, so check both lists.
PHP
$result = $izipay->references->createBulk([ // Required. 1 to 100 requests. new CreateReferenceRequest(amount: 5000, description: 'Student 551 - November'), new CreateReferenceRequest(amount: 5000, description: 'Student 552 - November'),]);echo "{$result->successCount} created, {$result->errorCount} failed\n";foreach ($result->references as $created) { echo $created->reference, "\n";}foreach ($result->errors as $error) { echo json_encode($error), "\n"; // IZI Pay's description of each failure}
Read, follow and cancel
PHP
// Read a reference and the status of its payment$current = $izipay->references->get( '584923109', // Required. The reference number.);// Every payment made to it (a Charging reference can receive several)$history = $izipay->references->getHistory( '584923109', // Required.);// Stop it accepting payments. Only works while it has not been paid.$izipay->references->cancel( '584923109', // Required.);
referenceStatus tells you about the reference itself (Active, Paid, Cancelled, Expired); status tells you about its payment.
List references
PHP
$page = $izipay->references->list( pageNumber: 1, // Optional. Default 1. pageSize: 50, // Optional. 1 to 100. Default 20. type: ReferenceType::Dynamic, // Optional. Only this type. status: PaymentStatus::Completed, // Optional. Only references whose payment has this status.);
Refunds
PHP
use IziPay\PaymentType;use IziPay\Refunds\RefundStatus;
Return money to a customer
You can refund all or part of a completed payment. For an authorization, refund the specific capture; to release money that was reserved but never collected, cancel the authorization instead.
PHP
$refund = $izipay->refunds->create( '497693862', // Required. The payment's id or internalId. amount: 500, // Required. 0.01 to 10,000,000. Less than the payment for a partial refund. supervisorId: 'SUP-001', // Required. The supervisor ID given to you during onboarding. reason: 'Item damaged', // Optional. Up to 500 characters.);echo "Refund {$refund->id}: {$refund->status->value}";
Before trying a refund again after OutcomeUnknownException, list the refunds and read the payment's refundedAmount, so the customer is not refunded twice.
Read and list refunds
PHP
$one = $izipay->refunds->get( '497693862', // Required. The payment's id. '9b2f2c43-4b8f-4a7e-9a52-0d8b8a3c1e11', // Required. The refund's id.);$refunds = $izipay->refunds->list( pageNumber: 1, // Optional. Default 1. pageSize: 50, // Optional. 1 to 100. Default 20. status: RefundStatus::Completed, // Optional. Pending, Processing, Completed or Failed. paymentType: PaymentType::Gpo, // Optional. Gpo or Ppr. startDate: new DateTimeImmutable('-30 days'), // Optional. Requested on or after. endDate: new DateTimeImmutable(), // Optional. Requested on or before.);
Terminals
For merchants with a Multicaixa point-of-sale terminal.
PHP
use IziPay\Terminals\TerminalState;// Read the terminal's state$terminal = $izipay->terminals->getStatus( 'POS-ID', // Required. Your terminal (POS) ID.);if ($terminal->status === TerminalState::Open) { // TerminalState::Open or TerminalState::Closed echo "{$terminal->name} is open";}// Open or close it. Both return the ID of the operation.$operationId = $izipay->terminals->open( 'POS-ID', // Required. supervisorId: 'SUP-001', // Optional. Only if your terminal needs a supervisor. supervisorIban: 'AO06000000000000000000000', // Optional. Only if your terminal needs one.);$operationId = $izipay->terminals->close('POS-ID'); // supervisorId and supervisorIban are optional here too
Your IZI Pay bill
Read-only access to your IZI Pay plan, usage and invoices.
PHP
// Packages you are subscribed to$subscriptions = $izipay->billing->getActiveSubscriptions();// Usage per service in the current billing period: how many payments and their total value.// Not your fee: your package's pricing (for example a commission) is applied on the invoice.foreach ($izipay->billing->getCurrentUsage() as $u) { echo "{$u->serviceName}: {$u->totalQuantity} {$u->unitName}, {$u->totalAmount} AOA in payments\n";}// Individual usage records$records = $izipay->billing->getUsageHistory( billingPeriod: '2026-11', // Optional. Only this month. Leave it out for all. pageNumber: 1, // Optional. Default 1. pageSize: 50, // Optional. 1 to 100. Default 50.);// Invoices, newest first$invoices = $izipay->billing->listInvoices( pageNumber: 1, // Optional. Default 1. pageSize: 20, // Optional. 1 to 100. Default 20.);// One invoice with its lines$invoice = $izipay->billing->getInvoice( $invoices[0]->invoiceId, // Required.);