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.
Method
The customer
Learn more
CreateReferenceAsync
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 Status = PaymentStatus.Failed and an ErrorCode and ErrorMessage; it is not thrown as an exception.
The using lines for all examples on this page:
C#
using IziPay;using IziPay.Payments;
Payment by reference
C#
var payment = await izipay.Payments.CreateReferenceAsync(new ReferencePaymentRequest{ // Required. Amount in kwanzas (AOA), not cents. Must be more than 0 for a Dynamic reference. // For a Charging reference, 0 lets the customer choose the amount. Amount = 15000m, // Optional. Dynamic (default): one payment of a fixed amount, such as an order. // Charging: a long-lived reference that can receive several payments, such as a customer account. ReferenceType = ReferenceType.Dynamic, // Optional. Your own reference number. Leave it out and IZI Pay generates one. Reference = null, // Optional. When the reference stops accepting payments. // Default: one month after creation for Dynamic, end of 2099 for Charging. ExpiryDate = DateTimeOffset.Now.AddDays(3), // Optional. What is being paid. Description = "Order 1042", // Optional. Customer details, kept with the payment. CustomerName = "Ana Silva", CustomerEmail = "ana@example.com", CustomerTelephone = "923000000", // Optional. Your invoice or document number. DocumentNumber = "FT 2026/1042", // Optional. Your own data, returned when you read the payment. Custom = new Dictionary<string, string> { ["orderId"] = "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.IdempotencyKey). IdempotencyKey = "order-1042"});Console.WriteLine($"Entity {payment.Entity}, reference {payment.Reference}, expires {payment.ExpiresAt}");
Show the entity and reference to the customer. The webhook tells you when they have paid.
One-time purchase on the customer's phone
C#
var purchase = await izipay.Payments.CreateMobileAsync(new MobilePaymentRequest{ // Required. Amount in kwanzas, more than 0. Amount = 2500m, // 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. PhoneNumber = "923000000", // Optional. The mobile provider agreed during onboarding, for example "UNITEL". Left out: an empty value is sent. Provider = "UNITEL", // Optional. What is being paid. Description = "Order 1043", // Optional. Your own data, returned when you read the payment. Custom = new Dictionary<string, string> { ["orderId"] = "1043" }, // Optional, recommended. See Idempotency keys on the overview page. IdempotencyKey = "order-1043"});switch (purchase.Status){ case PaymentStatus.Completed: // Paid. Confirm the order. break; case PaymentStatus.Failed: // Declined or not completed. Console.WriteLine($"{purchase.ErrorCode}: {purchase.ErrorMessage}"); break; default: // Pending or Processing. Wait for the webhook, or read the payment again later. break;}
The answer can take up to about 90 seconds while the customer approves on their phone.
QR Code
C#
var qr = await izipay.Payments.CreateQrCodeAsync(new QrCodePaymentRequest{ // Required. Amount in kwanzas, more than 0. Amount = 1200m, // Required. Your reference for this payment. Up to 100 characters. Reference = "TABLE-7", // Optional. Image size. Default: "MEDIUM". QrSize = "MEDIUM", // Optional. QR Code behaviour. Default: "STATIC". QrType = "STATIC", // Optional. How many payments the code accepts. Default: 1. MaxTransactions = 1, // Optional. When the code stops working. Default: 24 hours after creation. EndDate = DateTimeOffset.Now.AddHours(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. IncludeDeepLink = true, // Optional. What is being paid. Description = "Table 7", // Optional. Your own data, returned when you read the payment. Custom = new Dictionary<string, string> { ["table"] = "7" }, // Optional, recommended. IdempotencyKey = "bill-7781"});await File.WriteAllBytesAsync("qr.png", qr.QrCodePng!); // show it on screen or print itConsole.WriteLine($"Payment ID {qr.Id}"); // keep it to check the status laterConsole.WriteLine($"On a phone, open {qr.DeepLink}"); // opens the Multicaixa Express app directly
Webframe checkout page
C#
var checkout = await izipay.Payments.CreateWebframeAsync(new WebframePaymentRequest{ // Required. Amount in kwanzas, more than 0. Amount = 8900m, // 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. CssUrl = new Uri("https://shop.example.ao/izipay-checkout.css"), // Optional. Page settings agreed for your merchant. Leave them out for the defaults: // QrCode "DISABLED", Mobile "AUTHORIZATION", Card "AUTHORIZATION". QrCode = "DISABLED", Mobile = "AUTHORIZATION", Card = "AUTHORIZATION", // Optional. What is being paid. Description = "Order 1044", // Optional. Your own data, returned when you read the payment. Custom = new Dictionary<string, string> { ["orderId"] = "1044" }, // Optional, recommended. IdempotencyKey = "order-1044"});return Redirect(checkout.PaymentUrl!); // send the customer to the payment page
checkout.ExpiresAt 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.
C#
// 1. Reservevar hold = await izipay.Payments.CreateAuthorizationAsync(new AuthorizationRequest{ Amount = 50000m, // Required. Amount to reserve, in kwanzas. Reference = "BOOKING-88", // Required. Your reference. Up to 100 characters. PhoneNumber = "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 = new Dictionary<string, string> { ["bookingId"] = "88" }, // Optional. IdempotencyKey = "booking-88-hold" // Optional, recommended.});if (hold.Status == PaymentStatus.Authorized){ // Keep both IDs: AuthorizationId to capture, InternalId to cancel. Console.WriteLine($"{hold.AuthorizationId} / {hold.InternalId}");}// 2a. Collect all or part of itvar capture = await izipay.Payments.CaptureAsync(new CaptureRequest{ Amount = 42000m, // Required. Amount to collect, up to what was reserved. Reference = "BOOKING-88-CHECKOUT", // Required. Your reference for this capture. AuthorizationId = hold.AuthorizationId!, // Required. From the authorization. Not its InternalId. Description = "Check-out", // Optional. Custom = new Dictionary<string, string> { ["bookingId"] = "88" }, // Optional. IdempotencyKey = "booking-88-capture-1" // Optional, recommended. A new key for each capture.});// 2b. Or release the reservation without collectingvar cancellation = await izipay.Payments.CancelAuthorizationAsync( hold.InternalId!.Value); // Required. The authorization's InternalId. Not its AuthorizationId.
Capture uses AuthorizationId; cancel uses InternalId. The SDK never repeats a cancellation after it was sent. If it throws IziPayOutcomeUnknownException, read the payment before trying again.
What a created payment contains
Which fields are filled depends on the method.
Field
Filled for
Meaning
Id
All (except an image-only QR Code)
Use it with GetAsync and RequestStatusSyncAsync. For a payment by reference, it is the reference number
ReferenceRecordId
Payment by reference
The ID IZI Pay gave the reference record. You can't read the payment with it; use Id
InternalId
Most methods
IZI Pay's own ID. Needed to cancel an authorization
True when IZI Pay returned an existing payment for a repeated key
CustomMetadata, AdditionalData
When IZI Pay returns them
Your custom data, and any other data
Read a payment
C#
var payment = await izipay.Payments.GetAsync( "497693862"); // Required. The payment's Id.Console.WriteLine($"{payment.Status}: {payment.Amount} {payment.Currency}, paid {payment.CompletedAt}, refunded {payment.RefundedAmount}");
List payments
Every filter is optional. Without any, you get the 20 most recent payments.
C#
var page = await izipay.Payments.ListAsync(new ListPaymentsOptions{ PageNumber = 1, // Optional. Default 1. PageSize = 50, // Optional. 1 to 100. Default 20. Status = PaymentStatus.Completed, // Optional. Only this status. PaymentType = PaymentType.Ppr, // Optional. Ppr (references) or Gpo (Multicaixa Express). StartDate = DateTimeOffset.Now.Date, // Optional. Created on or after. EndDate = DateTimeOffset.Now, // Optional. Created on or before. Search = "ORDER-1042" // Optional. Free text, such as your reference.});foreach (var p in page.Items) Console.WriteLine($"{p.Reference}: {p.Status} {p.Amount}");// page.HasMore is true when there is another page: ask for PageNumber + 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.
C#
await izipay.Payments.RequestStatusSyncAsync( "497693862"); // Required. The payment's Id.