izipay.payments creates payments with every IZI Pay payment method and lets you follow them. Each example below shows every parameter. Lines marked Required must be sent; lines marked Optional can be left out, and the comment says what happens if you do.
All parameters are passed by name. The examples use the sync client; with AsyncIziPay, write await before each call. Everything else is the same.
Method
The customer
Learn more
create_reference
Pays an entity and reference at an ATM or in their banking app
Every create method returns a CreatedPayment. Always check its status. A payment the customer declined is returned with statusPaymentStatus.FAILED and an error_code and error_message; it is not raised as an exception.
Values are checked before anything is sent: a missing or wrong value raises ValueError or TypeError.
payment = izipay.payments.create_reference( # Required. Amount in kwanzas (AOA), not cents: Decimal, int or str. Must be more than 0 for a Dynamic # reference. For a Charging reference, 0 lets the customer choose the amount. amount=Decimal("15000"), # Optional. ReferenceType.DYNAMIC (default): one payment of a fixed amount, such as an order. # ReferenceType.CHARGING: a long-lived reference that can receive several payments, such as a customer account. reference_type=ReferenceType.DYNAMIC, # Optional. Your own reference number. Leave it out and IZI Pay generates one. reference=None, # Optional. When the reference stops accepting payments. Must be timezone-aware. # Default: one month after creation for Dynamic, end of 2099 for Charging. expiry_date=datetime.now(LUANDA) + timedelta(days=3), # Optional. Customer details, kept with the payment. customer_name="Ana Silva", customer_email="ana@example.com", customer_telephone="923000000", # Optional. Your invoice or document number. document_number="FT 2026/1042", # Optional. What is being paid. description="Order 1042", # Optional. Your own data, returned when you read the payment. custom={"order_id": "1042"}, # Optional, recommended. Sending the same request again with this key never creates a second reference. # Leave it out and the SDK makes one (returned in payment.idempotency_key). idempotency_key="order-1042",)expires = payment.expires_at.strftime("%d/%m/%Y %H:%M") if payment.expires_at else "-"print(f"Entity {payment.entity}, reference {payment.reference}, expires {expires}")
Show the entity and reference to the customer. The webhook tells you when they have paid. To read the payment later, use payment.id: for a payment by reference it is the reference number.
One-time purchase on the customer's phone
The answer can take up to about 90 seconds while the customer approves on their phone. Check your server's time-outs: see Time-outs on your server. In async code the wait does not block other requests.
QR Code
Python
qr = izipay.payments.create_qr_code( # Required. Amount in kwanzas, more than 0. amount=Decimal("1200"), # Required. Your reference for this payment. Up to 100 characters. reference="TABLE-7", # Optional. Image size. Default: "MEDIUM". qr_size="MEDIUM", # Optional. QR Code behaviour. Default: "STATIC". qr_type="STATIC", # Optional. How many payments the code accepts, at least 1. Default: 1. max_transactions=1, # Optional. When the code stops working. Must be timezone-aware. Default: 24 hours after creation. end_date=datetime.now(LUANDA) + timedelta(hours=2), # Optional. True (default): the answer includes the payment ID, the image and a deep link for phones. # False: IZI Pay answers with the image only, without a payment ID. Keep the default. include_deep_link=True, # Optional. What is being paid. description="Table 7", # Optional. Your own data, returned when you read the payment. custom={"table": "7"}, # Optional, recommended. idempotency_key="bill-7781",)if qr.qr_code_png is not None: with open("qr.png", "wb") as image: # show it on screen or print it image.write(qr.qr_code_png)print(f"Payment ID {qr.id}") # keep it to check the status laterprint(f"On a phone, open {qr.deep_link}") # opens the Multicaixa Express app directly
To show the image in a web page without saving a file, use a data URL: "data:image/png;base64," + base64.b64encode(qr.qr_code_png).decode().
Webframe checkout page
Python
checkout = izipay.payments.create_webframe( # Required. Amount in kwanzas, more than 0. amount=Decimal("8900"), # Required. Your reference for this payment. Up to 100 characters. reference="ORDER-1044", # Optional. A public HTTPS stylesheet ending in .css for the payment page. Leave it out for the standard look. css_url="https://shop.example.ao/izipay-checkout.css", # Optional. Page settings agreed for your merchant. Leave them out for the defaults: # qr_code "DISABLED", mobile "AUTHORIZATION", card "AUTHORIZATION". qr_code="DISABLED", mobile="AUTHORIZATION", card="AUTHORIZATION", # Optional. What is being paid. description="Order 1044", # Optional. Your own data, returned when you read the payment. custom={"order_id": "1044"}, # Optional, recommended. idempotency_key="order-1044",)redirect_to(checkout.payment_url) # send the customer to the payment page, e.g. Django's redirect()
checkout.expires_at says until when the page can be used. Creating the page does not mean the customer paid: follow the payment's status.
Reserve now, collect later
An authorization reserves money on the customer's account. A capture collects all or part of it. If you will not collect it, cancel the authorization to release the money.
Python
# 1. Reservehold = izipay.payments.create_authorization( amount=Decimal("50000"), # Required. Amount to reserve, in kwanzas. reference="BOOKING-88", # Required. Your reference. Up to 100 characters. phone_number="923000000", # Required. The customer's Multicaixa Express phone number. provider="UNITEL", # Optional. The mobile provider agreed during onboarding. description="Room 12, 3 nights", # Optional. custom={"booking_id": "88"}, # Optional. idempotency_key="booking-88-hold", # Optional, recommended.)if hold.status is PaymentStatus.AUTHORIZED: # Keep both IDs with your booking: authorization_id to capture, internal_id to cancel. bookings.save_hold("88", authorization_id=hold.authorization_id, internal_id=hold.internal_id)# Later: load them back (here booking.authorization_id and booking.internal_id are str).booking = bookings.get("88")# 2a. Collect all or part of itcapture = izipay.payments.capture( amount=Decimal("42000"), # Required. Amount to collect, up to what was reserved. reference="BOOKING-88-CHECKOUT", # Required. Your reference for this capture. authorization_id=booking.authorization_id, # Required. From the authorization. Not its internal_id. description="Check-out", # Optional. custom={"booking_id": "88"}, # Optional. idempotency_key="booking-88-capture-1", # Optional, recommended. A new key for each capture.)# 2b. Or release the reservation without collectingcancellation = izipay.payments.cancel_authorization( booking.internal_id, # Required. The authorization's internal_id. Not its authorization_id.)
Capture uses authorization_id; cancel uses internal_id. The SDK never repeats a cancellation after it was sent. If it raises OutcomeUnknownError, read the payment before trying again.
What a created payment contains
Which fields are filled depends on the method. Fields that are not filled are None.
Field
Filled for
Meaning
id
All (except an image-only QR Code)
Use it with get and request_status_sync. For a payment by reference, it is the reference number
reference_record_id
Payment by reference
The ID IZI Pay gave the reference record. You can't read the payment with it; use id
internal_id
Most methods
IZI Pay's own ID. Needed to cancel an authorization
True when IZI Pay returned an existing payment for a repeated key
custom_metadata, additional_data
When IZI Pay returns them
Your custom data, and any other data, as dicts
Send the same payment again
If creating a payment raises OutcomeUnknownError, send the same request with the key from the exception. IZI Pay returns the existing payment instead of charging again.
Python
try: purchase = izipay.payments.create_mobile( amount=Decimal("2500"), reference="ORDER-1043", phone_number="923000000" )except OutcomeUnknownError as error: # Later, for example from a queued job: purchase = izipay.payments.create_mobile( amount=Decimal("2500"), reference="ORDER-1043", phone_number="923000000", idempotency_key=error.idempotency_key, # Required here. The key from the exception. )
Every filter is optional. Without any, you get the 20 most recent payments.
Python
page = izipay.payments.list( page_number=1, # Optional. Default 1. page_size=50, # Optional. 1 to 100. Default 20. status=PaymentStatus.COMPLETED, # Optional. Only this status. payment_type=PaymentType.PPR, # Optional. PPR (references) or GPO (Multicaixa Express). start_date=datetime.now(LUANDA) - timedelta(days=1), # Optional. Created on or after. Timezone-aware. end_date=datetime.now(LUANDA), # Optional. Created on or before. Timezone-aware. search="ORDER-1042", # Optional. Free text, such as your reference.)for p in page.items: print(f"{p.reference}: {p.status.value} {p.amount}")# page.has_more is True when there is another page: ask for page_number + 1.
Ask IZI Pay to check a payment again
If you expected a webhook and it has not arrived, ask IZI Pay to check the status with the provider. The check runs in the background: read the payment a few seconds later.
Python
izipay.payments.request_status_sync( "497693862", # Required. The payment's id.)
purchase = izipay.payments.create_mobile( # Required. Amount in kwanzas, more than 0. amount=Decimal("2500"), # Required. Your reference for this payment, such as the order number. Up to 100 characters. reference="ORDER-1043", # Required. The customer's Multicaixa Express phone number. phone_number="923000000", # Optional. The mobile provider agreed during onboarding, for example "UNITEL". Left out: not sent. provider="UNITEL", # Optional. What is being paid. description="Order 1043", # Optional. Your own data, returned when you read the payment. custom={"order_id": "1043"}, # Optional, recommended. See Idempotency keys on the overview page. idempotency_key="order-1043",)if purchase.status is PaymentStatus.COMPLETED: ... # Paid. Confirm the order.elif purchase.status is PaymentStatus.FAILED: print(f"{purchase.error_code}: {purchase.error_message}") # Declined or not completed.else: ... # PENDING or PROCESSING. Wait for the webhook, or read the payment again later.