Cost+Docs

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.Json a System.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

Instalacia

dotnet add package NoPayn

Alebo ako lokalna referencia projektu:

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

Rychly 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 objednavky

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

ParameterTypPovinnePredvolene
ApiKeystringAno--
MerchantIdstringAno--
BaseUrlstringNiehttps://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/.

ParameterTypPovinnePopis
AmountintánoSuma v menovej jednotke ISO 4217 meny (napríklad centy pre EUR)
CurrencystringAnoISO 4217 kod (EUR, GBP, USD, NOK, SEK)
MerchantOrderIdstring?NieVasa interna referencia objednavky
Descriptionstring?NiePopis objednavky
ReturnUrlstring?NiePresmerovanie po uspesnej platbe
FailureUrlstring?NiePresmerovanie pri zruseni/exspiracii/chybe
WebhookUrlstring?NieAsynchronne notifikacie o zmene stavu
Localestring?NieJazyk HPP (en-GB, de-DE, nl-NL, atd.)
PaymentMethodsIReadOnlyList<string>?NieFilter platobnych metod HPP
ExpirationPeriodstring?NieISO 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
}
VynimkaPopis
NoPaynExceptionZakladna vynimka (siet, parsovanie)
ApiExceptionHTTP chyba z API
WebhookExceptionNeplatny payload webhooku

Stavy objednavok

StavKoncovy?Popis
newNieObjednavka vytvorena
processingNiePlatba prebieha
completedAnoPlatba uspesna -- doructe tovar
cancelledAnoPlatba zrusena zakaznikom
expiredAnoPlatobny odkaz vyprsal
errorAnoTechnicka chyba

Osvedcene postupy pre webhooky

  1. Vzdy overujte cez API -- payload webhooku obsahuje len ID objednavky, nikdy nie stav. SDK VerifyWebhookAsync() to robi automaticky.
  2. Vracajte HTTP 200 na potvrdenie prijatia. Akykolvek iny kod spusti az 10 opakovanych pokusov (2 minuty od seba).
  3. Implementujte zalohu dotazovanie -- pre objednavky starsie ako 10 minut, ktore nedosiahli konecny stav, dotazujte GetOrderAsync() ako bezpecnostnu siet.
  4. Budte idempotentni -- ten isty webhook mozete prijat viackrat.

Testovacie karty

Pouzite tieto karty v testovacom rezime Cost+ (sandbox webova stranka):

KartaCisloPoznamky
Visa (uspech)4111 1111 1111 1111Akekolvek CVV
Mastercard (uspech)5544 3300 0003 7Akekolvek CVV
Visa (zamietnutie)4111 1111 1111 1105Do Not Honor
Visa (nedostatok prostriedkov)4111 1111 1111 1151Insufficient 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.

On this page