Cost+Docs

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.Json u System.Security.Cryptography integrati
  • 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

Installazzjoni

dotnet add package NoPayn

Jew bħala referenza ta' proġett lokali:

dotnet add reference path/to/src/NoPayn/NoPayn.csproj

Bidu 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 NoPayn

3. 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?)

ParametruTipMeħtieġDefault
ApiKeystringIva—
MerchantIdstringIva—
BaseUrlstringLehttps://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/.

ParametruTipMeħtieġDeskrizzjoni
AmountintIvaAmmont fl-unità minuri ISO 4217 tal-munita (per eżempju, ċenteżmi għal EUR)
CurrencystringIvaKodiċi ISO 4217 (EUR, GBP, USD, NOK, SEK)
MerchantOrderIdstring?LeIr-referenza interna tal-ordni tiegħek
Descriptionstring?LeDeskrizzjoni tal-ordni
ReturnUrlstring?LeRedirect wara ħlas li rnexxielu
FailureUrlstring?LeRedirect fuq kanċellazzjoni/skadenza/żball
WebhookUrlstring?LeNotifiki asinkroni ta' bidla fl-istatus
Localestring?LeLingwa tal-HPP (en-GB, de-DE, nl-NL, eċċ.)
PaymentMethodsIReadOnlyList<string>?LeIffiltra l-metodi tal-HPP
ExpirationPeriodstring?LeTul 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ċċezzjoniDeskrizzjoni
NoPaynExceptionEċċezzjoni bażi (network, ipparsjar)
ApiExceptionŻball HTTP mill-API
WebhookExceptionPayload tal-webhook invalidu

Statuses tal-Ordni

StatusFinali?Deskrizzjoni
newLeOrdni maħluqa
processingLeĦlas qed isir
completedIvaĦlas irnexxielu — ikkonsenja l-prodotti
cancelledIvaĦlas ikkanċellat mill-klijent
expiredIvaLink tal-ħlas skada
errorIvaFalliment tekniku

L-Aħjar Prattiċi għall-Webhooks

  1. 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.
  2. Irritorna HTTP 200 biex tikkonferma r-riċevuta. Kwalunkwe kodiċi ieħor jiskatta sa 10 retries (2 minuti bejn xulxin).
  3. 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à.
  4. 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):

KartaNumruNoti
Visa (suċċess)4111 1111 1111 1111Kwalunkwe CVV
Mastercard (suċċess)5544 3300 0003 7Kwalunkwe CVV
Visa (miċħuda)4111 1111 1111 1105Do Not Honor
Visa (fondi insuffiċjenti)4111 1111 1111 1151Insufficient 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.

On this page