PHP SDK
The IZI Pay PHP SDK is a library you add to your own PHP application, with or without a framework such as Laravel or Symfony. It talks to the Payment API for you:
- it gets the access token and renews it before it expires;
- it gives you one method per payment type, with typed requests and answers;
- it retries temporary failures only when repeating the request cannot charge or refund twice;
- it turns every error into one family of exceptions, whatever format the API used;
- it checks and reads the webhooks IZI Pay sends you.
Beta
This page describes version 0.2.0-beta.1, available on Packagist. Method names can still change before version 1.0, so use the exact version you tested with.
Requirements
- PHP 8.3 or later, with the
jsonextension. Thecurlextension is recommended. - Composer.
- A Client ID and Client Secret for each environment you use. See Credentials and Support.
Install
bash
The SDK works with any HTTP client that follows the PSR-18 standard. Guzzle is recommended: with it the SDK can tell whether a failed request ever reached IZI Pay, so it can safely retry more requests (see Safe retries). If your project already uses Symfony HttpClient, you can leave Guzzle out of the command.
Updating from an older version? See SDK updates for the command and what changed.
Create the client
Create one client per set of credentials and reuse it while your script or request runs. It keeps the access token and the connections.
Every setting is shown below. Only the first three are required.
PHP
To choose the environment from configuration, use Environment::from('sandbox') or Environment::from('production').
The logger receives how long each request took and when the SDK retries. It never receives request or response bodies, tokens or secrets.
Share the access token between requests
PHP usually starts every web request from scratch (PHP-FPM, Apache mod_php). Without a cache, every page that uses IZI Pay first asks for a new access token. Pass a PSR-16 cache and the token is reused for up to an hour:
PHP
Use a cache that only your application can read. The token gives access to your merchant until it expires.
Laravel
Register the client once, for example in AppServiceProvider::register(). Any controller or job can then ask for IziPayClient.
PHP
Environments
environment | Address | Credentials |
|---|---|---|
Environment::Sandbox | https://pay-sandbox.izipay.ao | Sandbox Client App |
Environment::Production | https://pay.izipay.ao | Production Client App |
Sandbox and production credentials are different. If you use one in the other, the SDK throws an AuthenticationException that names the environment it tried.
Time-outs on your server
A mobile payment can take up to about 90 seconds while the customer approves it on their phone. The SDK waits up to 120 seconds. Check that your own limits are longer, or the request is stopped before IZI Pay answers:
- PHP's
max_execution_time(the time spent waiting for IZI Pay counts on Windows; on Linux it does not, but the next items do); - PHP-FPM's
request_terminate_timeout; - your web server's and load balancer's time-outs, such as Nginx
fastcgi_read_timeout.
If you pass your own httpClient, set its time-out yourself: the PSR-18 standard gives the SDK no way to do it.
What the client offers
| Property | Use it to | Page |
|---|---|---|
$izipay->payments | Create payments with every method, read them, list them | Payments |
$izipay->references | Create, read, list and cancel payment references | References, refunds and more |
$izipay->refunds | Return money for a completed payment | References, refunds and more |
$izipay->terminals | Read, open and close a point-of-sale terminal | References, refunds and more |
$izipay->billing | See your IZI Pay plan, usage and invoices | References, refunds and more |
Webhooks | Check and read the notifications IZI Pay sends you | Webhooks |
Safe retries
The SDK retries temporary failures (lost connection, time-out, HTTP 502, 503 or 504 from a proxy, rate limits) only where repeating the request is harmless:
| Operation | Repeated after it was sent? | Why |
|---|---|---|
| Reading and listing, token requests, status sync | Yes | They change nothing |
| Creating a payment (every method) | Yes, with the same idempotency key | IZI Pay returns the existing payment for a repeated key |
| Refunds, references, cancelling an authorization, opening or closing a terminal | No | They have no idempotency key, so a repeat could do it twice |
Any request is retried when it certainly never reached IZI Pay (connection refused, name not found) or was turned away by the rate limit (HTTP 429), because nothing was processed. When IZI Pay itself answers a change with an error code and HTTP 5xx, the SDK does not repeat it.
Why Guzzle is recommended
Only Guzzle (7 or 8, with the curl extension recommended) tells the SDK whether a failed request was ever sent. With any other HTTP client, the SDK assumes it may have been: payment creation is still retried with the same key, but a refund or reference that hits a connection problem is reported as an unknown outcome instead of being retried.
Idempotency keys
Every payment you create carries an idempotency key. If IZI Pay already has a payment with that key for your merchant, it returns that payment instead of creating another.
- Optional. If you leave it out, the SDK makes one and returns it in
$payment->idempotencyKey. That protects the SDK's own retries. - Recommended in production: use your own key, such as your order ID. Then a second attempt for the same order (after a crash, or a customer clicking Pay twice) returns the first payment instead of charging again.
- Use a new key for each new payment, including each capture.
Errors
Every failure is an IziPay\Exception\IziPayException. Catch the subclass you care about, or check $e->kind:
| Exception | kind | Meaning | What to do |
|---|---|---|---|
ValidationException | Validation | Something in the request is wrong (HTTP 400) | Fix the request. $e->details lists the fields |
AuthenticationException | Authentication | Credentials or token rejected | Check the credentials and that they belong to this environment |
PermissionException | Permission | These credentials may not do this (HTTP 403) | Contact IZI Pay support |
NotFoundException | NotFound | It does not exist for your merchant | Check the ID |
ConflictException | Conflict | Clashes with the current state, for example a reused key (HTTP 409) | Read the current state first |
NotAvailableException | NotAvailable | The feature is switched off for your merchant, for example CHECKOUT_DISABLED | Contact IZI Pay support. Nothing was processed |
RateLimitedException | RateLimited | Too many requests, even after waiting | Try again in a minute. Nothing was processed |
ConnectionException | Connection | IZI Pay could not be reached | Try again. Nothing was sent |
ServerException | Server | IZI Pay had an error while reading data | Try again later |
OutcomeUnknownException | OutcomeUnknown | Sent, but no clear answer came back | See below |
InvalidResponseException | InvalidResponse | An answer the SDK could not read | Contact IZI Pay support with traceId |
Other useful properties: statusCode, errorCode (IZI Pay's own code, such as INVALID_OPERATION), details, traceId (quote it to support) and the method isSafeToRetry() (true when sending the same request again cannot do anything twice).
When the outcome is unknown
OutcomeUnknownException means the request was sent but no clear answer came back. It may or may not have been processed.
PHP
Mistakes the SDK can see before sending, such as a missing phone number, a negative amount or more than 2 decimals, throw an InvalidArgumentException when you create the request, and nothing is sent.
Amounts, dates and statuses
- Amounts are in kwanzas, not cents:
1500,1500.50or'1500.50'. More than 2 decimals is refused. Amounts you read back arefloat. - IZI Pay writes most dates in Luanda time without saying so. The SDK reads them as UTC+01:00 and gives you a
DateTimeImmutable, so the time is right whatever time zone your server uses. - If IZI Pay adds a status the SDK does not know yet, it reads as
Unknowninstead of failing. TreatUnknownas not paid. See Payment Statuses.