IziPay 0.1.0-preview.3

This is a prerelease version of IziPay.
dotnet add package IziPay --version 0.1.0-preview.3
                    
NuGet\Install-Package IziPay -Version 0.1.0-preview.3
                    
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="IziPay" Version="0.1.0-preview.3" />
                    
For projects that support PackageReference, copy this XML node into the project file to reference the package.
<PackageVersion Include="IziPay" Version="0.1.0-preview.3" />
                    
Directory.Packages.props
<PackageReference Include="IziPay" />
                    
Project file
For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package.
paket add IziPay --version 0.1.0-preview.3
                    
#r "nuget: IziPay, 0.1.0-preview.3"
                    
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
#:package IziPay@0.1.0-preview.3
                    
#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package.
#addin nuget:?package=IziPay&version=0.1.0-preview.3&prerelease
                    
Install as a Cake Addin
#tool nuget:?package=IziPay&version=0.1.0-preview.3&prerelease
                    
Install as a Cake Tool

IZI Pay .NET SDK

Official .NET client for the IZI Pay Payment API (Angola). It handles access tokens, safe retries, errors and webhooks for you, so your code only deals with payments.

Preview (0.x). The API can still change between 0.x versions. Version 1.0 will follow once the IZI Pay API itself is stable. Pin the exact version you test with.

  • .NET 10 or later
  • Sandbox and production
  • MULTICAIXA Express (Webframe, mobile purchase, authorization and capture, QR Code), payment references, refunds, terminals, billing (read only) and webhooks

Install

dotnet add package IziPay --prerelease

Start

using IziPay;
using IziPay.Payments;

using var izipay = new IziPayClient(new IziPayClientOptions
{
    Environment = IziPayEnvironment.Sandbox,   // required: Sandbox or Production
    ClientId = builder.Configuration["IziPay:ClientId"]!,
    ClientSecret = builder.Configuration["IziPay:ClientSecret"]!
});

var payment = await izipay.Payments.CreateReferenceAsync(new ReferencePaymentRequest
{
    Amount = 1500m,
    Description = "Order 1042",
    CustomerEmail = "customer@example.com"
});

Console.WriteLine($"Pay entity {payment.Entity}, reference {payment.Reference}");

Create one client per set of credentials and reuse it: it keeps the access token and connections and is safe to use from many threads. Never put the secret in source control.

ASP.NET Core

builder.Services.AddIziPay(options =>
{
    options.Environment = builder.Environment.IsProduction() ? IziPayEnvironment.Production : IziPayEnvironment.Sandbox;
    options.ClientId = builder.Configuration["IziPay:ClientId"]!;
    options.ClientSecret = builder.Configuration["IziPay:ClientSecret"]!;
});

Then inject IziPayClient where you need it.

Environments

Environment Address Credentials
Sandbox https://pay-sandbox.izipay.ao Sandbox Client App
Production https://pay.izipay.ao Production Client App

There is no default environment, so test code can never reach production by accident. Sandbox and production credentials are different; using one in the other fails with an Authentication error that names the environment. Ask for credentials at suporte@izipay.ao.

Payments

Method What the customer does
CreateWebframeAsync Pays on a provider-hosted page; open PaymentUrl
CreateMobileAsync Approves a one-time purchase on their phone
CreateAuthorizationAsync / CaptureAsync Approves a reservation; you collect it later with the AuthorizationId
CreateQrCodeAsync Scans QrCodePng or opens DeepLink
CreateReferenceAsync Pays Entity + Reference at an ATM or in their banking app
var purchase = await izipay.Payments.CreateMobileAsync(new MobilePaymentRequest
{
    Amount = 2500m,
    Reference = "ORDER-1042",
    PhoneNumber = "923000000"
});

if (purchase.Status == PaymentStatus.Completed) { /* paid */ }
else if (purchase.Status == PaymentStatus.Failed) { /* declined: purchase.ErrorCode, purchase.ErrorMessage */ }
else { /* pending: wait for the webhook or read it later with GetAsync */ }

A declined payment is returned with Status = Failed, not thrown. Always check Status.

Other operations: GetAsync, ListAsync, RequestStatusSyncAsync (re-check with the provider when a webhook was missed) and CancelAuthorizationAsync (release a reservation; takes the InternalId, not the AuthorizationId).

Safe retries and idempotency

The SDK retries temporary failures (connection problems, time-outs, HTTP 502/503/504, rate limits) only when repeating the request cannot do anything twice:

Operation Retried after it was sent? Why
Reads, token requests, status sync Yes They change nothing
Creating a payment (any method) Yes, with the same idempotency key IZI Pay returns the existing payment for a repeated key
Refunds, references, cancellations, opening/closing terminals No There is no idempotency key, so a repeat could do it twice

Every request is retried when it certainly never reached IZI Pay (connection refused, DNS, TLS) or was refused by the rate limiter (HTTP 429), because nothing was processed. When IZI Pay itself answers a change with an error code and HTTP 5xx, the SDK does not repeat it: the gateway uses those answers to say "check before trying again".

Each payment gets an idempotency key. Pass your own (IdempotencyKey = order.Id) or store the one the SDK made (payment.IdempotencyKey). If no clear answer comes back, you get an IziPayOutcomeUnknownException:

