C# / .NET
Oficialus C#/.NET SDK Cost+ mokėjimų šliuzui
Oficialus C#/.NET SDK Cost+ mokėjimų šliuzui. Supaprastina HPP (mokėjimo puslapio) nukreipimo procesą, HMAC turinio pasirašymą ir webhook patvirtinimą.
Savybės
- Jokių priklausomybių — naudoja tik integruotus
System.Text.JsonirSystem.Security.Cryptography - Skirta .NET 8.0 su C# 12 funkcijomis (records, file-scoped namespaces, pattern matching)
- Nullable nuorodų tipai įjungti visur
- HMAC-SHA256 parašo generavimas ir pastovaus laiko patikrinimas
- Automatinis snake_case/PascalCase atitikimas tarp API ir SDK
- Webhook analizė + API pagrįstas užsakymo patikrinimas
- Visiškai asinchroninė API sąsaja
Reikalavimai
- .NET 8.0 SDK arba naujesnė
- Cost+ prekybininko paskyra — dashboard.costplus.io
Diegimas
dotnet add package NoPaynArba kaip vietinė projekto nuoroda:
dotnet add reference path/to/src/NoPayn/NoPayn.csprojGreitas startas
1. Inicializuokite klientą
using NoPayn;
using NoPayn.Models;
var nopayn = new NoPaynClient(new NoPaynConfig(
ApiKey: "your-api-key",
MerchantId: "your-project"
));2. Sukurkite mokėjimą ir nukreipkite į HPP
var result = await nopayn.GeneratePaymentUrlAsync(new CreateOrderParams
{
Amount = 1295, // €12.95 in cents
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",
});
// Redirect the customer
// result.OrderUrl → HPP (customer picks payment method)
// result.PaymentUrl → direct link to the first transaction's payment method
// result.Signature → HMAC-SHA256 for verification
// result.OrderId → NoPayn order UUID3. Apdorokite 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", etc.
Console.WriteLine(verified.IsFinal); // true when the order won't change
if (verified.Order.Status == "completed")
{
// Fulfil the order
}
return Results.Ok();
});API nuoroda
new NoPaynClient(config, httpClient?)
| Parametras | Tipas | Privalomas | Numatytasis |
|---|---|---|---|
ApiKey | string | Taip | — |
MerchantId | string | Taip | — |
BaseUrl | string | Ne | https://api.nopayn.co.uk |
Neprivalomas HttpClient gali būti perduotas kaip antras konstruktoriaus parametras pasirinktiniam HTTP tvarkymui ar testavimui.
client.CreateOrderAsync(params): Task<Order>
Sukuria užsakymą per POST /v1/orders/.
| Parametras | Tipas | Privalomas | Aprašymas |
|---|---|---|---|
Amount | int | Taip | Suma mažiausiu valiutos vienetu (centais) |
Currency | string | Taip | ISO 4217 kodas (EUR, GBP, USD, NOK, SEK) |
MerchantOrderId | string? | Ne | Jūsų vidinis užsakymo nuorodos ID |
Description | string? | Ne | Užsakymo aprašymas |
ReturnUrl | string? | Ne | Nukreipimas po sėkmingo mokėjimo |
FailureUrl | string? | Ne | Nukreipimas atšaukimo/galiojimo pabaigos/klaidos atveju |
WebhookUrl | string? | Ne | Asinchroniniai būsenos pakeitimo pranešimai |
Locale | string? | Ne | HPP kalba (en-GB, de-DE, nl-NL ir kt.) |
PaymentMethods | IReadOnlyList<string>? | Ne | Filtruoti HPP mokėjimo būdus |
ExpirationPeriod | string? | Ne | ISO 8601 trukmė (PT30M) |
Prieinami mokėjimo būdai: credit-card, apple-pay, google-pay, vipps-mobilepay
client.GetOrderAsync(orderId): Task<Order>
Gauna užsakymo detales per GET /v1/orders/{id}/.
client.CreateRefundAsync(orderId, amount, description?): Task<Refund>
Atlieka pilną arba dalinį grąžinimą per POST /v1/orders/{id}/refunds/.
client.GeneratePaymentUrlAsync(params): Task<PaymentUrlResult>
Patogus metodas, kuris sukuria užsakymą ir grąžina:
public record PaymentUrlResult(
string OrderId, // NoPayn order UUID
string OrderUrl, // HPP URL
string? PaymentUrl, // Direct payment URL (first transaction)
string Signature, // HMAC-SHA256 of amount:currency:orderId
Order Order // Full order object
);client.GenerateSignature(amount, currency, orderId): string
Generuoja HMAC-SHA256 hex parašą.
client.VerifySignature(amount, currency, orderId, signature): bool
Pastovaus laiko HMAC-SHA256 parašo patikrinimas.
client.VerifyWebhookAsync(rawBody): Task<VerifiedWebhook>
Analizuoja webhook turinį, tada iškviečia GET /v1/orders/{id}/, kad patikrintų tikrąją būseną.
Atskiros HMAC priemonės
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);Klaidų tvarkymas
using NoPayn.Exceptions;
try
{
await nopayn.CreateOrderAsync(new CreateOrderParams { Amount = 100, Currency = "EUR" });
}
catch (ApiException ex)
{
Console.Error.WriteLine(ex.StatusCode); // 401, 400, etc.
Console.Error.WriteLine(ex.ErrorBody); // Raw API error response
}
catch (NoPaynException ex)
{
Console.Error.WriteLine(ex.Message); // Network or parsing error
}| Išimtis | Aprašymas |
|---|---|
NoPaynException | Bazinė išimtis (tinklas, analizė) |
ApiException | HTTP klaida iš API |
WebhookException | Netinkamas webhook turinys |
Užsakymo būsenos
| Būsena | Galutinė? | Aprašymas |
|---|---|---|
new | Ne | Užsakymas sukurtas |
processing | Ne | Mokėjimas vykdomas |
completed | Taip | Mokėjimas sėkmingas — pristatykite prekes |
cancelled | Taip | Mokėjimas atšauktas kliento |
expired | Taip | Mokėjimo nuorodos laikas baigėsi |
error | Taip | Techninė klaida |
Webhook geriausios praktikos
- Visada patikrinkite per API — webhook turinys pateikia tik užsakymo ID, niekada būsenos. SDK
VerifyWebhookAsync()tai atlieka automatiškai. - Grąžinkite HTTP 200, kad patvirtintumėte gavimą. Bet koks kitas kodas suaktyvina iki 10 pakartotinių bandymų (kas 2 minutes).
- Įgyvendinkite atsarginį tikrintuvą — užsakymams, senesniems nei 10 minučių, kurie nepasiekė galutinės būsenos, naudokite
GetOrderAsync()kaip saugos tinklą. - Būkite idempotentiški — galite gauti tą patį webhook kelis kartus.
Testinės kortelės
Naudokite šias korteles Cost+ testavimo režimu (testavimo svetainė):
| Kortelė | Numeris | Pastabos |
|---|---|---|
| Visa (sėkminga) | 4111 1111 1111 1111 | Bet koks CVV |
| Mastercard (sėkminga) | 5544 3300 0003 7 | Bet koks CVV |
| Visa (atmesta) | 4111 1111 1111 1105 | Do Not Honor |
| Visa (nepakankamos lėšos) | 4111 1111 1111 1151 | Insufficient Funds |
Naudokite bet kurią ateities galiojimo datą ir bet kokį 3 skaitmenų CVC.
Demonstracinė programa
Docker pagrįsta ASP.NET Core demonstracinė programa įtraukta į GitHub saugyklą pilnam mokėjimo proceso testavimui.
Palaikymas
Reikia pagalbos? Kreipkitės į mūsų palaikymo komandą adresu support@costplus.io.