This page covers everything in the .NET SDK besides creating payments. As on the other pages, each example shows every parameter, marked Required or Optional.
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 throws IziPayOutcomeUnknownException, look it up before trying again.
Payment references
izipay.References works with payment references directly. To create a reference as a payment, with an idempotency key, you can also use Payments.CreateReferenceAsync.
C#
using IziPay;using IziPay.References;
Create a reference
C#
var reference = await izipay.References.CreateAsync(new CreateReferenceRequest{ // Optional. Dynamic (default): one payment of a fixed amount. // Charging: a long-lived reference that can receive several payments. ReferenceType = ReferenceType.Dynamic, // Required for Dynamic (more than 0). For Charging, 0 lets the customer choose the amount. Amount = 15000m, // Optional. Your own reference number. Leave it out and IZI Pay generates one. Reference = null, // Optional. When the reference stops accepting payments. ExpiryDate = DateTimeOffset.Now.AddDays(3), // Optional. What is being paid. Description = "Invoice FT 2026/1042", // Optional. Customer details. 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 reference. CustomMetadata = new Dictionary<string, string> { ["invoiceId"] = "1042" }});Console.WriteLine($"Entity {reference.Entity}, reference {reference.Reference}, {reference.ReferenceStatus}");
Create up to 100 references at once
Each item has the same fields as above. Some can succeed while others fail, so check both lists.
C#
var result = await izipay.References.CreateBulkAsync(new[]{ new CreateReferenceRequest { Amount = 5000m, Description = "Student 551 - November" }, new CreateReferenceRequest { Amount = 5000m, Description = "Student 552 - November" }});Console.WriteLine($"{result.SuccessCount} created, {result.ErrorCount} failed");foreach (var created in result.References) Console.WriteLine(created.Reference);foreach (var error in result.Errors) Console.WriteLine(error);
Read, follow and cancel
C#
// Read a reference and the status of its paymentvar current = await izipay.References.GetAsync( "584923109"); // Required. The reference number.// Every payment made to it (a Charging reference can receive several)var history = await izipay.References.GetHistoryAsync( "584923109"); // Required.// Stop it accepting payments. Only works while it has not been paid.await izipay.References.CancelAsync( "584923109"); // Required.
ReferenceStatus tells you about the reference itself (Active, Paid, Cancelled, Expired); Status tells you about its payment.
List references
C#
var page = await izipay.References.ListAsync(new ListReferencesOptions{ PageNumber = 1, // Optional. Default 1. PageSize = 50, // Optional. 1 to 100. Default 20. Type = ReferenceType.Dynamic, // Optional. Only this type. Status = PaymentStatus.Completed // Optional. Only references whose payment has this status.});
Refunds
C#
using IziPay.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.
C#
var refund = await izipay.Refunds.CreateAsync( "497693862", // Required. The payment's Id or InternalId. new CreateRefundRequest { Amount = 500m, // Required. 0.01 to 10,000,000. Less than the payment for a partial refund. SupervisorId = "SUP-001", // Required. The supervisor ID given to you during onboarding. Reason = "Item damaged" // Optional. Up to 500 characters. });Console.WriteLine($"Refund {refund.Id}: {refund.Status}");
Before trying a refund again after IziPayOutcomeUnknownException, list the refunds and read the payment's RefundedAmount, so the customer is not refunded twice.
Read and list refunds
C#
var one = await izipay.Refunds.GetAsync( "497693862", // Required. The payment's Id. Guid.Parse("9b2f2c43-4b8f-4a7e-9a52-0d8b8a3c1e11")); // Required. The refund's Id.var refunds = await izipay.Refunds.ListAsync(new ListRefundsOptions{ PageNumber = 1, // Optional. Default 1. PageSize = 50, // Optional. 1 to 100. Default 20. Status = RefundStatus.Completed, // Optional. Pending, Processing, Completed or Failed. PaymentType = PaymentType.Gpo, // Optional. Gpo or Ppr. StartDate = DateTimeOffset.Now.AddDays(-30), // Optional. Requested on or after. EndDate = DateTimeOffset.Now // Optional. Requested on or before.});
Terminals
For merchants with a Multicaixa point-of-sale terminal.
C#
using IziPay.Terminals;// Read the terminal's statevar terminal = await izipay.Terminals.GetStatusAsync( "POS-ID"); // Required. Your terminal (POS) ID.Console.WriteLine($"{terminal.Name}: {terminal.Status}"); // Open or Closed// Open or close itvar options = new TerminalOperationOptions{ SupervisorId = "SUP-001", // Optional. Only if your terminal needs a supervisor. SupervisorIban = "AO06000000000000000000000" // Optional. Only if your terminal needs one.};var opened = await izipay.Terminals.OpenAsync("POS-ID", options); // options is optionalvar closed = await izipay.Terminals.CloseAsync("POS-ID", options);
Your IZI Pay bill
Read-only access to your IZI Pay plan, usage and invoices.
C#
using IziPay.Billing;// Packages you are subscribed tovar subscriptions = await izipay.Billing.GetActiveSubscriptionsAsync();// 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.var usage = await izipay.Billing.GetCurrentUsageAsync();foreach (var u in usage) Console.WriteLine($"{u.ServiceName}: {u.TotalQuantity} {u.UnitName}, {u.TotalAmount} AOA in payments");// Individual usage recordsvar records = await izipay.Billing.GetUsageHistoryAsync( billingPeriod: "2026-11", // Optional. Only this month. Leave it out for all. pageNumber: 1, // Optional. Default 1. pageSize: 50); // Optional. 1 to 100. Default 50.// Invoices, newest firstvar invoices = await izipay.Billing.ListInvoicesAsync( pageNumber: 1, // Optional. Default 1. pageSize: 20); // Optional. 1 to 100. Default 20.// One invoice with its linesvar invoice = await izipay.Billing.GetInvoiceAsync( invoices[0].InvoiceId); // Required.