Skip to main content
Pre-release

This release is a pre-release and may not be stable for production use.

IZI Pay Python SDK

Official Python 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.

  • Python 3.10 or later
  • A sync client (IziPay: Django, Flask, Odoo, scripts) and an asyncio client (AsyncIziPay: FastAPI) with the same methods
  • Sandbox and production
  • MULTICAIXA Express (Webframe, mobile purchase, authorization and capture, QR Code), payment references, refunds, terminals, billing (read only) and webhooks
  • One dependency: httpx. Fully typed (py.typed), plain frozen dataclasses

Install

pip install --pre izipay

Start

import os
from decimal import Decimal

from izipay import IziPay

with IziPay(
    environment="sandbox",  # required: "sandbox" or "production"
    client_id=os.environ["IZIPAY_CLIENT_ID"],
    client_secret=os.environ["IZIPAY_CLIENT_SECRET"],
) as izipay:
    payment = izipay.payments.create_reference(
        amount=Decimal("1500"),
        description="Order 1042",
        customer_email="customer@example.com",
    )
    print(f"Pay entity {payment.entity}, reference {payment.reference}")

With asyncio, use AsyncIziPay and await every call:

from izipay import AsyncIziPay

async with AsyncIziPay(environment="sandbox", client_id=..., client_secret=...) as izipay:
    payment = await izipay.payments.create_reference(amount=Decimal("1500"))

Create one client per set of credentials and reuse it (for example at application start-up): it keeps the access token and the HTTP connections. IziPay is thread-safe; AsyncIziPay is safe to share between tasks of one event loop. Only one token request runs at a time. Never put the secret in source control.

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

There is no default environment, so test code can never reach production by accident. Sandbox and production credentials are different; using one in the other fails with an AuthenticationError that names the environment. Ask for credentials at suporte@izipay.ao.

Payments

Method What the customer does
create_webframe Pays on a provider-hosted page; open payment.payment_url
create_mobile Approves a one-time purchase on their phone
create_authorization / capture Approves a reservation; you collect it later with the authorization_id
create_qr_code Scans payment.qr_code_png or opens payment.deep_link
create_reference Pays entity + reference at an ATM or in their banking app
from izipay import PaymentStatus

purchase = izipay.payments.create_mobile(
    amount=Decimal("2500"),
    reference="ORDER-1042",
    phone_number="923000000",
)

if purchase.status is PaymentStatus.COMPLETED:
    ...  # paid
elif purchase.status is PaymentStatus.FAILED:
    ...  # declined: purchase.error_code, purchase.error_message
else:
    ...  # pending: wait for the webhook or read it later with get()

A declined payment is returned with status FAILED, not raised. Always check status.

Amounts are in kwanzas, not cents: Decimal("2500.50"), 2500 or "2500.50". A float is refused (it cannot hold cents exactly), and so is more than 2 decimals. Amounts in answers are always Decimal.

For a payment by reference, payment.id is the reference number, which get() and request_status_sync() accept.

Other operations: get, list, request_status_sync (re-check with the provider when a webhook was missed) and cancel_authorization (release a reservation; takes the internal_id, not the authorization_id).

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: gunicorn's default worker time-out is 30 seconds (--timeout), and your web server, load balancer or task queue may have their own.

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, connect time-out) or was refused by the rate limiter (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.

Each payment gets an idempotency key. Pass your own (idempotency_key=str(order.id)) or store the one the SDK made (payment.idempotency_key). If no clear answer comes back, you get an OutcomeUnknownError:

from izipay import OutcomeUnknownError

try:
    payment = izipay.payments.create_mobile(amount=amount, reference=ref, phone_number=phone)
except OutcomeUnknownError as error:
    if error.idempotency_key is not None:
        # 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.create_mobile(
            amount=amount, reference=ref, phone_number=phone, idempotency_key=error.idempotency_key
        )
    else:
        ...  # refund, reference or terminal operation: look it up before trying again

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

Errors

Every failure from IZI Pay is an izipay.IziPayError. Catch a subclass, or check error.kind:

Error kind Meaning
AuthenticationError AUTHENTICATION Credentials or token rejected
PermissionDeniedError PERMISSION These credentials may not do this (HTTP 403)
ValidationError VALIDATION Something in the request is wrong (HTTP 400); see error.details
NotFoundError NOT_FOUND It does not exist for your merchant
ConflictError CONFLICT Clashes with the current state (HTTP 409)
NotAvailableError NOT_AVAILABLE Feature switched off for your merchant, for example CHECKOUT_DISABLED
RateLimitedError RATE_LIMITED Too many requests, even after waiting. Nothing was processed
ConnectionFailedError CONNECTION IZI Pay could not be reached. Nothing was sent
ServerError SERVER IZI Pay had an error while reading data
OutcomeUnknownError OUTCOME_UNKNOWN Sent, but no clear answer came back
InvalidResponseError INVALID_RESPONSE An answer the SDK could not read

