Search by

izipay / izipay-php

izipay

Official PHP client for the IZI Pay Payment API (Angola): MULTICAIXA Express, payment references, refunds and webhooks.

v0.2.0-beta.1 2026-11-22 21:34 UTC

This package is auto-updated.

Last update: 2026-11-22 17:39:42 UTC


README

Official PHP client for the IZI Pay Payment API (Angola). It handles access tokens, safe retries, errors and webhooks for you, so your code only deals with payments.

Beta (0.x). The API can still change between 0.x versions. Version 1.0 will follow once the IZI Pay API itself is stable. Pin the exact version you test with.

  • PHP 8.3 or later
  • Sandbox and production
  • MULTICAIXA Express (Webframe, mobile purchase, authorization and capture, QR Code), payment references, refunds, terminals, billing (read only) and webhooks
  • Works with any PSR-18 HTTP client; Guzzle 7 or 8 is recommended

Install

composer require izipay/izipay-php:^0.2@beta guzzlehttp/guzzle

Guzzle is optional but recommended: with it the SDK can tell whether a failed request ever reached IZI Pay, so it can retry more requests safely. Without it the SDK uses Symfony HttpClient or any PSR-18 client it finds.

Start

use IziPay\Environment;
use IziPay\IziPayClient;
use IziPay\Payments\ReferencePaymentRequest;

$izipay = new IziPayClient(
    environment: Environment::Sandbox,           // required: Sandbox or Production
    clientId: getenv('IZIPAY_CLIENT_ID'),
    clientSecret: getenv('IZIPAY_CLIENT_SECRET'),
);

$payment = $izipay->payments->createReference(new ReferencePaymentRequest(
    amount: 1500,
    description: 'Order 1042',
    customerEmail: 'customer@example.com',
));

echo "Pay entity {$payment->entity}, reference {$payment->reference}";

Never put the secret in source control.

Share the access token between requests

PHP-FPM starts every web request from scratch, so without help each page asks IZI Pay for a new access token. Pass any PSR-16 cache (Laravel's Cache::store(), Symfony's Psr16Cache, a Redis or APCu cache) and the token is reused for up to an hour:

$izipay = new IziPayClient(
    environment: Environment::Production,
    clientId: $config['izipay_client_id'],
    clientSecret: $config['izipay_client_secret'],
    tokenCache: $cache, // private to your application: the token gives access to your merchant
);

Environments

EnvironmentAddressCredentials
Environment::Sandboxhttps://pay-sandbox.izipay.aoSandbox Client App
Environment::Productionhttps://pay.izipay.aoProduction Client App

There is no default environment, so test code can never reach production by accident. Read it from configuration with Environment::from('sandbox'). Sandbox and production credentials are different; using one in the other fails with an AuthenticationException that names the environment. Ask for credentials at suporte@izipay.ao.

Payments

MethodWhat the customer does
createWebframePays on a provider-hosted page; open $payment->paymentUrl
createMobileApproves a one-time purchase on their phone
createAuthorization / captureApproves a reservation; you collect it later with the authorizationId
createQrCodeScans $payment->qrCodePng or opens $payment->deepLink
createReferencePays entity + reference at an ATM or in their banking app
use IziPay\Payments\MobilePaymentRequest;
use IziPay\PaymentStatus;

$purchase = $izipay->payments->createMobile(new MobilePaymentRequest(
    amount: 2500,
    reference: 'ORDER-1042',
    phoneNumber: '923000000',
));

if ($purchase->status === PaymentStatus::Completed) { /* paid */ }
elseif ($purchase->status === PaymentStatus::Failed) { /* declined: $purchase->errorCode, $purchase->errorMessage */ }
else { /* pending: wait for the webhook or read it later with get() */ }

A declined payment is returned with status Failed, not thrown. Always check status.

Amounts are in kwanzas, not cents: 2500, 2500.50 or '2500.50'. More than 2 decimals is refused.

Other operations: get, list, requestStatusSync (re-check with the provider when a webhook was missed) and cancelAuthorization (release a reservation; takes the internalId, not the authorizationId).

Time-outs

A mobile payment can take up to 90 seconds while the customer approves it on their phone. The SDK waits up to 120 seconds per attempt (timeout:). Check that your own limits are longer: PHP's max_execution_time, your web server's and load balancer's time-outs, and PHP-FPM's request_terminate_timeout.

If you pass your own HTTP client, set its time-out yourself: PSR-18 has no standard way for the SDK to do it.

Safe retries and idempotency

The SDK retries temporary failures (connection problems, time-outs, HTTP 502/503/504, rate limits) only when repeating the request cannot do anything twice:

OperationRetried after it was sent?Why
Reads, token requests, status syncYesThey change nothing
Creating a payment (any method)Yes, with the same idempotency keyIZI Pay returns the existing payment for a repeated key
Refunds, references, cancellations, opening/closing terminalsNoThere is no idempotency key, so a repeat could do it twice

Every request is retried when it certainly never reached IZI Pay (connection refused, DNS, TLS) or was refused by the rate limiter (HTTP 429), because nothing was processed. Only Guzzle (7 or 8) reports enough to know a request was never sent; with other HTTP clients the SDK assumes it may have been. When IZI Pay itself answers a change with an error code and HTTP 5xx, the SDK does not repeat it.

