Webhooks with the Python SDK
When a customer pays, IZI Pay sends a notification to the webhook URL you gave during onboarding. The Webhooks class helps you:
- check that the notification really comes from IZI Pay;
- read it into a typed object;
- answer in the exact format IZI Pay expects.
How delivery and retries work is explained in Webhooks. The Webhooks class does not need an IziPay client or your Client App credentials, and it works the same in sync and async code: it never calls IZI Pay.
Set up
During onboarding you chose an Access-Key: a secret that IZI Pay sends in the Access-Key header of every notification. Give the same value to the SDK.
Python
Receive a payment by reference
The body can be given as bytes or str. In any other framework, pass the Access-Key header (or None when it is missing) and the raw body.
A reference notification contains:
| Field | Meaning |
|---|---|
id | IZI Pay's ID for this notification. Use it to ignore repeats |
reference | The reference that was paid |
amount_paid | Amount paid, in kwanzas (Decimal) |
paid_at | When the customer paid (timezone-aware datetime) |
transaction_id, system_log_number, system_log_id | Transaction identifiers, useful for reconciliation |
terminal_type, terminal_id, terminal_location | Where the customer paid, for example an ATM |
nib, bank | The payer's account and bank, when sent |
Receive a QR Code payment
Same steps, on your QR Code webhook URL:
Python
Answer
| Call | When | IZI Pay then |
|---|---|---|
Webhooks.acknowledge(order_id) | You handled it, or had already handled it before | Stops sending it |
Webhooks.acknowledge(order_id, "Payment already processed") | Same, with your own note | Stops sending it |
Webhooks.reject(order_id, "Database unavailable") | You could not handle it now | Sends it again later |
The first argument is required: your own ID for the order or payment. The note is optional for acknowledge and required for reject. Both return the JSON text to send back; answer reject with an HTTP 5xx status.
Always answer acknowledge for a repeat you already handled. Answering an error makes IZI Pay keep resending it.
Other checks
webhooks.ensure_authentic(header)does the same asis_authenticbut raisesWebhookErrorwhen the key is wrong.parse_reference_paymentandparse_qr_code_paymentraiseizipay.WebhookErrorwhen the body is empty or is not a valid notification. Answer HTTP 400 in that case.- The key is compared in a way that takes the same time whether it is right or wrong (
hmac.compare_digest), so it cannot be guessed by measuring answers. The SDK keeps only a hash of the key.