(PermissionDeniedError and ConnectionFailedError are named so they do not clash with Python's built-in PermissionError and ConnectionError.)

Other 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. Errors can be pickled with their fields (Celery, multiprocessing).

Mistakes the SDK can see before sending (a missing phone number, a negative amount, a float amount, a date without a time zone, ...) raise ValueError or TypeError 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.

from izipay import Webhooks

webhooks = Webhooks(os.environ["IZIPAY_WEBHOOK_ACCESS_KEY"])


# FastAPI
@app.post("/izipay/reference-payments")
async def reference_payment(request: Request) -> Response:
    if not webhooks.is_authentic(request.headers.get("Access-Key")):
        return Response(status_code=401)

    payment = webhooks.parse_reference_payment(await request.body())

    # Notifications can arrive more than once: use payment.id to process each only once.
    order_id = await orders.mark_paid(payment.reference, payment.amount_paid, payment.id)

    return Response(Webhooks.acknowledge(order_id), media_type="application/json")

In Django, read the key with request.headers.get("Access-Key") and the body with request.body. Use parse_qr_code_payment on your QR Code webhook URL. The key is compared in constant time.

Other areas

from izipay import CreateReferenceRequest

izipay.references.create(amount=Decimal("1000"))
izipay.references.create_bulk([CreateReferenceRequest(amount=5), CreateReferenceRequest(amount=6)])
izipay.references.get("584923109")
izipay.refunds.create(payment_id=payment_id, amount=Decimal("500"), supervisor_id="...")
izipay.terminals.get_status("POS-ID")
izipay.billing.get_current_usage()

Dates

The gateway writes most dates in Luanda time without an offset. The SDK reads them as UTC+01:00 and returns timezone-aware datetime values, so they are correct whatever time zone your server uses. Dates you pass in (expiry_date, start_date, ...) must be timezone-aware too, for example datetime(2026, 12, 31, 23, 59, tzinfo=izipay.LUANDA).

Logging

The SDK logs timings (DEBUG) and retries (WARNING) to the izipay logger, or to the logger= you pass. It never logs request or response bodies, tokens, secrets or phone numbers.

Your own HTTP client

Pass http_client=httpx.Client(...) (or httpx.AsyncClient for AsyncIziPay) to use a proxy or your own connection settings. The SDK still applies its time-out to each request, never follows redirects, and does not close a client you passed in.

Development

python -m venv .venv
.venv/bin/pip install -e . --group dev
.venv/bin/pytest                 # unit tests (sync and async) and integration tests with a local server
.venv/bin/mypy                   # strict, checked as Python 3.10
.venv/bin/ruff check . && .venv/bin/ruff format --check .
.venv/bin/python tools/sandbox_check.py   # against the real sandbox; needs sandbox credentials

Metadata

Release files for izipay 0.1.0b1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for izipay 0.1.0b1
File Size Uploaded Provenance Actions
izipay-0.1.0b1.tar.gz 60.3 kB Without provenance Details for izipay-0.1.0b1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for izipay 0.1.0b1
File Interpreter ABI Platform Actions
izipay-0.1.0b1-py3-none-any.whl Python 3 none any Details for izipay-0.1.0b1-py3-none-any.whl

Total release size: 117.2 kB

Release files / izipay-0.1.0b1.tar.gz

Download URL izipay-0.1.0b1.tar.gz
Size 60.3 kB
Tags Source
SHA-256 checksum
How to use checksums
7c748ab42449b30fe673b27d6365c0991a036e56ea64ed575a22dc5013eb6b40
BLAKE2b-256 checksum
How to use checksums
886a49469ef9c119e8ba76cb4a8f6d5f6273601e2e0f9f740f9d853e19e8cc62
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.18

Release files / izipay-0.1.0b1-py3-none-any.whl

Download URL izipay-0.1.0b1-py3-none-any.whl
Size 56.9 kB
Tags Python 3
SHA-256 checksum
How to use checksums
75db42789f48ce3a9e9dac96cafb0f7ef4841cc5aa8737d96746526aa0536b48
BLAKE2b-256 checksum
How to use checksums
804f6a2f822974133cc6c8f462cb5a16c963a0b1826f4b97be539f6ca7bfcfb5
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.18

Security for izipay 0.1.0b1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page