Cost+Docs

C# / .NET

Oficiální C#/.NET SDK pro platební bránu Cost+

Oficiální C#/.NET SDK pro platební bránu Cost+. Zjednodušuje tok přesměrování HPP (Hosted Payment Page), HMAC podepisování payloadu a ověřování webhooků.

Funkce

  • Žádné závislosti — používá pouze vestavěné System.Text.Json a System.Security.Cryptography
  • Cílí na .NET 8.0 s funkcemi C# 12 (records, file-scoped namespaces, pattern matching)
  • Nullable reference types povoleny v celém projektu
  • Generování podpisů HMAC-SHA256 a ověřování s konstantním časem
  • Automatické mapování snake_case/PascalCase mezi API a SDK
  • Parsování webhooků + ověřování objednávek přes API
  • Plně asynchronní API

Požadavky

Instalace

dotnet add package NoPayn

Nebo jako lokální reference projektu:

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

Rychlý start

1. Inicializace klienta

using NoPayn;
using NoPayn.Models;

var nopayn = new NoPaynClient(new NoPaynConfig(
    ApiKey: "your-api-key",
    MerchantId: "your-project"
));

2. Vytvoření platby a přesměrování na 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 UUID

3. Zpracování 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", etc.
    Console.WriteLine(verified.IsFinal);      // true when the order won't change

    if (verified.Order.Status == "completed")
    {
        // Fulfil the order
    }

    return Results.Ok();
});

API reference

new NoPaynClient(config, httpClient?)

ParametrTypPovinnéVýchozí
ApiKeystringAno
MerchantIdstringAno
BaseUrlstringNehttps://api.nopayn.co.uk

Volitelný HttpClient lze předat jako druhý parametr konstruktoru pro vlastní HTTP zpracování nebo testování.

client.CreateOrderAsync(params): Task<Order>

Vytvoří objednávku přes POST /v1/orders/.

ParametrTypPovinnéPopis
AmountintAnoČástka v nejmenší měnové jednotce (centy)
CurrencystringAnoISO 4217 kód (EUR, GBP, USD, NOK, SEK)
MerchantOrderIdstring?NeVaše interní reference objednávky
Descriptionstring?NePopis objednávky
ReturnUrlstring?NePřesměrování po úspěšné platbě
FailureUrlstring?NePřesměrování při zrušení/vypršení/chybě
WebhookUrlstring?NeAsynchronní notifikace o změně stavu
Localestring?NeJazyk HPP (en-GB, de-DE, nl-NL atd.)
PaymentMethodsIReadOnlyList<string>?NeFiltr metod HPP
ExpirationPeriodstring?NeISO 8601 doba trvání (PT30M)

Dostupné platební metody: credit-card, apple-pay, google-pay, vipps-mobilepay

client.GetOrderAsync(orderId): Task<Order>

Načte detaily objednávky přes GET /v1/orders/{id}/.

client.CreateRefundAsync(orderId, amount, description?): Task<Refund>

Provede úplnou nebo částečnou refundaci přes POST /v1/orders/{id}/refunds/.

client.GeneratePaymentUrlAsync(params): Task<PaymentUrlResult>

Pohodlná metoda, která vytvoří objednávku a vrátí:

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

Generuje HMAC-SHA256 hex podpis.

client.VerifySignature(amount, currency, orderId, signature): bool

Ověření HMAC-SHA256 podpisu s konstantním časem.

client.VerifyWebhookAsync(rawBody): Task<VerifiedWebhook>

Parsuje tělo webhooku a poté zavolá GET /v1/orders/{id}/ pro ověření skutečného stavu.

Samostatné HMAC utility

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);

Zpracování chyb

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
}
VýjimkaPopis
NoPaynExceptionZákladní výjimka (síť, parsování)
ApiExceptionHTTP chyba z API
WebhookExceptionNeplatný webhookový payload

Stavy objednávek

StavKonečný?Popis
newNeObjednávka vytvořena
processingNePlatba probíhá
completedAnoPlatba úspěšná — doručte zboží
cancelledAnoPlatba zrušena zákazníkem
expiredAnoPlatební odkaz vypršel
errorAnoTechnická chyba

Osvědčené postupy pro webhooky

  1. Vždy ověřte přes API — webhookový payload obsahuje pouze ID objednávky, nikdy stav. Metoda VerifyWebhookAsync() SDK to dělá automaticky.
  2. Vraťte HTTP 200 jako potvrzení přijetí. Jakýkoli jiný kód spustí až 10 opakování (po 2 minutách).
  3. Implementujte záložní polling — pro objednávky starší než 10 minut, které nedosáhly konečného stavu, dotazujte GetOrderAsync() jako záchrannou síť.
  4. Buďte idempotentní — stejný webhook můžete obdržet vícekrát.

Testovací karty

Tyto karty použijte v testovacím režimu Cost+ (sandbox web):

KartaČísloPoznámky
Visa (úspěch)4111 1111 1111 1111Libovolné CVV
Mastercard (úspěch)5544 3300 0003 7Libovolné CVV
Visa (zamítnuto)4111 1111 1111 1105Do Not Honor
Visa (nedostatek prostředků)4111 1111 1111 1151Insufficient Funds

Použijte libovolné budoucí datum platnosti a libovolný 3místný CVC.

Demo aplikace

Demo aplikace ASP.NET Core založená na Dockeru je součástí GitHub repozitáře pro testování celého platebního toku.

Podpora

Potřebujete pomoc? Obraťte se na náš tým podpory na support@costplus.io.

On this page