izipay / izipay-php
Official PHP client for the IZI Pay Payment API (Angola): MULTICAIXA Express, payment references, refunds and webhooks.
Requires
- php: >=8.3
- ext-json: *
- php-http/discovery: ^1.19
- psr/clock: ^1.0
- psr/http-client: ^1.0
- psr/http-factory: ^1.0
- psr/http-message: ^1.1 || ^2.0
- psr/log: ^1.1 || ^2.0 || ^3.0
- psr/simple-cache: ^1.0 || ^2.0 || ^3.0
Requires (Dev)
- guzzlehttp/guzzle: ^7.8 || ^8.0
- phpstan/phpstan: ^2.1
- phpunit/phpunit: ^10.5
Suggests
- guzzlehttp/guzzle: Recommended HTTP client. With Guzzle the SDK can tell whether a failed request reached IZI Pay, so it retries more safely.
Provides
None
Conflicts
None
Replaces
None
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
| Environment | Address | Credentials |
|---|---|---|
Environment::Sandbox | https://pay-sandbox.izipay.ao | Sandbox Client App |
Environment::Production | https://pay.izipay.ao | Production 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
| Method | What the customer does |
|---|---|
createWebframe | Pays on a provider-hosted page; open $payment->paymentUrl |
createMobile | Approves a one-time purchase on their phone |
createAuthorization / capture | Approves a reservation; you collect it later with the authorizationId |
createQrCode | Scans $payment->qrCodePng or opens $payment->deepLink |
createReference | Pays 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:
| Operation | Retried after it was sent? | Why |
|---|---|---|
| Reads, token requests, status sync | Yes | They change nothing |
| Creating a payment (any method) | Yes, with the same idempotency key | IZI Pay returns the existing payment for a repeated key |
| Refunds, references, cancellations, opening/closing terminals | No | There 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:
| Exception | kind | Meaning |
|---|---|---|
AuthenticationException | Authentication | Credentials or token rejected |
PermissionException | Permission | These credentials may not do this (HTTP 403) |
ValidationException | Validation | Something in the request is wrong (HTTP 400); see $e->details |
NotFoundException | NotFound | It does not exist for your merchant |
ConflictException | Conflict | Clashes with the current state (HTTP 409) |
NotAvailableException | NotAvailable | Feature switched off for your merchant, for example CHECKOUT_DISABLED |
RateLimitedException | RateLimited | Too many requests, even after waiting. Nothing was processed |
ConnectionException | Connection | IZI Pay could not be reached. Nothing was sent |
ServerException | Server | IZI Pay had an error while reading data |
OutcomeUnknownException | OutcomeUnknown | Sent, but no clear answer came back |
InvalidResponseException | InvalidResponse | An 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
- Set the new version in
IziPayClient::VERSION(src/IziPayClient.php) and add it at the top ofCHANGELOG.md(a test fails if they differ). If you changed the public API on purpose, runphp tools/api-surface.php --update(a test fails until you do) and describe the change in the CHANGELOG. - Push to
mainand wait for the pipeline to pass. - 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. - Check the version on https://packagist.org/packages/izipay/izipay-php and install it with Composer in a clean folder.
- Add the version to the SDK updates page of the docs (
izipay-v2-docs:pages/sdks/updates.mdxandpages/pt/sdks/updates.mdx: date, what changed, whether code changes are needed) and update the version named on the SDK's overview pages.