izipay 0.1.0b1__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (35) hide show
  1. izipay-0.1.0b1/.gitignore +14 -0
  2. izipay-0.1.0b1/CHANGELOG.md +27 -0
  3. izipay-0.1.0b1/LICENSE +21 -0
  4. izipay-0.1.0b1/PKG-INFO +272 -0
  5. izipay-0.1.0b1/README.md +243 -0
  6. izipay-0.1.0b1/pyproject.toml +83 -0
  7. izipay-0.1.0b1/src/izipay/__init__.py +130 -0
  8. izipay-0.1.0b1/src/izipay/_async_client.py +644 -0
  9. izipay-0.1.0b1/src/izipay/_client.py +644 -0
  10. izipay-0.1.0b1/src/izipay/_enums.py +237 -0
  11. izipay-0.1.0b1/src/izipay/_internal/__init__.py +1 -0
  12. izipay-0.1.0b1/src/izipay/_internal/core.py +482 -0
  13. izipay-0.1.0b1/src/izipay/_internal/data.py +178 -0
  14. izipay-0.1.0b1/src/izipay/_internal/dates.py +65 -0
  15. izipay-0.1.0b1/src/izipay/_internal/error_parser.py +119 -0
  16. izipay-0.1.0b1/src/izipay/_internal/guard.py +120 -0
  17. izipay-0.1.0b1/src/izipay/_internal/operations.py +998 -0
  18. izipay-0.1.0b1/src/izipay/_internal/setup.py +102 -0
  19. izipay-0.1.0b1/src/izipay/_internal/tokens.py +163 -0
  20. izipay-0.1.0b1/src/izipay/_internal/transport.py +173 -0
  21. izipay-0.1.0b1/src/izipay/_version.py +1 -0
  22. izipay-0.1.0b1/src/izipay/errors.py +304 -0
  23. izipay-0.1.0b1/src/izipay/models.py +358 -0
  24. izipay-0.1.0b1/src/izipay/py.typed +0 -0
  25. izipay-0.1.0b1/src/izipay/webhooks.py +214 -0
  26. izipay-0.1.0b1/tests/__init__.py +0 -0
  27. izipay-0.1.0b1/tests/conftest.py +35 -0
  28. izipay-0.1.0b1/tests/integration/__init__.py +0 -0
  29. izipay-0.1.0b1/tests/integration/test_real_http.py +239 -0
  30. izipay-0.1.0b1/tests/support.py +255 -0
  31. izipay-0.1.0b1/tests/unit/__init__.py +0 -0
  32. izipay-0.1.0b1/tests/unit/test_client_core.py +528 -0
  33. izipay-0.1.0b1/tests/unit/test_operations.py +576 -0
  34. izipay-0.1.0b1/tests/unit/test_parity_and_internals.py +115 -0
  35. izipay-0.1.0b1/tests/unit/test_webhooks.py +88 -0