try
{
    var payment = await izipay.Payments.CreateMobileAsync(request with { IdempotencyKey = order.PaymentKey });
}
catch (IziPayOutcomeUnknownException ex) when (ex.IdempotencyKey != null)
{
    // The payment may exist. Sending the same request with the same key later is safe:
    // IZI Pay returns the existing payment instead of charging again.
}
catch (IziPayOutcomeUnknownException)
{
    // Refund, reference or terminal operation: look it up before trying again.
}

Defaults: up to 2 retries (MaxRetries, 0–5) and 120 seconds per attempt (Timeout). The gateway can take up to 90 seconds while the customer approves on their phone, so keep the time-out above that.

Errors

Every failure is an IziPayException with one shape, whatever format the API used:

Property Meaning
Kind Authentication, Permission, Validation, NotFound, Conflict, RateLimited, Server, Connection, OutcomeUnknown, NotAvailable (feature switched off for your merchant), InvalidResponse
StatusCode HTTP status, when IZI Pay answered
ErrorCode IZI Pay's code, such as INVALID_OPERATION or REFERENCE_NOT_FOUND
Details Field-level problems
TraceId Quote it when you contact support
IsSafeToRetry True when sending the same request again later cannot do anything twice

Invalid input (missing phone number, negative amount, ...) is rejected with an ArgumentException before anything is sent.

Webhooks

IZI Pay sends the Access-Key you chose during onboarding with every notification. It only stops resending when your endpoint answers HTTP 2xx with "Success": true.

builder.Services.AddIziPayWebhooks(_ => builder.Configuration["IziPay:WebhookAccessKey"]!);

app.MapPost("/webhooks/izipay/references", async (HttpRequest http, IziPayWebhooks webhooks) =>
{
    if (!webhooks.IsAuthentic(http.Headers[IziPayWebhooks.AccessKeyHeader]))
        return Results.Unauthorized();

    using var reader = new StreamReader(http.Body);
    var payment = webhooks.ParseReferencePayment(await reader.ReadToEndAsync());

    // Notifications can arrive more than once: use payment.Id to process each only once.
    var orderId = await orders.MarkPaidAsync(payment.Reference, payment.AmountPaid, payment.Id);
    return Results.Content(IziPayWebhooks.Acknowledge(orderId), "application/json");
});

Use ParseQrCodePayment on your QR Code webhook URL. The key is compared in constant time.

Other areas

await izipay.References.CreateAsync(new CreateReferenceRequest { Amount = 1000m });
await izipay.References.GetAsync("584923109");
await izipay.Refunds.CreateAsync(paymentId, new CreateRefundRequest { Amount = 500m, SupervisorId = "..." });
await izipay.Terminals.GetStatusAsync("POS-ID");
await izipay.Billing.GetCurrentUsageAsync();

Dates

The gateway writes most dates in Luanda time without an offset. The SDK reads them as UTC+01:00 and exposes DateTimeOffset, so values are correct whatever time zone your server uses.

Logging

Pass an ILogger<IziPayClient> (automatic with AddIziPay). The SDK logs timings and retries. It never logs request or response bodies, tokens or secrets.

Building from source

dotnet test
dotnet pack src/IziPay -c Release

Versions and support

Versions follow Semantic Versioning. Before 1.0, a new minor version (0.1 to 0.2) can need code changes; a new beta or preview of the same minor version only fixes problems. From 1.0, only a major version can remove or change something, after it was marked as deprecated in a minor version. The SDK supports the .NET versions that still get security fixes from their maintainers. Fixes go to the newest version. What changed in each version: SDK updates.

Problems with the SDK: email suporte@izipay.ao with the SDK version, the environment, and the error's message and trace ID. Never send secrets, tokens or your webhook Access-Key.

Releasing

  1. Set the new version in <Version> (src/IziPay/IziPay.csproj) and add it at the top of CHANGELOG.md. Move the lines in src/IziPay/PublicAPI.Unshipped.txt to PublicAPI.Shipped.txt (the build fails when a public API change is not recorded there) and describe API changes in the CHANGELOG.
  2. Push to main and wait for the pipeline to pass.
  3. Tag and push: git tag -a v<version> -m "..." && git push origin v<version>. GitLab CI tests again, builds the package and publishes it to NuGet with Trusted Publishing; the tag must match <Version>.
  4. Check the version on https://www.nuget.org/packages/IziPay/ (NuGet takes a few minutes to list it) and install it in a clean project.
  5. Add the version to the SDK updates page of the docs (izipay-v2-docs: pages/sdks/updates.mdx and pages/pt/sdks/updates.mdx: date, what changed, whether code changes are needed) and update the version named on the SDK's overview pages.
Product Compatible and additional computed target framework versions.
.NET net10.0 is compatible.  net10.0-android was computed.  net10.0-browser was computed.  net10.0-ios was computed.  net10.0-maccatalyst was computed.  net10.0-macos was computed.  net10.0-tvos was computed.  net10.0-windows was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages

This package is not used by any NuGet packages.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last Updated
0.1.0-preview.3 0 11/22/2026
0.1.0-preview.2 38 11/22/2026
0.1.0-preview.1 47 11/21/2026