.NET SDK
The IZI Pay .NET SDK is a library you add to your own .NET application. It talks to the Payment API for you:
- it gets the access token and renews it before it expires;
- it gives you one method per payment type, with typed requests and answers;
- it retries temporary failures only when repeating the request cannot charge or refund twice;
- it turns every error into one exception type, whatever format the API used;
- it checks and reads the webhooks IZI Pay sends you.
Preview
This page describes version 0.1.0-preview.3, available on NuGet. Method names can still change before version 1.0, so install it with --prerelease and use the exact version you tested with.
Requirements
- .NET 10 or later.
- A Client ID and Client Secret for each environment you use. See Credentials and Support.
Install
bash
Updating from an older version? See SDK updates for the command and what changed.
Create the client
Create one client per set of credentials and reuse it for the life of your application. It keeps the access token and the connections, and it is safe to use from many threads at once.
Every setting is shown below. Only the first three are required.
C#
You can also pass an ILogger<IziPayClient> as a second argument. The SDK logs how long each request took and when it retries. It never logs request or response bodies, tokens or secrets.
ASP.NET Core
Register the client once in Program.cs. Any controller or service can then ask for IziPayClient, and the logger is added automatically.
C#
Environments
Environment | Address | Credentials |
|---|---|---|
IziPayEnvironment.Sandbox | https://pay-sandbox.izipay.ao | Sandbox Client App |
IziPayEnvironment.Production | https://pay.izipay.ao | Production Client App |
Sandbox and production credentials are different. If you use one in the other, the SDK throws an Authentication error that names the environment it tried.
What the client offers
| Property | Use it to | Page |
|---|---|---|
izipay.Payments | Create payments with every method, read them, list them | Payments |
izipay.References | Create, read, list and cancel payment references | References, refunds and more |
izipay.Refunds | Return money for a completed payment | References, refunds and more |
izipay.Terminals | Read, open and close a point-of-sale terminal | References, refunds and more |
izipay.Billing | See your IZI Pay plan, usage and invoices | References, refunds and more |
IziPayWebhooks | Check and read the notifications IZI Pay sends you | Webhooks |
Every method also takes an optional CancellationToken as its last argument.
Safe retries
The SDK retries temporary failures (lost connection, time-out, HTTP 502, 503 or 504 from a proxy, rate limits) only where repeating the request is harmless:
| Operation | Repeated after it was sent? | Why |
|---|---|---|
| Reading and listing, token requests, status sync | Yes | They change nothing |
| Creating a payment (every method) | Yes, with the same idempotency key | IZI Pay returns the existing payment for a repeated key |
| Refunds, references, cancelling an authorization, opening or closing a terminal | No | They have no idempotency key, so a repeat could do it twice |
Any request is retried when it certainly never reached IZI Pay (connection refused, name not found) or was turned away by the rate limit (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.
Idempotency keys
Every payment you create carries an idempotency key. If IZI Pay already has a payment with that key for your merchant, it returns that payment instead of creating another.
- Optional. If you leave it out, the SDK makes one and returns it in
payment.IdempotencyKey. That protects the SDK's own retries. - Recommended in production: use your own key, such as your order ID. Then a second attempt for the same order (after a crash, or a customer clicking Pay twice) returns the first payment instead of charging again.
- Use a new key for each new payment, including each capture.
Errors
Every failure is an IziPayException. Check Kind to decide what to do:
Kind | Meaning | What to do |
|---|---|---|
Validation | Something in the request is wrong (HTTP 400) | Fix the request. Details lists the fields |
Authentication | Credentials or token rejected | Check the credentials and that they belong to this environment |
Permission | These credentials may not do this (HTTP 403) | Contact IZI Pay support |
NotFound | It does not exist for your merchant | Check the ID |
Conflict | Clashes with the current state, for example a reused key (HTTP 409) | Read the current state first |
NotAvailable | The feature is switched off for your merchant, for example CHECKOUT_DISABLED | Contact IZI Pay support. Nothing was processed |
RateLimited | Too many requests, even after waiting | Try again in a minute. Nothing was processed |
Connection | IZI Pay could not be reached | Try again. Nothing was sent |
Server | IZI Pay had an error while reading data | Try again later |
OutcomeUnknown | Sent, but no clear answer came back | See below |
InvalidResponse | An answer the SDK could not read | Contact IZI Pay support with TraceId |
Other useful properties: StatusCode, ErrorCode (IZI Pay's own code, such as INVALID_OPERATION), Details, TraceId (quote it to support) and IsSafeToRetry (true when sending the same request again cannot do anything twice).
When the outcome is unknown
IziPayOutcomeUnknownException means the request was sent but no clear answer came back. It may or may not have been processed.
C#
Mistakes the SDK can see before sending, such as a missing phone number or a negative amount, throw an ArgumentException and nothing is sent.
Dates and statuses
- IZI Pay writes most dates in Luanda time without saying so. The SDK reads them as UTC+01:00 and gives you a
DateTimeOffset, so the time is right whatever time zone your server uses. - If IZI Pay adds a status the SDK does not know yet, it reads as
Unknowninstead of failing. TreatUnknownas not paid. See Payment Statuses.