@@ -0,0 +1,14 @@
1
+ .venv/
2
+ __pycache__/
3
+ *.py[cod]
4
+ .pytest_cache/
5
+ .mypy_cache/
6
+ .ruff_cache/
7
+ dist/
8
+ build/
9
+ *.egg-info/
10
+ .coverage
11
+ htmlcov/
12
+ .DS_Store
13
+ .idea/
14
+ .vscode/
@@ -0,0 +1,27 @@
1
+ # Changelog
2
+
3
+ All notable changes to the IZI Pay Python SDK. Versions follow [Semantic Versioning](https://semver.org/) and
4
+ [PEP 440](https://peps.python.org/pep-0440/); before 1.0, minor versions may contain breaking changes.
5
+
6
+ ## 0.1.0b1 (unreleased)
7
+
8
+ First beta, with the same behaviour as the IZI Pay PHP SDK 0.1.0-beta.1 and .NET SDK 0.1.0-preview.1.
9
+
10
+ - `IziPay` (sync, thread-safe) and `AsyncIziPay` (asyncio) with the same methods, for sandbox and production, with
11
+ a required environment choice. httpx is the only dependency.
12
+ - Access tokens from Client App credentials, kept in memory and renewed before expiry; one token request at a
13
+ time across threads or tasks.
14
+ - Payments: Webframe, mobile purchase, authorization, capture, QR Code (with deep link), payment by reference;
15
+ get, list, status sync, cancel authorization. For a payment by reference, `CreatedPayment.id` is the reference
16
+ number, which `get()` and `request_status_sync()` accept; the gateway's own answer ID is kept in
17
+ `reference_record_id`.
18
+ - Amounts in as `Decimal`, `int` or `str` (a `float` is refused), out as `Decimal`. Timezone-aware dates; dates
19
+ without an offset are read as Luanda time (UTC+01:00).
20
+ - Automatic idempotency keys on payment creation; retries only where repeating is safe.
21
+ - `OutcomeUnknownError` when no clear answer came back, carrying the idempotency key to resend safely.
22
+ - One error family for every API error format, with a subclass per kind; errors can be pickled.
23
+ - References: create, bulk create, get, list, cancel, history.
24
+ - Refunds: create, get, list.
25
+ - Terminals: status, open, close.
26
+ - Billing: active subscriptions, current usage, usage history, invoices.
27
+ - Webhooks: constant-time `Access-Key` check, typed reference and QR Code notifications, acknowledgement body.
izipay-0.1.0b1/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Suplitel
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,272 @@
1
+ Metadata-Version: 2.5
2
+ Name: izipay
3
+ Version: 0.1.0b1
4
+ Summary: Official Python SDK for the IZI Pay payment API (Angola): MULTICAIXA Express, payment references, refunds and webhooks.
5
+ Project-URL: Homepage, https://developer.izipay.ao
6
+ Project-URL: Documentation, https://developer.izipay.ao
7
+ Project-URL: Source, https://gitlab.com/suplitel/izipay-sdk-python
8
+ Project-URL: Changelog, https://gitlab.com/suplitel/izipay-sdk-python/-/blob/main/CHANGELOG.md
9
+ Author: Suplitel
10
+ License-Expression: MIT
11
+ License-File: LICENSE
12
+ Keywords: angola,emis,izipay,kwanza,multicaixa,payments
13
+ Classifier: Development Status :: 4 - Beta
14
+ Classifier: Framework :: AsyncIO
15
+ Classifier: Intended Audience :: Developers
16
+ Classifier: Operating System :: OS Independent
17
+ Classifier: Programming Language :: Python :: 3
18
+ Classifier: Programming Language :: Python :: 3 :: Only
19
+ Classifier: Programming Language :: Python :: 3.10
20
+ Classifier: Programming Language :: Python :: 3.11
21
+ Classifier: Programming Language :: Python :: 3.12
22
+ Classifier: Programming Language :: Python :: 3.13
23
+ Classifier: Programming Language :: Python :: 3.14
24
+ Classifier: Topic :: Office/Business :: Financial
25
+ Classifier: Typing :: Typed
26
+ Requires-Python: >=3.10
27
+ Requires-Dist: httpx<1,>=0.25
28
+ Description-Content-Type: text/markdown
29
+
30
+ # IZI Pay Python SDK
31
+
32
+ Official Python client for the IZI Pay payment API (Angola). It handles access tokens, safe retries, errors and
33
+ webhooks for you, so your code only deals with payments.
34
+
35
+ > **Beta (0.x).** The API can still change between 0.x versions. Version 1.0 will follow once the IZI Pay API
36
+ > itself is stable. Pin the exact version you test with.
37
+
38
+ - Python 3.10 or later
39
+ - A sync client (`IziPay`: Django, Flask, Odoo, scripts) and an asyncio client (`AsyncIziPay`: FastAPI) with the
40
+ same methods
41
+ - Sandbox and production
42
+ - MULTICAIXA Express (Webframe, mobile purchase, authorization and capture, QR Code), payment references,
43
+ refunds, terminals, billing (read only) and webhooks
44
+ - One dependency: [httpx](https://www.python-httpx.org). Fully typed (`py.typed`), plain frozen dataclasses
45
+
46
+ ## Install
47
+
48
+ ```bash
49
+ pip install --pre izipay
50
+ ```
51
+
52
+ ## Start
53
+
54
+ ```python
55
+ import os
56
+ from decimal import Decimal
57
+
58
+ from izipay import IziPay
59
+
60
+ with IziPay(
61
+ environment="sandbox", # required: "sandbox" or "production"
62
+ client_id=os.environ["IZIPAY_CLIENT_ID"],
63
+ client_secret=os.environ["IZIPAY_CLIENT_SECRET"],
64
+ ) as izipay:
65
+ payment = izipay.payments.create_reference(
66
+ amount=Decimal("1500"),
67
+ description="Order 1042",
68
+ customer_email="customer@example.com",
69
+ )
70
+ print(f"Pay entity {payment.entity}, reference {payment.reference}")
71
+ ```
72
+
73
+ With asyncio, use `AsyncIziPay` and `await` every call:
74
+
75
+ ```python
76
+ from izipay import AsyncIziPay
77
+
78
+ async with AsyncIziPay(environment="sandbox", client_id=..., client_secret=...) as izipay:
79
+ payment = await izipay.payments.create_reference(amount=Decimal("1500"))
80
+ ```
81
+
82
+ Create one client per set of credentials and reuse it (for example at application start-up): it keeps the access
83
+ token and the HTTP connections. `IziPay` is thread-safe; `AsyncIziPay` is safe to share between tasks of one event
84
+ loop. Only one token request runs at a time. Never put the secret in source control.
85
+
86
+ ## Environments
87
+
88
+ | Environment | Address | Credentials |
89
+ | --- | --- | --- |
90
+ | `"sandbox"` / `Environment.SANDBOX` | `https://pay-sandbox.izipay.ao` | Sandbox Client App |
91
+ | `"production"` / `Environment.PRODUCTION` | `https://pay.izipay.ao` | Production Client App |
92
+
93
+ There is no default environment, so test code can never reach production by accident. Sandbox and production
94
+ credentials are different; using one in the other fails with an `AuthenticationError` that names the environment.
95
+ Ask for credentials at suporte@izipay.ao.
96
+
97
+ ## Payments
98
+
99
+ | Method | What the customer does |
100
+ | --- | --- |
101
+ | `create_webframe` | Pays on a provider-hosted page; open `payment.payment_url` |
102
+ | `create_mobile` | Approves a one-time purchase on their phone |
103
+ | `create_authorization` / `capture` | Approves a reservation; you collect it later with the `authorization_id` |
104
+ | `create_qr_code` | Scans `payment.qr_code_png` or opens `payment.deep_link` |
105
+ | `create_reference` | Pays `entity` + `reference` at an ATM or in their banking app |
106
+
107
+ ```python
108
+ from izipay import PaymentStatus
109
+
110
+ purchase = izipay.payments.create_mobile(
111
+ amount=Decimal("2500"),
112
+ reference="ORDER-1042",
113
+ phone_number="923000000",
114
+ )
115
+
116
+ if purchase.status is PaymentStatus.COMPLETED:
117
+ ... # paid
118
+ elif purchase.status is PaymentStatus.FAILED:
119
+ ... # declined: purchase.error_code, purchase.error_message
120
+ else:
121
+ ... # pending: wait for the webhook or read it later with get()
122
+ ```
123
+
124
+ A declined payment is **returned** with status `FAILED`, not raised. Always check `status`.
125
+
126
+ Amounts are in kwanzas, not cents: `Decimal("2500.50")`, `2500` or `"2500.50"`. A `float` is refused (it cannot
127
+ hold cents exactly), and so is more than 2 decimals. Amounts in answers are always `Decimal`.
128
+
129
+ For a payment by reference, `payment.id` is the reference number, which `get()` and `request_status_sync()` accept.
130
+
131
+ Other operations: `get`, `list`, `request_status_sync` (re-check with the provider when a webhook was missed) and
132
+ `cancel_authorization` (release a reservation; takes the `internal_id`, not the `authorization_id`).
133
+
134
+ ## Time-outs
135
+
136
+ A mobile payment can take up to 90 seconds while the customer approves it on their phone. The SDK waits up to
137
+ 120 seconds per attempt (`timeout=`). Check that your own limits are longer: gunicorn's default worker time-out is
138
+ 30 seconds (`--timeout`), and your web server, load balancer or task queue may have their own.
139
+
140
+ ## Safe retries and idempotency
141
+
142
+ The SDK retries temporary failures (connection problems, time-outs, HTTP 502/503/504, rate limits) **only when
143
+ repeating the request cannot do anything twice**:
144
+
145
+ | Operation | Retried after it was sent? | Why |
146
+ | --- | --- | --- |
147
+ | Reads, token requests, status sync | Yes | They change nothing |
148
+ | Creating a payment (any method) | Yes, with the same idempotency key | IZI Pay returns the existing payment for a repeated key |
149
+ | Refunds, references, cancellations, opening/closing terminals | **No** | There is no idempotency key, so a repeat could do it twice |
150
+
151
+ Every request is retried when it certainly never reached IZI Pay (connection refused, DNS, TLS, connect time-out)
152
+ or was refused by the rate limiter (HTTP 429), because nothing was processed. When IZI Pay itself answers a change
153
+ with an error code and HTTP 5xx, the SDK does not repeat it.
154
+
155
+ Each payment gets an idempotency key. Pass your own (`idempotency_key=str(order.id)`) or store the one the SDK made
156
+ (`payment.idempotency_key`). If no clear answer comes back, you get an `OutcomeUnknownError`:
157
+
158
+ ```python
159
+ from izipay import OutcomeUnknownError
160
+
161
+ try:
162
+ payment = izipay.payments.create_mobile(amount=amount, reference=ref, phone_number=phone)
163
+ except OutcomeUnknownError as error:
164
+ if error.idempotency_key is not None:
165
+ # The payment may exist. Sending the same request with the same key later is safe:
166
+ # IZI Pay returns the existing payment instead of charging again.
167
+ payment = izipay.payments.create_mobile(
168
+ amount=amount, reference=ref, phone_number=phone, idempotency_key=error.idempotency_key
169
+ )
170
+ else:
171
+ ... # refund, reference or terminal operation: look it up before trying again
172
+ ```
173
+
174
+ Defaults: up to 2 retries (`max_retries=`, 0–5) and 120 seconds per attempt.
175
+
176
+ ## Errors
177
+
178
+ Every failure from IZI Pay is an `izipay.IziPayError`. Catch a subclass, or check `error.kind`:
179
+
180
+ | Error | `kind` | Meaning |
181
+ | --- | --- | --- |
182
+ | `AuthenticationError` | `AUTHENTICATION` | Credentials or token rejected |
183
+ | `PermissionDeniedError` | `PERMISSION` | These credentials may not do this (HTTP 403) |
184
+ | `ValidationError` | `VALIDATION` | Something in the request is wrong (HTTP 400); see `error.details` |
185
+ | `NotFoundError` | `NOT_FOUND` | It does not exist for your merchant |
186
+ | `ConflictError` | `CONFLICT` | Clashes with the current state (HTTP 409) |
187
+ | `NotAvailableError` | `NOT_AVAILABLE` | Feature switched off for your merchant, for example `CHECKOUT_DISABLED` |
188
+ | `RateLimitedError` | `RATE_LIMITED` | Too many requests, even after waiting. Nothing was processed |
189
+ | `ConnectionFailedError` | `CONNECTION` | IZI Pay could not be reached. Nothing was sent |
190
+ | `ServerError` | `SERVER` | IZI Pay had an error while reading data |
191
+ | `OutcomeUnknownError` | `OUTCOME_UNKNOWN` | Sent, but no clear answer came back |
192
+ | `InvalidResponseError` | `INVALID_RESPONSE` | An answer the SDK could not read |
193
+
194
+ (`PermissionDeniedError` and `ConnectionFailedError` are named so they do not clash with Python's built-in
195
+ `PermissionError` and `ConnectionError`.)
196
+
197
+ Other attributes: `status_code`, `error_code` (IZI Pay's own code, such as `INVALID_OPERATION`), `details`,
198
+ `trace_id` (quote it to support) and `is_safe_to_retry`. Errors can be pickled with their fields (Celery,
199
+ multiprocessing).
200
+
201
+ Mistakes the SDK can see before sending (a missing phone number, a negative amount, a `float` amount, a date
202
+ without a time zone, ...) raise `ValueError` or `TypeError` and nothing is sent.
203
+
204
+ ## Webhooks
205
+
206
+ IZI Pay sends the `Access-Key` you chose during onboarding with every notification. It only stops resending when your
207
+ endpoint answers HTTP 2xx with `"Success": true`.
208
+
209
+ ```python
210
+ from izipay import Webhooks
211
+
212
+ webhooks = Webhooks(os.environ["IZIPAY_WEBHOOK_ACCESS_KEY"])
213
+
214
+
215
+ # FastAPI
216
+ @app.post("/izipay/reference-payments")
217
+ async def reference_payment(request: Request) -> Response:
218
+ if not webhooks.is_authentic(request.headers.get("Access-Key")):
219
+ return Response(status_code=401)
220
+
221
+ payment = webhooks.parse_reference_payment(await request.body())
222
+
223
+ # Notifications can arrive more than once: use payment.id to process each only once.
224
+ order_id = await orders.mark_paid(payment.reference, payment.amount_paid, payment.id)
225
+
226
+ return Response(Webhooks.acknowledge(order_id), media_type="application/json")
227
+ ```
228
+
229
+ In Django, read the key with `request.headers.get("Access-Key")` and the body with `request.body`. Use
230
+ `parse_qr_code_payment` on your QR Code webhook URL. The key is compared in constant time.
231
+
232
+ ## Other areas
233
+
234
+ ```python
235
+ from izipay import CreateReferenceRequest
236
+
237
+ izipay.references.create(amount=Decimal("1000"))
238
+ izipay.references.create_bulk([CreateReferenceRequest(amount=5), CreateReferenceRequest(amount=6)])
239
+ izipay.references.get("584923109")
240
+ izipay.refunds.create(payment_id=payment_id, amount=Decimal("500"), supervisor_id="...")
241
+ izipay.terminals.get_status("POS-ID")
242
+ izipay.billing.get_current_usage()
243
+ ```
244
+
245
+ ## Dates
246
+
247
+ The gateway writes most dates in Luanda time without an offset. The SDK reads them as UTC+01:00 and returns
248
+ timezone-aware `datetime` values, so they are correct whatever time zone your server uses. Dates you pass in
249
+ (`expiry_date`, `start_date`, ...) must be timezone-aware too, for example
250
+ `datetime(2026, 12, 31, 23, 59, tzinfo=izipay.LUANDA)`.
251
+
252
+ ## Logging
253
+
254
+ The SDK logs timings (DEBUG) and retries (WARNING) to the `izipay` logger, or to the `logger=` you pass. It never
255
+ logs request or response bodies, tokens, secrets or phone numbers.
256
+
257
+ ## Your own HTTP client
258
+
259
+ Pass `http_client=httpx.Client(...)` (or `httpx.AsyncClient` for `AsyncIziPay`) to use a proxy or your own
260
+ connection settings. The SDK still applies its time-out to each request, never follows redirects, and does not
261
+ close a client you passed in.
262
+
263
+ ## Development
264
+
265
+ ```bash
266
+ python -m venv .venv
267
+ .venv/bin/pip install -e . --group dev
268
+ .venv/bin/pytest # unit tests (sync and async) and integration tests with a local server
269
+ .venv/bin/mypy # strict, checked as Python 3.10
270
+ .venv/bin/ruff check . && .venv/bin/ruff format --check .
271
+ .venv/bin/python tools/sandbox_check.py # against the real sandbox; needs sandbox credentials
272
+ ```
@@ -0,0 +1,243 @@
1
+ # IZI Pay Python SDK
2
+
3
+ Official Python client for the IZI Pay payment API (Angola). It handles access tokens, safe retries, errors and
4
+ webhooks for you, so your code only deals with payments.
5
+
6
+ > **Beta (0.x).** The API can still change between 0.x versions. Version 1.0 will follow once the IZI Pay API
7
+ > itself is stable. Pin the exact version you test with.
8
+
9
+ - Python 3.10 or later
10
+ - A sync client (`IziPay`: Django, Flask, Odoo, scripts) and an asyncio client (`AsyncIziPay`: FastAPI) with the
11
+ same methods
12
+ - Sandbox and production
13
+ - MULTICAIXA Express (Webframe, mobile purchase, authorization and capture, QR Code), payment references,
14
+ refunds, terminals, billing (read only) and webhooks
15
+ - One dependency: [httpx](https://www.python-httpx.org). Fully typed (`py.typed`), plain frozen dataclasses
16
+
17
+ ## Install
18
+
19
+ ```bash
20
+ pip install --pre izipay
21
+ ```
22
+
23
+ ## Start
24
+
25
+ ```python
26
+ import os
27
+ from decimal import Decimal
28
+
29
+ from izipay import IziPay
30
+
31
+ with IziPay(
32
+ environment="sandbox", # required: "sandbox" or "production"
33
+ client_id=os.environ["IZIPAY_CLIENT_ID"],
34
+ client_secret=os.environ["IZIPAY_CLIENT_SECRET"],
35
+ ) as izipay:
36
+ payment = izipay.payments.create_reference(
37
+ amount=Decimal("1500"),
38
+ description="Order 1042",
39
+ customer_email="customer@example.com",
40
+ )
41
+ print(f"Pay entity {payment.entity}, reference {payment.reference}")
42
+ ```
43
+
44
+ With asyncio, use `AsyncIziPay` and `await` every call:
45
+
46
+ ```python
47
+ from izipay import AsyncIziPay
48
+
49
+ async with AsyncIziPay(environment="sandbox", client_id=..., client_secret=...) as izipay:
50
+ payment = await izipay.payments.create_reference(amount=Decimal("1500"))
51
+ ```
52
+
53
+ Create one client per set of credentials and reuse it (for example at application start-up): it keeps the access
54
+ token and the HTTP connections. `IziPay` is thread-safe; `AsyncIziPay` is safe to share between tasks of one event
55
+ loop. Only one token request runs at a time. Never put the secret in source control.
56
+
57
+ ## Environments
58
+
59
+ | Environment | Address | Credentials |
60
+ | --- | --- | --- |
61
+ | `"sandbox"` / `Environment.SANDBOX` | `https://pay-sandbox.izipay.ao` | Sandbox Client App |
62
+ | `"production"` / `Environment.PRODUCTION` | `https://pay.izipay.ao` | Production Client App |
63
+
64
+ There is no default environment, so test code can never reach production by accident. Sandbox and production
65
+ credentials are different; using one in the other fails with an `AuthenticationError` that names the environment.
66
+ Ask for credentials at suporte@izipay.ao.
67
+
68
+ ## Payments
69
+
70
+ | Method | What the customer does |
71
+ | --- | --- |
72
+ | `create_webframe` | Pays on a provider-hosted page; open `payment.payment_url` |
73
+ | `create_mobile` | Approves a one-time purchase on their phone |
74
+ | `create_authorization` / `capture` | Approves a reservation; you collect it later with the `authorization_id` |
75
+ | `create_qr_code` | Scans `payment.qr_code_png` or opens `payment.deep_link` |
76
+ | `create_reference` | Pays `entity` + `reference` at an ATM or in their banking app |
77
+
78
+ ```python
79
+ from izipay import PaymentStatus
80
+
81
+ purchase = izipay.payments.create_mobile(
82
+ amount=Decimal("2500"),
83
+ reference="ORDER-1042",
84
+ phone_number="923000000",
85
+ )
86
+
87
+ if purchase.status is PaymentStatus.COMPLETED:
88
+ ... # paid
89
+ elif purchase.status is PaymentStatus.FAILED:
90
+ ... # declined: purchase.error_code, purchase.error_message
91
+ else:
92
+ ... # pending: wait for the webhook or read it later with get()
93
+ ```
94
+
95
+ A declined payment is **returned** with status `FAILED`, not raised. Always check `status`.
96
+
97
+ Amounts are in kwanzas, not cents: `Decimal("2500.50")`, `2500` or `"2500.50"`. A `float` is refused (it cannot
98
+ hold cents exactly), and so is more than 2 decimals. Amounts in answers are always `Decimal`.
99
+
100
+ For a payment by reference, `payment.id` is the reference number, which `get()` and `request_status_sync()` accept.
101
+
102
+ Other operations: `get`, `list`, `request_status_sync` (re-check with the provider when a webhook was missed) and
103
+ `cancel_authorization` (release a reservation; takes the `internal_id`, not the `authorization_id`).
104
+
105
+ ## Time-outs
106
+
107
+ A mobile payment can take up to 90 seconds while the customer approves it on their phone. The SDK waits up to
108
+ 120 seconds per attempt (`timeout=`). Check that your own limits are longer: gunicorn's default worker time-out is
109
+ 30 seconds (`--timeout`), and your web server, load balancer or task queue may have their own.
110
+
111
+ ## Safe retries and idempotency
112
+
113
+ The SDK retries temporary failures (connection problems, time-outs, HTTP 502/503/504, rate limits) **only when
114
+ repeating the request cannot do anything twice**:
115
+
116
+ | Operation | Retried after it was sent? | Why |
117
+ | --- | --- | --- |
118
+ | Reads, token requests, status sync | Yes | They change nothing |
119
+ | Creating a payment (any method) | Yes, with the same idempotency key | IZI Pay returns the existing payment for a repeated key |
120
+ | Refunds, references, cancellations, opening/closing terminals | **No** | There is no idempotency key, so a repeat could do it twice |
121
+
122
+ Every request is retried when it certainly never reached IZI Pay (connection refused, DNS, TLS, connect time-out)
123
+ or was refused by the rate limiter (HTTP 429), because nothing was processed. When IZI Pay itself answers a change
124
+ with an error code and HTTP 5xx, the SDK does not repeat it.
125
+
126
+ Each payment gets an idempotency key. Pass your own (`idempotency_key=str(order.id)`) or store the one the SDK made
127
+ (`payment.idempotency_key`). If no clear answer comes back, you get an `OutcomeUnknownError`:
128
+
129
+ ```python
130
+ from izipay import OutcomeUnknownError
131
+
132
+ try:
133
+ payment = izipay.payments.create_mobile(amount=amount, reference=ref, phone_number=phone)
134
+ except OutcomeUnknownError as error:
135
+ if error.idempotency_key is not None:
136
+ # The payment may exist. Sending the same request with the same key later is safe:
137
+ # IZI Pay returns the existing payment instead of charging again.
138
+ payment = izipay.payments.create_mobile(
139
+ amount=amount, reference=ref, phone_number=phone, idempotency_key=error.idempotency_key
140
+ )
141
+ else:
142
+ ... # refund, reference or terminal operation: look it up before trying again
143
+ ```
144
+
145
+ Defaults: up to 2 retries (`max_retries=`, 0–5) and 120 seconds per attempt.
146
+
147
+ ## Errors
148
+
149
+ Every failure from IZI Pay is an `izipay.IziPayError`. Catch a subclass, or check `error.kind`:
150
+
151
+ | Error | `kind` | Meaning |
152
+ | --- | --- | --- |
153
+ | `AuthenticationError` | `AUTHENTICATION` | Credentials or token rejected |
154
+ | `PermissionDeniedError` | `PERMISSION` | These credentials may not do this (HTTP 403) |
155
+ | `ValidationError` | `VALIDATION` | Something in the request is wrong (HTTP 400); see `error.details` |
156
+ | `NotFoundError` | `NOT_FOUND` | It does not exist for your merchant |
157
+ | `ConflictError` | `CONFLICT` | Clashes with the current state (HTTP 409) |
158
+ | `NotAvailableError` | `NOT_AVAILABLE` | Feature switched off for your merchant, for example `CHECKOUT_DISABLED` |
159
+ | `RateLimitedError` | `RATE_LIMITED` | Too many requests, even after waiting. Nothing was processed |
160
+ | `ConnectionFailedError` | `CONNECTION` | IZI Pay could not be reached. Nothing was sent |
161
+ | `ServerError` | `SERVER` | IZI Pay had an error while reading data |
162
+ | `OutcomeUnknownError` | `OUTCOME_UNKNOWN` | Sent, but no clear answer came back |
163
+ | `InvalidResponseError` | `INVALID_RESPONSE` | An answer the SDK could not read |
164
+
165
+ (`PermissionDeniedError` and `ConnectionFailedError` are named so they do not clash with Python's built-in
166
+ `PermissionError` and `ConnectionError`.)
167
+
168
+ Other attributes: `status_code`, `error_code` (IZI Pay's own code, such as `INVALID_OPERATION`), `details`,
169
+ `trace_id` (quote it to support) and `is_safe_to_retry`. Errors can be pickled with their fields (Celery,
170
+ multiprocessing).
171
+
172
+ Mistakes the SDK can see before sending (a missing phone number, a negative amount, a `float` amount, a date
173
+ without a time zone, ...) raise `ValueError` or `TypeError` and nothing is sent.
174
+
175
+ ## Webhooks
176
+
177
+ IZI Pay sends the `Access-Key` you chose during onboarding with every notification. It only stops resending when your
178
+ endpoint answers HTTP 2xx with `"Success": true`.
179
+
180
+ ```python
181
+ from izipay import Webhooks
182
+
183
+ webhooks = Webhooks(os.environ["IZIPAY_WEBHOOK_ACCESS_KEY"])
184
+
185
+
186
+ # FastAPI
187
+ @app.post("/izipay/reference-payments")
188
+ async def reference_payment(request: Request) -> Response:
189
+ if not webhooks.is_authentic(request.headers.get("Access-Key")):
190
+ return Response(status_code=401)
191
+
192
+ payment = webhooks.parse_reference_payment(await request.body())
193
+
194
+ # Notifications can arrive more than once: use payment.id to process each only once.
195
+ order_id = await orders.mark_paid(payment.reference, payment.amount_paid, payment.id)
196
+
197
+ return Response(Webhooks.acknowledge(order_id), media_type="application/json")
198
+ ```
199
+
200
+ In Django, read the key with `request.headers.get("Access-Key")` and the body with `request.body`. Use
201
+ `parse_qr_code_payment` on your QR Code webhook URL. The key is compared in constant time.
202
+
203
+ ## Other areas
204
+
205
+ ```python
206
+ from izipay import CreateReferenceRequest
207
+
208
+ izipay.references.create(amount=Decimal("1000"))
209
+ izipay.references.create_bulk([CreateReferenceRequest(amount=5), CreateReferenceRequest(amount=6)])
210
+ izipay.references.get("584923109")
211
+ izipay.refunds.create(payment_id=payment_id, amount=Decimal("500"), supervisor_id="...")
212
+ izipay.terminals.get_status("POS-ID")
213
+ izipay.billing.get_current_usage()
214
+ ```
215
+
216
+ ## Dates
217
+
218
+ The gateway writes most dates in Luanda time without an offset. The SDK reads them as UTC+01:00 and returns
219
+ timezone-aware `datetime` values, so they are correct whatever time zone your server uses. Dates you pass in
220
+ (`expiry_date`, `start_date`, ...) must be timezone-aware too, for example
221
+ `datetime(2026, 12, 31, 23, 59, tzinfo=izipay.LUANDA)`.
222
+
223
+ ## Logging
224
+
225
+ The SDK logs timings (DEBUG) and retries (WARNING) to the `izipay` logger, or to the `logger=` you pass. It never
226
+ logs request or response bodies, tokens, secrets or phone numbers.
227
+
228
+ ## Your own HTTP client
229
+
230
+ Pass `http_client=httpx.Client(...)` (or `httpx.AsyncClient` for `AsyncIziPay`) to use a proxy or your own
231
+ connection settings. The SDK still applies its time-out to each request, never follows redirects, and does not
232
+ close a client you passed in.
233
+
234
+ ## Development
235
+
236
+ ```bash
237
+ python -m venv .venv
238
+ .venv/bin/pip install -e . --group dev
239
+ .venv/bin/pytest # unit tests (sync and async) and integration tests with a local server
240
+ .venv/bin/mypy # strict, checked as Python 3.10
241
+ .venv/bin/ruff check . && .venv/bin/ruff format --check .
242
+ .venv/bin/python tools/sandbox_check.py # against the real sandbox; needs sandbox credentials
243
+ ```
@@ -0,0 +1,83 @@
1
+ [build-system]
2
+ requires = ["hatchling>=1.27"]
3
+ build-backend = "hatchling.build"
4
+
5
+ [project]
6
+ name = "izipay"
7
+ dynamic = ["version"]
8
+ description = "Official Python SDK for the IZI Pay payment API (Angola): MULTICAIXA Express, payment references, refunds and webhooks."
9
+ readme = "README.md"
10
+ license = "MIT"
11
+ license-files = ["LICENSE"]
12
+ authors = [{ name = "Suplitel" }]
13
+ requires-python = ">=3.10"
14
+ dependencies = ["httpx>=0.25,<1"]
15
+ keywords = ["izipay", "angola", "payments", "multicaixa", "emis", "kwanza"]
16
+ classifiers = [
17
+ "Development Status :: 4 - Beta",
18
+ "Intended Audience :: Developers",
19
+ "Operating System :: OS Independent",
20
+ "Programming Language :: Python :: 3",
21
+ "Programming Language :: Python :: 3 :: Only",
22
+ "Programming Language :: Python :: 3.10",
23
+ "Programming Language :: Python :: 3.11",
24
+ "Programming Language :: Python :: 3.12",
25
+ "Programming Language :: Python :: 3.13",
26
+ "Programming Language :: Python :: 3.14",
27
+ "Framework :: AsyncIO",
28
+ "Topic :: Office/Business :: Financial",
29
+ "Typing :: Typed",
30
+ ]
31
+
32
+ [project.urls]
33
+ Homepage = "https://developer.izipay.ao"
34
+ Documentation = "https://developer.izipay.ao"
35
+ Source = "https://gitlab.com/suplitel/izipay-sdk-python"
36
+ Changelog = "https://gitlab.com/suplitel/izipay-sdk-python/-/blob/main/CHANGELOG.md"
37
+
38
+ [dependency-groups]
39
+ dev = [
40
+ "pytest>=8",
41
+ "respx>=0.21",
42
+ "mypy>=1.10",
43
+ "ruff>=0.6",
44
+ ]
45
+
46
+ [tool.hatch.version]
47
+ path = "src/izipay/_version.py"
48
+
49
+ [tool.hatch.build.targets.wheel]
50
+ packages = ["src/izipay"]
51
+
52
+ [tool.hatch.build.targets.sdist]
53
+ include = ["src/izipay", "tests", "README.md", "CHANGELOG.md", "LICENSE"]
54
+
55
+ [tool.pytest.ini_options]
56
+ testpaths = ["tests"]
57
+ addopts = "-ra --strict-markers"
58
+ markers = ["integration: runs the SDK against a local HTTP server"]
59
+ filterwarnings = ["error"]
60
+
61
+ [tool.mypy]
62
+ strict = true
63
+ python_version = "3.10"
64
+ files = ["src", "tests", "tools"]
65
+
66
+ [tool.ruff]
67
+ line-length = 120
68
+ target-version = "py310"
69
+ src = ["src", "tests"]
70
+
71
+ [tool.ruff.lint]
72
+ select = ["E", "F", "W", "I", "UP", "B", "A", "C4", "SIM", "RUF", "PT", "S", "N", "PL", "PERF", "T20"]
73
+ ignore = [
74
+ "PLR0911", # many returns in mapping functions read better than nested conditions
75
+ "PLR0912",
76
+ "PLR0913", # the public methods take the API's fields as keyword arguments
77
+ "PLR0915",
78
+ "PLR2004", # HTTP status codes are clearer than named constants
79
+ ]
80
+
81
+ [tool.ruff.lint.per-file-ignores]
82
+ "tests/**" = ["S101", "S105", "S106", "PLC0415", "PLR0917"]
83
+ "tools/**" = ["T201", "S603", "S607"]