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.JsonaSystem.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
- .NET 8.0 SDK nebo novější
- Obchodní účet Cost+ — dashboard.costplus.io
Instalace
dotnet add package NoPaynNebo jako lokální reference projektu:
dotnet add reference path/to/src/NoPayn/NoPayn.csprojRychlý 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 UUID3. 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?)
| Parametr | Typ | Povinné | Výchozí |
|---|---|---|---|
ApiKey | string | Ano | — |
MerchantId | string | Ano | — |
BaseUrl | string | Ne | https://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/.
| Parametr | Typ | Povinné | Popis |
|---|---|---|---|
Amount | int | Ano | Částka v nejmenší měnové jednotce (centy) |
Currency | string | Ano | ISO 4217 kód (EUR, GBP, USD, NOK, SEK) |
MerchantOrderId | string? | Ne | Vaše interní reference objednávky |
Description | string? | Ne | Popis objednávky |
ReturnUrl | string? | Ne | Přesměrování po úspěšné platbě |
FailureUrl | string? | Ne | Přesměrování při zrušení/vypršení/chybě |
WebhookUrl | string? | Ne | Asynchronní notifikace o změně stavu |
Locale | string? | Ne | Jazyk HPP (en-GB, de-DE, nl-NL atd.) |
PaymentMethods | IReadOnlyList<string>? | Ne | Filtr metod HPP |
ExpirationPeriod | string? | Ne | ISO 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ýjimka | Popis |
|---|---|
NoPaynException | Základní výjimka (síť, parsování) |
ApiException | HTTP chyba z API |
WebhookException | Neplatný webhookový payload |
Stavy objednávek
| Stav | Konečný? | Popis |
|---|---|---|
new | Ne | Objednávka vytvořena |
processing | Ne | Platba probíhá |
completed | Ano | Platba úspěšná — doručte zboží |
cancelled | Ano | Platba zrušena zákazníkem |
expired | Ano | Platební odkaz vypršel |
error | Ano | Technická chyba |
Osvědčené postupy pro webhooky
- Vždy ověřte přes API — webhookový payload obsahuje pouze ID objednávky, nikdy stav. Metoda
VerifyWebhookAsync()SDK to dělá automaticky. - Vraťte HTTP 200 jako potvrzení přijetí. Jakýkoli jiný kód spustí až 10 opakování (po 2 minutách).
- 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íť. - 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 | Číslo | Poznámky |
|---|---|---|
| Visa (úspěch) | 4111 1111 1111 1111 | Libovolné CVV |
| Mastercard (úspěch) | 5544 3300 0003 7 | Libovolné CVV |
| Visa (zamítnuto) | 4111 1111 1111 1105 | Do Not Honor |
| Visa (nedostatek prostředků) | 4111 1111 1111 1151 | Insufficient 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.