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.
- izipay-0.1.0b1/.gitignore +14 -0
- izipay-0.1.0b1/CHANGELOG.md +27 -0
- izipay-0.1.0b1/LICENSE +21 -0
- izipay-0.1.0b1/PKG-INFO +272 -0
- izipay-0.1.0b1/README.md +243 -0
- izipay-0.1.0b1/pyproject.toml +83 -0
- izipay-0.1.0b1/src/izipay/__init__.py +130 -0
- izipay-0.1.0b1/src/izipay/_async_client.py +644 -0
- izipay-0.1.0b1/src/izipay/_client.py +644 -0
- izipay-0.1.0b1/src/izipay/_enums.py +237 -0
- izipay-0.1.0b1/src/izipay/_internal/__init__.py +1 -0
- izipay-0.1.0b1/src/izipay/_internal/core.py +482 -0
- izipay-0.1.0b1/src/izipay/_internal/data.py +178 -0
- izipay-0.1.0b1/src/izipay/_internal/dates.py +65 -0
- izipay-0.1.0b1/src/izipay/_internal/error_parser.py +119 -0
- izipay-0.1.0b1/src/izipay/_internal/guard.py +120 -0
- izipay-0.1.0b1/src/izipay/_internal/operations.py +998 -0
- izipay-0.1.0b1/src/izipay/_internal/setup.py +102 -0
- izipay-0.1.0b1/src/izipay/_internal/tokens.py +163 -0
- izipay-0.1.0b1/src/izipay/_internal/transport.py +173 -0
- izipay-0.1.0b1/src/izipay/_version.py +1 -0
- izipay-0.1.0b1/src/izipay/errors.py +304 -0
- izipay-0.1.0b1/src/izipay/models.py +358 -0
- izipay-0.1.0b1/src/izipay/py.typed +0 -0
- izipay-0.1.0b1/src/izipay/webhooks.py +214 -0
- izipay-0.1.0b1/tests/__init__.py +0 -0
- izipay-0.1.0b1/tests/conftest.py +35 -0
- izipay-0.1.0b1/tests/integration/__init__.py +0 -0
- izipay-0.1.0b1/tests/integration/test_real_http.py +239 -0
- izipay-0.1.0b1/tests/support.py +255 -0
- izipay-0.1.0b1/tests/unit/__init__.py +0 -0
- izipay-0.1.0b1/tests/unit/test_client_core.py +528 -0
- izipay-0.1.0b1/tests/unit/test_operations.py +576 -0
- izipay-0.1.0b1/tests/unit/test_parity_and_internals.py +115 -0
- izipay-0.1.0b1/tests/unit/test_webhooks.py +88 -0
|
@@ -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.
|
izipay-0.1.0b1/PKG-INFO
ADDED
|
@@ -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
|
+
```
|
izipay-0.1.0b1/README.md
ADDED
|
@@ -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"]
|