Cost+Docs

C# / .NET

Offizielles C#/.NET SDK für das Cost+ Zahlungsgateway

Offizielles C#/.NET SDK für das Cost+ Zahlungsgateway. Vereinfacht den HPP (Hosted Payment Page) Weiterleitungsablauf, die HMAC-Payload-Signierung und die Webhook-Verifizierung.

Funktionen

  • Keine Abhängigkeiten — verwendet nur integrierte System.Text.Json und System.Security.Cryptography
  • Zielplattform .NET 8.0 mit C# 12 Features (Records, File-Scoped Namespaces, Pattern Matching)
  • Nullable Reference Types durchgehend aktiviert
  • HMAC-SHA256-Signaturgenerierung und zeitkonstante Verifizierung
  • Automatisches snake_case/PascalCase-Mapping zwischen API und SDK
  • Webhook-Parsing + API-basierte Bestellungsverifizierung
  • Vollständig asynchrone API-Oberfläche

Voraussetzungen

Installation

dotnet add package NoPayn

Oder als lokale Projektreferenz:

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

Schnellstart

1. Client initialisieren

using NoPayn;
using NoPayn.Models;

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

2. Zahlung erstellen und zur HPP weiterleiten

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. Webhook verarbeiten

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-Referenz

new NoPaynClient(config, httpClient?)

ParameterTypErforderlichStandard
ApiKeystringJa
MerchantIdstringJa
BaseUrlstringNeinhttps://api.nopayn.co.uk

Ein optionaler HttpClient kann als zweiter Konstruktorparameter für benutzerdefinierte HTTP-Verarbeitung oder Tests übergeben werden.

client.CreateOrderAsync(params): Task<Order>

Erstellt eine Bestellung über POST /v1/orders/.

ParameterTypErforderlichBeschreibung
AmountintJaBetrag in kleinster Währungseinheit (Cent)
CurrencystringJaISO 4217 Code (EUR, GBP, USD, NOK, SEK)
MerchantOrderIdstring?NeinIhre interne Bestellreferenz
Descriptionstring?NeinBestellbeschreibung
ReturnUrlstring?NeinWeiterleitung nach erfolgreicher Zahlung
FailureUrlstring?NeinWeiterleitung bei Abbruch/Ablauf/Fehler
WebhookUrlstring?NeinAsynchrone Statusänderungs-Benachrichtigungen
Localestring?NeinHPP-Sprache (en-GB, de-DE, nl-NL usw.)
PaymentMethodsIReadOnlyList<string>?NeinHPP-Methoden filtern
ExpirationPeriodstring?NeinISO 8601 Dauer (PT30M)

Verfügbare Zahlungsmethoden: credit-card, apple-pay, google-pay, vipps-mobilepay

client.GetOrderAsync(orderId): Task<Order>

Ruft Bestellungsdetails über GET /v1/orders/{id}/ ab.

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

Stellt eine vollständige oder teilweise Erstattung über POST /v1/orders/{id}/refunds/ aus.

client.GeneratePaymentUrlAsync(params): Task<PaymentUrlResult>

Komfortmethode, die eine Bestellung erstellt und zurückgibt:

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

Generiert eine HMAC-SHA256-Hex-Signatur.

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

Zeitkonstante Verifizierung einer HMAC-SHA256-Signatur.

client.VerifyWebhookAsync(rawBody): Task<VerifiedWebhook>

Parst den Webhook-Body und ruft dann GET /v1/orders/{id}/ auf, um den tatsächlichen Status zu verifizieren.

Eigenständige HMAC-Hilfsfunktionen

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

Fehlerbehandlung

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
}
ExceptionBeschreibung
NoPaynExceptionBasis-Exception (Netzwerk, Parsing)
ApiExceptionHTTP-Fehler von der API
WebhookExceptionUngültiger Webhook-Payload

Bestellungsstatus

StatusEndgültig?Beschreibung
newNeinBestellung erstellt
processingNeinZahlung in Bearbeitung
completedJaZahlung erfolgreich — Ware liefern
cancelledJaZahlung vom Kunden storniert
expiredJaZahlungslink abgelaufen
errorJaTechnischer Fehler

Webhook Best Practices

  1. Immer über die API verifizieren — der Webhook-Payload enthält nur die Bestell-ID, niemals den Status. Die VerifyWebhookAsync()-Methode des SDK erledigt dies automatisch.
  2. HTTP 200 zurückgeben, um den Empfang zu bestätigen. Jeder andere Code löst bis zu 10 Wiederholungsversuche aus (im 2-Minuten-Abstand).
  3. Backup-Poller implementieren — für Bestellungen, die älter als 10 Minuten sind und noch keinen Endstatus erreicht haben, GetOrderAsync() als Sicherheitsnetz abfragen.
  4. Idempotent sein — Sie können denselben Webhook mehrfach erhalten.

Testkarten

Verwenden Sie diese Karten im Cost+ Testmodus (Sandbox-Website):

KarteNummerHinweise
Visa (Erfolg)4111 1111 1111 1111Beliebiger CVV
Mastercard (Erfolg)5544 3300 0003 7Beliebiger CVV
Visa (abgelehnt)4111 1111 1111 1105Do Not Honor
Visa (unzureichendes Guthaben)4111 1111 1111 1151Insufficient Funds

Verwenden Sie ein beliebiges zukünftiges Ablaufdatum und eine beliebige 3-stellige CVC.

Demo-App

Eine Docker-basierte ASP.NET Core Demo-App ist im GitHub-Repository enthalten, um den vollständigen Zahlungsablauf zu testen.

Support

Brauchen Sie Hilfe? Kontaktieren Sie unser Support-Team unter support@costplus.io.

On this page