Python SDK
The IZI Pay Python SDK is a library you add to your own Python application: a Django or Flask site, a FastAPI service, an Odoo module or a plain script. 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 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.
There are two clients with exactly the same methods: IziPay for ordinary (synchronous) code, and AsyncIziPay for asyncio code such as FastAPI, where every call is awaited.
Beta
This page describes version 0.2.0b1, available on PyPI. Method names can still change before version 1.0, so use the exact version you tested with.
Requirements
- Python 3.11 or later.
- A Client ID and Client Secret for each environment you use. See Credentials and Support.
The SDK has one dependency, httpx, which pip installs for you. It is fully typed, so editors and type checkers such as mypy know every field.
Install
bash
--pre is needed while the SDK is in beta. In a requirements file, pin the exact version: izipay==0.2.0b1.
Updating from an older version? See SDK updates for the command and what changed.
Create the client
Create one client per set of credentials, when your application starts, and reuse it. It keeps the access token and the connections. IziPay can be shared between threads; AsyncIziPay can be shared between the tasks of one event loop.
Every setting is shown below. Only the first three are required.
In a script, with IziPay(...) as izipay: (or async with AsyncIziPay(...) as izipay:) closes the client for you.
If you pass your own http_client, the SDK still applies its time-out to every request and never follows redirects. It does not close a client you passed in.
The logger receives how long each request took (DEBUG) and when the SDK retries (WARNING). It never receives request or response bodies, tokens, secrets or phone numbers. To see these lines, turn on the izipay logger in your logging configuration.
Django
Create the client once, in a module of your own, and import it wherever you need it:
Python
The same works in Flask, an Odoo module or a Celery worker: one client per process, created at start-up.
FastAPI
Open the client when the application starts and close it when it stops:
Python
Environments
environment | Address | Credentials |
|---|---|---|
"sandbox" / Environment.SANDBOX | https://pay-sandbox.izipay.ao | Sandbox Client App |
"production" / Environment.PRODUCTION | https://pay.izipay.ao | Production Client App |
Sandbox and production credentials are different. If you use one in the other, the SDK raises an AuthenticationError 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:
- gunicorn stops a worker after 30 seconds by default: start it with
--timeout 150or more; - your web server's and load balancer's time-outs, such as Nginx
proxy_read_timeout; - the time limit of a task queue, if you create payments from Celery or a similar worker.
Opening the connection gets at most 15 seconds of the time-out. If IZI Pay cannot be reached, a call therefore fails with ConnectionFailedError within about 45 seconds (3 attempts) instead of hanging; nothing was sent, so it is safe to try again.
What the client offers
| Attribute | 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 |
The examples on the next pages use the sync client. With AsyncIziPay, write await before each call: await izipay.payments.get(...). Every parameter and answer is the same.
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, connection time-out) 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.
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.idempotency_key. 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 from IZI Pay is an izipay.IziPayError. Catch the subclass you care about, or check error.kind:
| Exception | kind | Meaning | What to do |
|---|---|---|---|
ValidationError | VALIDATION | Something in the request is wrong (HTTP 400) | Fix the request. error.details lists the fields |
AuthenticationError | AUTHENTICATION | Credentials or token rejected | Check the credentials and that they belong to this environment |
PermissionDeniedError | PERMISSION | These credentials may not do this (HTTP 403) | Contact IZI Pay support |
NotFoundError | NOT_FOUND | It does not exist for your merchant | Check the ID |
ConflictError | CONFLICT | Clashes with the current state, for example a reused key (HTTP 409) | Read the current state first |
NotAvailableError | NOT_AVAILABLE | The feature is switched off for your merchant, for example CHECKOUT_DISABLED | Contact IZI Pay support. Nothing was processed |
RateLimitedError | RATE_LIMITED | Too many requests, even after waiting | Try again in a minute. Nothing was processed |
ConnectionFailedError | CONNECTION | IZI Pay could not be reached | Try again. Nothing was sent |
ServerError | SERVER | IZI Pay had an error while reading data | Try again later |
OutcomeUnknownError | OUTCOME_UNKNOWN | Sent, but no clear answer came back | See below |
InvalidResponseError | INVALID_RESPONSE | An answer the SDK could not read | Contact IZI Pay support with trace_id |
PermissionDeniedError and ConnectionFailedError have these names so they do not clash with Python's built-in PermissionError and ConnectionError.
Other useful attributes: status_code, error_code (IZI Pay's own code, such as INVALID_OPERATION), details, trace_id (quote it to support) and is_safe_to_retry (true when sending the same request again cannot do anything twice). The exceptions keep these attributes when they are pickled, for example by Celery.
When the outcome is unknown
OutcomeUnknownError means the request was sent but no clear answer came back. It may or may not have been processed.
Python
Mistakes the SDK can see before sending, such as a missing phone number, a negative amount or more than 2 decimals, raise a ValueError or TypeError, and nothing is sent.
Amounts, dates and statuses
- Amounts are in kwanzas, not cents. Pass a
Decimal(Decimal("1500.50")), anint(1500) or a string ("1500.50"). Afloatis refused, because it cannot hold cents exactly, and so is more than 2 decimals. Amounts you read back are alwaysDecimal. - IZI Pay writes most dates in Luanda time without saying so. The SDK reads them as UTC+01:00 and gives you a timezone-aware
datetime, so the time is right whatever time zone your server uses. - Dates you pass in must be timezone-aware too.
izipay.LUANDAis Luanda's time zone:datetime(2026, 12, 31, 23, 59, tzinfo=LUANDA)ordatetime.now(LUANDA) + timedelta(days=3). A date without a time zone raisesValueError. - If IZI Pay adds a status the SDK does not know yet, it reads as
UNKNOWNinstead of failing. TreatUNKNOWNas not paid. See Payment Statuses. - The answers are frozen dataclasses: you can read their fields but not change them.