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.JsonundSystem.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
- .NET 8.0 SDK oder neuer
- Ein Cost+ Händlerkonto — dashboard.costplus.io
Installation
dotnet add package NoPaynOder als lokale Projektreferenz:
dotnet add reference path/to/src/NoPayn/NoPayn.csprojSchnellstart
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 UUID3. 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?)
| Parameter | Typ | Erforderlich | Standard |
|---|---|---|---|
ApiKey | string | Ja | — |
MerchantId | string | Ja | — |
BaseUrl | string | Nein | https://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/.
| Parameter | Typ | Erforderlich | Beschreibung |
|---|---|---|---|
Amount | int | Ja | Betrag in kleinster Währungseinheit (Cent) |
Currency | string | Ja | ISO 4217 Code (EUR, GBP, USD, NOK, SEK) |
MerchantOrderId | string? | Nein | Ihre interne Bestellreferenz |
Description | string? | Nein | Bestellbeschreibung |
ReturnUrl | string? | Nein | Weiterleitung nach erfolgreicher Zahlung |
FailureUrl | string? | Nein | Weiterleitung bei Abbruch/Ablauf/Fehler |
WebhookUrl | string? | Nein | Asynchrone Statusänderungs-Benachrichtigungen |
Locale | string? | Nein | HPP-Sprache (en-GB, de-DE, nl-NL usw.) |
PaymentMethods | IReadOnlyList<string>? | Nein | HPP-Methoden filtern |
ExpirationPeriod | string? | Nein | ISO 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
}| Exception | Beschreibung |
|---|---|
NoPaynException | Basis-Exception (Netzwerk, Parsing) |
ApiException | HTTP-Fehler von der API |
WebhookException | Ungültiger Webhook-Payload |
Bestellungsstatus
| Status | Endgültig? | Beschreibung |
|---|---|---|
new | Nein | Bestellung erstellt |
processing | Nein | Zahlung in Bearbeitung |
completed | Ja | Zahlung erfolgreich — Ware liefern |
cancelled | Ja | Zahlung vom Kunden storniert |
expired | Ja | Zahlungslink abgelaufen |
error | Ja | Technischer Fehler |
Webhook Best Practices
- 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. - HTTP 200 zurückgeben, um den Empfang zu bestätigen. Jeder andere Code löst bis zu 10 Wiederholungsversuche aus (im 2-Minuten-Abstand).
- Backup-Poller implementieren — für Bestellungen, die älter als 10 Minuten sind und noch keinen Endstatus erreicht haben,
GetOrderAsync()als Sicherheitsnetz abfragen. - Idempotent sein — Sie können denselben Webhook mehrfach erhalten.
Testkarten
Verwenden Sie diese Karten im Cost+ Testmodus (Sandbox-Website):
| Karte | Nummer | Hinweise |
|---|---|---|
| Visa (Erfolg) | 4111 1111 1111 1111 | Beliebiger CVV |
| Mastercard (Erfolg) | 5544 3300 0003 7 | Beliebiger CVV |
| Visa (abgelehnt) | 4111 1111 1111 1105 | Do Not Honor |
| Visa (unzureichendes Guthaben) | 4111 1111 1111 1151 | Insufficient 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.