Each payment gets an idempotency key. Pass your own (idempotencyKey: $order->id) or store the one the SDK made ($payment->idempotencyKey). If no clear answer comes back, you get an OutcomeUnknownException:

use IziPay\Exception\OutcomeUnknownException;

try {
    $payment = $izipay->payments->createMobile($request);
} catch (OutcomeUnknownException $e) {
    if ($e->idempotencyKey !== null) {
        // The payment may exist. Sending the same request with the same key later is safe:
        // IZI Pay returns the existing payment instead of charging again.
        $payment = $izipay->payments->createMobile($request->withIdempotencyKey($e->idempotencyKey));
    } else {
        // Refund, reference or terminal operation: look it up before trying again.
    }
}

Defaults: up to 2 retries (maxRetries:, 0–5) and 120 seconds per attempt.

Errors

Every failure is an IziPay\Exception\IziPayException. Catch a subclass, or check $e->kind:

ExceptionkindMeaning
AuthenticationExceptionAuthenticationCredentials or token rejected
PermissionExceptionPermissionThese credentials may not do this (HTTP 403)
ValidationExceptionValidationSomething in the request is wrong (HTTP 400); see $e->details
NotFoundExceptionNotFoundIt does not exist for your merchant
ConflictExceptionConflictClashes with the current state (HTTP 409)
NotAvailableExceptionNotAvailableFeature switched off for your merchant, for example CHECKOUT_DISABLED
RateLimitedExceptionRateLimitedToo many requests, even after waiting. Nothing was processed
ConnectionExceptionConnectionIZI Pay could not be reached. Nothing was sent
ServerExceptionServerIZI Pay had an error while reading data
OutcomeUnknownExceptionOutcomeUnknownSent, but no clear answer came back
InvalidResponseExceptionInvalidResponseAn answer the SDK could not read

Other properties: statusCode, errorCode (IZI Pay's own code, such as INVALID_OPERATION), details, traceId (quote it to support) and isSafeToRetry().

Mistakes the SDK can see before sending (a missing phone number, a negative amount, ...) throw an InvalidArgumentException and nothing is sent.

Webhooks

IZI Pay sends the Access-Key you chose during onboarding with every notification. It only stops resending when your endpoint answers HTTP 2xx with "Success": true.

use IziPay\Webhooks\Webhooks;

$webhooks = new Webhooks(getenv('IZIPAY_WEBHOOK_ACCESS_KEY'));

if (!$webhooks->isAuthentic($_SERVER['HTTP_ACCESS_KEY'] ?? null)) {   // PSR-7: $request->getHeaderLine('Access-Key')
    http_response_code(401);
    exit;
}

$payment = $webhooks->parseReferencePayment(file_get_contents('php://input'));

// Notifications can arrive more than once: use $payment->id to process each only once.
$orderId = $orders->markPaid($payment->reference, $payment->amountPaid, $payment->id);

header('Content-Type: application/json');
echo Webhooks::acknowledge($orderId);

Use parseQrCodePayment on your QR Code webhook URL. The key is compared in constant time.

Other areas

use IziPay\References\CreateReferenceRequest;

$izipay->references->create(new CreateReferenceRequest(amount: 1000));
$izipay->references->get('584923109');
$izipay->refunds->create($paymentId, amount: 500, supervisorId: '...');
$izipay->terminals->getStatus('POS-ID');
$izipay->billing->getCurrentUsage();

Dates

The gateway writes most dates in Luanda time without an offset. The SDK reads them as UTC+01:00 and returns DateTimeImmutable, so values are correct whatever time zone your server uses.

Logging

Pass any PSR-3 logger (logger:). The SDK logs timings and retries. It never logs request or response bodies, tokens or secrets.

Development

composer install
composer check          # PHPStan (max level), unit tests, integration tests with a local server
composer sandbox-check  # against the real sandbox; needs sandbox credentials

Versions and support

Versions follow Semantic Versioning. Before 1.0, a new minor version (0.1 to 0.2) can need code changes; a new beta or preview of the same minor version only fixes problems. From 1.0, only a major version can remove or change something, after it was marked as deprecated in a minor version. The SDK supports the PHP versions that still get security fixes from their maintainers. Fixes go to the newest version. What changed in each version: SDK updates.

Problems with the SDK: email suporte@izipay.ao with the SDK version, the environment, and the error's message and trace ID. Never send secrets, tokens or your webhook Access-Key.

Releasing

  1. Set the new version in IziPayClient::VERSION (src/IziPayClient.php) and add it at the top of CHANGELOG.md (a test fails if they differ). If you changed the public API on purpose, run php tools/api-surface.php --update (a test fails until you do) and describe the change in the CHANGELOG.
  2. Push to main and wait for the pipeline to pass.
  3. Tag and push: git tag -a v<version> -m "..." && git push origin v<version>. Packagist picks up the tag through the GitLab integration within a minute.
  4. Check the version on https://packagist.org/packages/izipay/izipay-php and install it with Composer in a clean folder.
  5. Add the version to the SDK updates page of the docs (izipay-v2-docs: pages/sdks/updates.mdx and pages/pt/sdks/updates.mdx: date, what changed, whether code changes are needed) and update the version named on the SDK's overview pages.