C# / .NET

Oficjalny SDK C#/.NET dla bramki płatności Cost+. Upraszcza przepływ przekierowań HPP (hostowanej strony płatności), podpisywanie HMAC i weryfikację webhooków.

Funkcje

Zero zależności — używa tylko wbudowanych System.Text.Json i System.Security.Cryptography
Wymaga .NET 8.0 z funkcjami C# 12 (rekordy, przestrzenie nazw w zakresie pliku, dopasowywanie wzorców)
Nullable reference types włączone w całym SDK
Generowanie podpisów HMAC-SHA256 i weryfikacja w stałym czasie
Automatyczne mapowanie snake_case/PascalCase między API a SDK
Parsowanie webhooków + weryfikacja zamówienia przez API
W pełni asynchroniczna powierzchnia API

Wymagania

.NET 8.0 SDK lub nowszy
Konto sprzedawcy Cost+ — dashboard.costplus.io

Instalacja

dotnet add package NoPayn

Lub jako lokalna referencja projektu:

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

Szybki start

1. Zainicjalizuj klienta

using NoPayn;
using NoPayn.Models;

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

2. Utwórz płatność i przekieruj na HPP

var result = await nopayn.GeneratePaymentUrlAsync(new CreateOrderParams
{
    Amount = 1295,              // 12,95 EUR w centach
    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",
});

// Przekieruj klienta
// result.OrderUrl   → HPP (klient wybiera metodę płatności)
// result.PaymentUrl → bezpośredni link do metody płatności pierwszej transakcji
// result.Signature  → HMAC-SHA256 do weryfikacji
// result.OrderId    → UUID zamówienia NoPayn

3. Obsłuż 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", itp.
    Console.WriteLine(verified.IsFinal);      // true gdy zamówienie się nie zmieni

    if (verified.Order.Status == "completed")
    {
        // Zrealizuj zamówienie
    }

    return Results.Ok();
});

Dokumentacja API

`new NoPaynClient(config, httpClient?)`

Parametr	Typ	Wymagany	Domyślnie
`ApiKey`	`string`	Tak	—
`MerchantId`	`string`	Tak	—
`BaseUrl`	`string`	Nie	`https://api.nopayn.co.uk`

Opcjonalny HttpClient może być przekazany jako drugi parametr konstruktora dla niestandardowej obsługi HTTP lub testowania.

`client.CreateOrderAsync(params): Task<Order>`

Tworzy zamówienie przez POST /v1/orders/.

Parametr	Typ	Wymagany	Opis
`Amount`	`int`	Tak	Kwota w najmniejszej jednostce waluty (centy)
`Currency`	`string`	Tak	Kod ISO 4217 (`EUR`, `GBP`, `USD`, `NOK`, `SEK`)
`MerchantOrderId`	`string?`	Nie	Twoja wewnętrzna referencja zamówienia
`Description`	`string?`	Nie	Opis zamówienia
`ReturnUrl`	`string?`	Nie	Przekierowanie po pomyślnej płatności
`FailureUrl`	`string?`	Nie	Przekierowanie przy anulowaniu/wygaśnięciu/błędzie
`WebhookUrl`	`string?`	Nie	Asynchroniczne powiadomienia o zmianie statusu
`Locale`	`string?`	Nie	Język HPP (`en-GB`, `de-DE`, `nl-NL`, itp.)
`PaymentMethods`	`IReadOnlyList<string>?`	Nie	Filtruj metody HPP
`ExpirationPeriod`	`string?`	Nie	Czas trwania ISO 8601 (`PT30M`)

Dostępne metody płatności: credit-card, apple-pay, google-pay, vipps-mobilepay

`client.GetOrderAsync(orderId): Task<Order>`

Pobiera szczegóły zamówienia przez GET /v1/orders/{id}/.

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

Dokonuje pełnego lub częściowego zwrotu przez POST /v1/orders/{id}/refunds/.

`client.GeneratePaymentUrlAsync(params): Task<PaymentUrlResult>`

Metoda pomocnicza, która tworzy zamówienie i zwraca:

public record PaymentUrlResult(
    string OrderId,        // UUID zamówienia NoPayn
    string OrderUrl,       // URL HPP
    string? PaymentUrl,    // Bezpośredni URL płatności (pierwsza transakcja)
    string Signature,      // HMAC-SHA256 z amount:currency:orderId
    Order Order            // Pełny obiekt zamówienia
);

`client.GenerateSignature(amount, currency, orderId): string`

Generuje podpis HMAC-SHA256 w formacie hex.

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

Weryfikacja HMAC-SHA256 w stałym czasie.

`client.VerifyWebhookAsync(rawBody): Task<VerifiedWebhook>`

Parsuje treść webhooka, następnie wywołuje GET /v1/orders/{id}/, aby zweryfikować rzeczywisty status.

Samodzielne narzędzia HMAC

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

Obsługa błędów

using NoPayn.Exceptions;

try
{
    await nopayn.CreateOrderAsync(new CreateOrderParams { Amount = 100, Currency = "EUR" });
}
catch (ApiException ex)
{
    Console.Error.WriteLine(ex.StatusCode);  // 401, 400, itp.
    Console.Error.WriteLine(ex.ErrorBody);   // Surowa odpowiedź błędu API
}
catch (NoPaynException ex)
{
    Console.Error.WriteLine(ex.Message);     // Błąd sieci lub parsowania
}

Wyjątek	Opis
`NoPaynException`	Bazowy wyjątek (sieć, parsowanie)
`ApiException`	Błąd HTTP z API
`WebhookException`	Nieprawidłowa treść webhooka

Statusy zamówień

Status	Końcowy?	Opis
`new`	Nie	Zamówienie utworzone
`processing`	Nie	Płatność w toku
`completed`	Tak	Płatność zakończona sukcesem — wydaj towar
`cancelled`	Tak	Płatność anulowana przez klienta
`expired`	Tak	Link płatności wygasł
`error`	Tak	Błąd techniczny

Najlepsze praktyki dotyczące webhooków

Zawsze weryfikuj przez API — treść webhooka zawiera tylko identyfikator zamówienia, nigdy status. VerifyWebhookAsync() SDK robi to automatycznie.
Zwracaj HTTP 200, aby potwierdzić odbiór. Każdy inny kod powoduje do 10 ponowień (co 2 minuty).
Zaimplementuj zapasowe odpytywanie — dla zamówień starszych niż 10 minut, które nie osiągnęły końcowego statusu, odpytuj GetOrderAsync() jako zabezpieczenie.
Bądź idempotentny — możesz otrzymać ten sam webhook wielokrotnie.

Karty testowe

Użyj tych kart w trybie testowym Cost+ (strona testowa):

Karta	Numer	Uwagi
Visa (sukces)	`4111 1111 1111 1111`	Dowolny CVV
Mastercard (sukces)	`5544 3300 0003 7`	Dowolny CVV
Visa (odrzucona)	`4111 1111 1111 1105`	Do Not Honor
Visa (brak środków)	`4111 1111 1111 1151`	Insufficient Funds

Użyj dowolnej przyszłej daty ważności i dowolnego 3-cyfrowego CVC.

Aplikacja demonstracyjna

Aplikacja demonstracyjna oparta na Dockerze z ASP.NET Core jest dołączona w repozytorium GitHub do testowania pełnego przepływu płatności.

Wsparcie

Potrzebujesz pomocy? Skontaktuj się z naszym zespołem wsparcia pod adresem support@costplus.io.

On this page