This page covers everything in the Python SDK besides creating payments. As on the other pages, each example shows every parameter, marked Required or Optional. The examples use the sync client; with AsyncIziPay, write await before each call.
Never repeated automatically
Creating or cancelling a reference, creating a refund, and opening or closing a terminal have no idempotency key. The SDK never sends them twice. If one raises OutcomeUnknownError, look it up before trying again.
izipay.references works with payment references directly. To create a reference as a payment, with an idempotency key, you can also use payments.create_reference.
Create a reference
Python
reference = izipay.references.create( # Required for Dynamic (more than 0). For Charging, 0 or None lets the customer choose the amount. amount=Decimal("15000"), # Optional. ReferenceType.DYNAMIC (default): one payment of a fixed amount. # ReferenceType.CHARGING: a long-lived reference that can receive several payments. 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. expiry_date=datetime.now(LUANDA) + timedelta(days=3), # Optional. What is being paid. description="Invoice FT 2026/1042", # Optional. Customer details. customer_name="Ana Silva", customer_email="ana@example.com", customer_telephone="923000000", # Optional. Your invoice or document number. document_number="FT 2026/1042", # Optional. Your own data, returned when you read the reference. custom_metadata={"invoice_id": "1042"},)print(f"Entity {reference.entity}, reference {reference.reference}, {reference.reference_status.value}")
Create up to 100 references at once
Each CreateReferenceRequest takes the same parameters as create above, and is checked as soon as you build it. Some references can succeed while others fail, so check both lists.
Python
result = izipay.references.create_bulk( [ # Required. 1 to 100 requests. CreateReferenceRequest(amount=Decimal("5000"), description="Student 551 - November"), CreateReferenceRequest(amount=Decimal("5000"), description="Student 552 - November"), ])print(f"{result.success_count} created, {result.error_count} failed")for created in result.references: print(created.reference)for failure in result.errors: print(failure) # IZI Pay's description of each failure
Read, follow and cancel
Python
# Read a reference and the status of its paymentcurrent = izipay.references.get( "584923109", # Required. The reference number.)# Every payment made to it (a Charging reference can receive several)history = izipay.references.get_history( "584923109", # Required.)# Stop it accepting payments. Only works while it has not been paid.izipay.references.cancel( "584923109", # Required.)
reference_status tells you about the reference itself (ACTIVE, PAID, CANCELLED, EXPIRED); status tells you about its payment.
List references
Python
page = izipay.references.list( page_number=1, # Optional. Default 1. page_size=50, # Optional. 1 to 100. Default 20. reference_type=ReferenceType.DYNAMIC, # Optional. Only this type. status=PaymentStatus.COMPLETED, # Optional. Only references whose payment has this status.)
Refunds
Return money to a customer
You can refund all or part of a completed payment. For an authorization, refund the specific capture; to release money that was reserved but never collected, cancel the authorization instead.
Python
refund = izipay.refunds.create( payment_id="497693862", # Required. The payment's id or internal_id. amount=Decimal("500"), # Required. 0.01 to 10,000,000. Less than the payment for a partial refund. supervisor_id="SUP-001", # Required. The supervisor ID given to you during onboarding. reason="Item damaged", # Optional. Up to 500 characters.)print(f"Refund {refund.id}: {refund.status.value}")
Before trying a refund again after OutcomeUnknownError, list the refunds and read the payment's refunded_amount, so the customer is not refunded twice.
Read and list refunds
Python
one = izipay.refunds.get( payment_id="497693862", # Required. The payment's id. refund_id="9b2f2c43-4b8f-4a7e-9a52-0d8b8a3c1e11", # Required. The refund's id.)refunds = izipay.refunds.list( page_number=1, # Optional. Default 1. page_size=50, # Optional. 1 to 100. Default 20. status=RefundStatus.COMPLETED, # Optional. PENDING, PROCESSING, COMPLETED or FAILED. payment_type=PaymentType.GPO, # Optional. GPO or PPR. start_date=datetime.now(LUANDA) - timedelta(days=30), # Optional. Requested on or after. end_date=datetime.now(LUANDA), # Optional. Requested on or before.)
Terminals
For merchants with a Multicaixa point-of-sale terminal.
Python
# Read the terminal's stateterminal = izipay.terminals.get_status( "POS-ID", # Required. Your terminal (POS) ID.)if terminal.status is TerminalState.OPEN: # TerminalState.OPEN or TerminalState.CLOSED print(f"{terminal.name} is open")# Open or close it. Both return the ID of the operation.operation_id = izipay.terminals.open( "POS-ID", # Required. supervisor_id="SUP-001", # Optional. Only if your terminal needs a supervisor. supervisor_iban="AO06000000000000000000000", # Optional. Only if your terminal needs one.)operation_id = izipay.terminals.close("POS-ID") # supervisor_id and supervisor_iban are optional here too
Your IZI Pay bill
Read-only access to your IZI Pay plan, usage and invoices.
Python
# Packages you are subscribed tosubscriptions = izipay.billing.get_active_subscriptions()# Usage per service in the current billing period: how many payments and their total value.# Not your fee: your package's pricing (for example a commission) is applied on the invoice.for usage in izipay.billing.get_current_usage(): print(f"{usage.service_name}: {usage.total_quantity} {usage.unit_name}, {usage.total_amount} AOA in payments")# Individual usage recordsrecords = izipay.billing.get_usage_history( billing_period="2026-11", # Optional. Only this month. Leave it out for all. page_number=1, # Optional. Default 1. page_size=50, # Optional. 1 to 100. Default 50.)# Invoices, newest firstinvoices = izipay.billing.list_invoices( page_number=1, # Optional. Default 1. page_size=20, # Optional. 1 to 100. Default 20.)# One invoice with its linesinvoice = izipay.billing.get_invoice( invoices[0].invoice_id, # Required.)