IziPay 0.1.0-preview.3
dotnet add package IziPay --version 0.1.0-preview.3
NuGet\Install-Package IziPay -Version 0.1.0-preview.3
<PackageReference Include="IziPay" Version="0.1.0-preview.3" />
<PackageVersion Include="IziPay" Version="0.1.0-preview.3" />
<PackageReference Include="IziPay" />
paket add IziPay --version 0.1.0-preview.3
#r "nuget: IziPay, 0.1.0-preview.3"
#:package IziPay@0.1.0-preview.3
#addin nuget:?package=IziPay&version=0.1.0-preview.3&prerelease
#tool nuget:?package=IziPay&version=0.1.0-preview.3&prerelease
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
- Set the new version in
<Version>(src/IziPay/IziPay.csproj) and add it at the top ofCHANGELOG.md. Move the lines insrc/IziPay/PublicAPI.Unshipped.txttoPublicAPI.Shipped.txt(the build fails when a public API change is not recorded there) and describe API changes in the CHANGELOG. - Push to
mainand wait for the pipeline to pass. - 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>. - 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.
- Add the version to the SDK updates page of the docs (
izipay-v2-docs:pages/sdks/updates.mdxandpages/pt/sdks/updates.mdx: date, what changed, whether code changes are needed) and update the version named on the SDK's overview pages.
| Product | Versions 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. |
-
net10.0
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 |