C# / .NET
SDK uffiċjali ta' C#/.NET għall-gateway tal-ħlas Cost+
SDK uffiċjali ta' C#/.NET għall-gateway tal-ħlas Cost+. Jissimplifika l-flusso ta' redirect tal-HPP (Paġna ta' Ħlas Ospitata), il-firma tal-payload HMAC, u l-verifika tal-webhooks.
Karatteristiċi
- Żero dipendenzi — juża biss
System.Text.JsonuSystem.Security.Cryptographyintegrati - Jimmira .NET 8.0 b'karatteristiċi ta' C# 12 (records, file-scoped namespaces, pattern matching)
- Nullable reference types attivati kullimkien
- Ġenerazzjoni ta' firma HMAC-SHA256 u verifika b'ħin kostanti
- Mappa awtomatika ta' snake_case/PascalCase bejn l-API u l-SDK
- Ipparsjar tal-webhooks + verifika tal-ordni bbażata fuq l-API
- Superfiċje tal-API kompletament asinkrona
Rekwiżiti
- .NET 8.0 SDK jew aktar tard
- Kont ta' kummerċjant Cost+ — dashboard.costplus.io
Installazzjoni
dotnet add package NoPaynJew bħala referenza ta' proġett lokali:
dotnet add reference path/to/src/NoPayn/NoPayn.csprojBidu Malajr
1. Inizjalizza l-Klijent
using NoPayn;
using NoPayn.Models;
var nopayn = new NoPaynClient(new NoPaynConfig(
ApiKey: "your-api-key",
MerchantId: "your-project"
));2. Oħloq Ħlas u Irridirezzjona lejn il-HPP
var result = await nopayn.GeneratePaymentUrlAsync(new CreateOrderParams
{
Amount = 1295, // €12.95 f'ċenteżmi
Currency = "EUR",
MerchantOrderId = "ORDER-001",
Description = "Premium Widget",
ReturnUrl = "https://shop.example.com/success",
FailureUrl = "https://shop.example.com/failure",
WebhookUrl = "https://shop.example.com/webhook",
Locale = "en-GB",
ExpirationPeriod = "PT30M",
});
// Irridirezzjona l-klijent
// result.OrderUrl → HPP (il-klijent jagħżel il-metodu ta' ħlas)
// result.PaymentUrl → link dirett lejn il-metodu ta' ħlas tal-ewwel tranżazzjoni
// result.Signature → HMAC-SHA256 għall-verifika
// result.OrderId → UUID tal-ordni NoPayn3. Ittratta l-Webhook
app.MapPost("/webhook", async (HttpContext ctx) =>
{
using var reader = new StreamReader(ctx.Request.Body);
var rawBody = await reader.ReadToEndAsync();
var verified = await nopayn.VerifyWebhookAsync(rawBody);
Console.WriteLine(verified.Order.Status); // "completed", "cancelled", eċċ.
Console.WriteLine(verified.IsFinal); // true meta l-ordni ma tinbidilx aktar
if (verified.Order.Status == "completed")
{
// Issodisfa l-ordni
}
return Results.Ok();
});Referenza tal-API
new NoPaynClient(config, httpClient?)
| Parametru | Tip | Meħtieġ | Default |
|---|---|---|---|
ApiKey | string | Iva | — |
MerchantId | string | Iva | — |
BaseUrl | string | Le | https://api.nopayn.co.uk |
HttpClient opzjonali jista' jiġi mgħoddi bħala t-tieni parametru tal-konstrukttur għat-trattar personalizzat tal-HTTP jew ittestjar.
client.CreateOrderAsync(params): Task<Order>
Joħloq ordni permezz ta' POST /v1/orders/.
| Parametru | Tip | Meħtieġ | Deskrizzjoni |
|---|---|---|---|
Amount | int | Iva | Ammont fl-unità minuri ISO 4217 tal-munita (per eżempju, ċenteżmi għal EUR) |
Currency | string | Iva | Kodiċi ISO 4217 (EUR, GBP, USD, NOK, SEK) |
MerchantOrderId | string? | Le | Ir-referenza interna tal-ordni tiegħek |
Description | string? | Le | Deskrizzjoni tal-ordni |
ReturnUrl | string? | Le | Redirect wara ħlas li rnexxielu |
FailureUrl | string? | Le | Redirect fuq kanċellazzjoni/skadenza/żball |
WebhookUrl | string? | Le | Notifiki asinkroni ta' bidla fl-istatus |
Locale | string? | Le | Lingwa tal-HPP (en-GB, de-DE, nl-NL, eċċ.) |
PaymentMethods | IReadOnlyList<string>? | Le | Iffiltra l-metodi tal-HPP |
ExpirationPeriod | string? | Le | Tul ta' żmien ISO 8601 (PT30M) |
Metodi ta' ħlas disponibbli: credit-card, apple-pay, google-pay, vipps-mobilepay
client.GetOrderAsync(orderId): Task<Order>
Jiġbed id-dettalji tal-ordni permezz ta' GET /v1/orders/{id}/.
client.CreateRefundAsync(orderId, amount, description?): Task<Refund>
Joħroġ rifużjoni sħiħa jew parzjali permezz ta' POST /v1/orders/{id}/refunds/.
client.GeneratePaymentUrlAsync(params): Task<PaymentUrlResult>
Metodu ta' konvenjenza li joħloq ordni u jirritorna:
public record PaymentUrlResult(
string OrderId, // UUID tal-ordni NoPayn
string OrderUrl, // URL tal-HPP
string? PaymentUrl, // URL ta' ħlas dirett (l-ewwel tranżazzjoni)
string Signature, // HMAC-SHA256 ta' amount:currency:orderId
Order Order // Oġġett sħiħ tal-ordni
);client.GenerateSignature(amount, currency, orderId): string
Jiġġenera firma HMAC-SHA256 hex.
client.VerifySignature(amount, currency, orderId, signature): bool
Verifika b'ħin kostanti ta' firma HMAC-SHA256.
client.VerifyWebhookAsync(rawBody): Task<VerifiedWebhook>
Jipparsja l-korp tal-webhook, imbagħad isejjaħ GET /v1/orders/{id}/ biex jivverifika l-istatus attwali.
Utilitajiet HMAC Standalone
using NoPayn;
var sig = NoPaynSignature.Generate("your-api-key", 1295, "EUR", "order-uuid");
var ok = NoPaynSignature.Verify("your-api-key", 1295, "EUR", "order-uuid", sig);Trattar tal-Żbalji
using NoPayn.Exceptions;
try
{
await nopayn.CreateOrderAsync(new CreateOrderParams { Amount = 100, Currency = "EUR" });
}
catch (ApiException ex)
{
Console.Error.WriteLine(ex.StatusCode); // 401, 400, eċċ.
Console.Error.WriteLine(ex.ErrorBody); // Risposta ta' żball mhux ipproċessata tal-API
}
catch (NoPaynException ex)
{
Console.Error.WriteLine(ex.Message); // Żball tan-network jew tal-ipparsjar
}| Eċċezzjoni | Deskrizzjoni |
|---|---|
NoPaynException | Eċċezzjoni bażi (network, ipparsjar) |
ApiException | Żball HTTP mill-API |
WebhookException | Payload tal-webhook invalidu |
Statuses tal-Ordni
| Status | Finali? | Deskrizzjoni |
|---|---|---|
new | Le | Ordni maħluqa |
processing | Le | Ħlas qed isir |
completed | Iva | Ħlas irnexxielu — ikkonsenja l-prodotti |
cancelled | Iva | Ħlas ikkanċellat mill-klijent |
expired | Iva | Link tal-ħlas skada |
error | Iva | Falliment tekniku |
L-Aħjar Prattiċi għall-Webhooks
- Dejjem ivverifika permezz tal-API — il-payload tal-webhook fih biss l-ID tal-ordni, qatt l-istatus. Il-
VerifyWebhookAsync()tal-SDK jagħmel dan awtomatikament. - Irritorna HTTP 200 biex tikkonferma r-riċevuta. Kwalunkwe kodiċi ieħor jiskatta sa 10 retries (2 minuti bejn xulxin).
- Implimenta backup poller — għal ordnijiet itqal minn 10 minuti li għadhom ma laħqux status finali, agħmel polling ta'
GetOrderAsync()bħala xibka ta' sigurtà. - Kun idempotenti — tista' tirċievi l-istess webhook aktar minn darba.
Karti tat-Test
Uża dawn il-karti f'modalità tat-test ta' Cost+ (website sandbox):
| Karta | Numru | Noti |
|---|---|---|
| Visa (suċċess) | 4111 1111 1111 1111 | Kwalunkwe CVV |
| Mastercard (suċċess) | 5544 3300 0003 7 | Kwalunkwe CVV |
| Visa (miċħuda) | 4111 1111 1111 1105 | Do Not Honor |
| Visa (fondi insuffiċjenti) | 4111 1111 1111 1151 | Insufficient Funds |
Uża kwalunkwe data ta' skadenza futura u kwalunkwe CVC ta' 3 ċifri.
App Demo
App demo bbażata fuq Docker b'ASP.NET Core hija inkluża fir-repożitorju ta' GitHub għall-ittestjar tal-flusso sħiħ tal-ħlas.
Appoġġ
Għandek bżonn l-għajnuna? Ikkuntattja t-tim tal-appoġġ tagħna fuq support@costplus.io.