C# / .NET
Oficialne C#/.NET SDK pre platobnu branu Cost+
Oficialne C#/.NET SDK pre platobnu branu Cost+. Zjednodusuje proces presmerovania HPP (Hosted Payment Page), HMAC podpisovanie payloadov a overovanie webhookov.
Funkcie
- Ziadne zavislosti -- pouziva len vstavane
System.Text.JsonaSystem.Security.Cryptography - Cieli na .NET 8.0 s C# 12 vlastnostami (records, file-scoped namespaces, pattern matching)
- Nullable referencne typy aktivovane v celom projekte
- HMAC-SHA256 generovanie podpisov a overovanie v konstantnom case
- Automaticke mapovanie snake_case/PascalCase medzi API a SDK
- Parsovanie webhookov + overovanie objednavok na zaklade API
- Plne asynchronne API rozhranie
Poziadavky
- .NET 8.0 SDK alebo novsi
- Ucet obchodnika Cost+ -- dashboard.costplus.io
Instalacia
dotnet add package NoPaynAlebo ako lokalna referencia projektu:
dotnet add reference path/to/src/NoPayn/NoPayn.csprojRychly start
1. Inicializacia klienta
using NoPayn;
using NoPayn.Models;
var nopayn = new NoPaynClient(new NoPaynConfig(
ApiKey: "your-api-key",
MerchantId: "your-project"
));2. Vytvorenie platby a presmerovanie na HPP
var result = await nopayn.GeneratePaymentUrlAsync(new CreateOrderParams
{
Amount = 1295, // €12,95 v centoch
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",
});
// Presmerujte zakaznika
// result.OrderUrl → HPP (zakaznik si vyberie platobnu metodu)
// result.PaymentUrl → priamy odkaz na platobnu metodu prvej transakcie
// result.Signature → HMAC-SHA256 na overenie
// result.OrderId → NoPayn UUID objednavky3. Spracovanie webhooku
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", atd.
Console.WriteLine(verified.IsFinal); // true, ked sa objednavka uz nezmeni
if (verified.Order.Status == "completed")
{
// Vybavte objednavku
}
return Results.Ok();
});API referencia
new NoPaynClient(config, httpClient?)
| Parameter | Typ | Povinne | Predvolene |
|---|---|---|---|
ApiKey | string | Ano | -- |
MerchantId | string | Ano | -- |
BaseUrl | string | Nie | https://api.nopayn.co.uk |
Volitelny HttpClient je mozne predat ako druhy parameter konstruktora pre vlastne HTTP spracovanie alebo testovanie.
client.CreateOrderAsync(params): Task<Order>
Vytvori objednavku cez POST /v1/orders/.
| Parameter | Typ | Povinne | Popis |
|---|---|---|---|
Amount | int | áno | Suma v menovej jednotke ISO 4217 meny (napríklad centy pre EUR) |
Currency | string | Ano | ISO 4217 kod (EUR, GBP, USD, NOK, SEK) |
MerchantOrderId | string? | Nie | Vasa interna referencia objednavky |
Description | string? | Nie | Popis objednavky |
ReturnUrl | string? | Nie | Presmerovanie po uspesnej platbe |
FailureUrl | string? | Nie | Presmerovanie pri zruseni/exspiracii/chybe |
WebhookUrl | string? | Nie | Asynchronne notifikacie o zmene stavu |
Locale | string? | Nie | Jazyk HPP (en-GB, de-DE, nl-NL, atd.) |
PaymentMethods | IReadOnlyList<string>? | Nie | Filter platobnych metod HPP |
ExpirationPeriod | string? | Nie | ISO 8601 trvanie (PT30M) |
Dostupne platobne metody: credit-card, apple-pay, google-pay, vipps-mobilepay
client.GetOrderAsync(orderId): Task<Order>
Ziskanie podrobnosti objednavky cez GET /v1/orders/{id}/.
client.CreateRefundAsync(orderId, amount, description?): Task<Refund>
Vydanie uplneho alebo ciastocneho vratenia cez POST /v1/orders/{id}/refunds/.
client.GeneratePaymentUrlAsync(params): Task<PaymentUrlResult>
Pomocna metoda, ktora vytvori objednavku a vrati:
public record PaymentUrlResult(
string OrderId, // NoPayn UUID objednavky
string OrderUrl, // HPP URL
string? PaymentUrl, // Priama platobna URL (prva transakcia)
string Signature, // HMAC-SHA256 z amount:currency:orderId
Order Order // Uplny objekt objednavky
);client.GenerateSignature(amount, currency, orderId): string
Generuje HMAC-SHA256 hex podpis.
client.VerifySignature(amount, currency, orderId, signature): bool
Overovanie HMAC-SHA256 podpisu v konstantnom case.
client.VerifyWebhookAsync(rawBody): Task<VerifiedWebhook>
Parsuje telo webhooku, potom vola GET /v1/orders/{id}/ na overenie skutocneho stavu.
Samostatne HMAC nastroje
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);Spracovanie chyb
using NoPayn.Exceptions;
try
{
await nopayn.CreateOrderAsync(new CreateOrderParams { Amount = 100, Currency = "EUR" });
}
catch (ApiException ex)
{
Console.Error.WriteLine(ex.StatusCode); // 401, 400, atd.
Console.Error.WriteLine(ex.ErrorBody); // Surova API chybova odpoved
}
catch (NoPaynException ex)
{
Console.Error.WriteLine(ex.Message); // Sietova alebo parsovania chyba
}| Vynimka | Popis |
|---|---|
NoPaynException | Zakladna vynimka (siet, parsovanie) |
ApiException | HTTP chyba z API |
WebhookException | Neplatny payload webhooku |
Stavy objednavok
| Stav | Koncovy? | Popis |
|---|---|---|
new | Nie | Objednavka vytvorena |
processing | Nie | Platba prebieha |
completed | Ano | Platba uspesna -- doructe tovar |
cancelled | Ano | Platba zrusena zakaznikom |
expired | Ano | Platobny odkaz vyprsal |
error | Ano | Technicka chyba |
Osvedcene postupy pre webhooky
- Vzdy overujte cez API -- payload webhooku obsahuje len ID objednavky, nikdy nie stav. SDK
VerifyWebhookAsync()to robi automaticky. - Vracajte HTTP 200 na potvrdenie prijatia. Akykolvek iny kod spusti az 10 opakovanych pokusov (2 minuty od seba).
- Implementujte zalohu dotazovanie -- pre objednavky starsie ako 10 minut, ktore nedosiahli konecny stav, dotazujte
GetOrderAsync()ako bezpecnostnu siet. - Budte idempotentni -- ten isty webhook mozete prijat viackrat.
Testovacie karty
Pouzite tieto karty v testovacom rezime Cost+ (sandbox webova stranka):
| Karta | Cislo | Poznamky |
|---|---|---|
| Visa (uspech) | 4111 1111 1111 1111 | Akekolvek CVV |
| Mastercard (uspech) | 5544 3300 0003 7 | Akekolvek CVV |
| Visa (zamietnutie) | 4111 1111 1111 1105 | Do Not Honor |
| Visa (nedostatok prostriedkov) | 4111 1111 1111 1151 | Insufficient Funds |
Pouzite akykolvek buduci datum exspiracie a akykolvek 3-ciselny CVC.
Demo aplikacia
Demo aplikacia na baze Dockeru s ASP.NET Core je zahrnuta v GitHub repozitari na testovanie uplneho platobneho procesu.
Podpora
Potrebujete pomoc? Kontaktujte nas tym podpory na support@costplus.io.