Cost+Docs

C# / .NET

Officielt C#/.NET SDK til Cost+ betalingsgateway

Officielt C#/.NET SDK til Cost+ betalingsgateway. Forenkler HPP (Hosted Payment Page) redirect-flowet, HMAC payload-signering og webhook-verificering.

Funktioner

  • Ingen afhængigheder — bruger kun indbygget System.Text.Json og System.Security.Cryptography
  • Targeterer .NET 8.0 med C# 12-funktioner (records, file-scoped namespaces, pattern matching)
  • Nullable reference types aktiveret overalt
  • HMAC-SHA256 signaturgenerering og tidskonstant verificering
  • Automatisk snake_case/PascalCase-mapping mellem API'et og SDK'et
  • Webhook-parsing + API-baseret ordreverificering
  • Fuldt asynkront API-interface

Krav

Installation

dotnet add package NoPayn

Eller som lokal projektreference:

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

Hurtigstart

1. Initialiser klienten

using NoPayn;
using NoPayn.Models;

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

2. Opret en betaling og omdiriger til HPP'en

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. Håndter webhooken

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

ParameterTypePåkrævetStandard
ApiKeystringJa
MerchantIdstringJa
BaseUrlstringNejhttps://api.nopayn.co.uk

En valgfri HttpClient kan sendes som den anden constructor-parameter til tilpasset HTTP-håndtering eller test.

client.CreateOrderAsync(params): Task<Order>

Opretter en ordre via POST /v1/orders/.

ParameterTypePåkrævetBeskrivelse
AmountintJaBeløb i mindste valutaenhed (øre/cent)
CurrencystringJaISO 4217-kode (EUR, GBP, USD, NOK, SEK)
MerchantOrderIdstring?NejDin interne ordrereference
Descriptionstring?NejOrdrebeskrivelse
ReturnUrlstring?NejOmdirigering efter vellykket betaling
FailureUrlstring?NejOmdirigering ved annullering/udløb/fejl
WebhookUrlstring?NejAsynkrone statusændringsnotifikationer
Localestring?NejHPP-sprog (en-GB, de-DE, nl-NL osv.)
PaymentMethodsIReadOnlyList<string>?NejFiltrer HPP-metoder
ExpirationPeriodstring?NejISO 8601-varighed (PT30M)

Tilgængelige betalingsmetoder: credit-card, apple-pay, google-pay, vipps-mobilepay

client.GetOrderAsync(orderId): Task<Order>

Henter ordredetaljer via GET /v1/orders/{id}/.

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

Udsteder en fuld eller delvis refusion via POST /v1/orders/{id}/refunds/.

client.GeneratePaymentUrlAsync(params): Task<PaymentUrlResult>

Convenience-metode der opretter en ordre og returnerer:

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

Genererer en HMAC-SHA256 hex-signatur.

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

Tidskonstant verificering af en HMAC-SHA256-signatur.

client.VerifyWebhookAsync(rawBody): Task<VerifiedWebhook>

Parser webhook-kroppen og kalder derefter GET /v1/orders/{id}/ for at verificere den faktiske status.

Selvstændige HMAC-hjælpefunktioner

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

Fejlhåndtering

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
}
UndtagelseBeskrivelse
NoPaynExceptionGrundundtagelse (netværk, parsing)
ApiExceptionHTTP-fejl fra API'et
WebhookExceptionUgyldig webhook-payload

Ordrestatusser

StatusEndelig?Beskrivelse
newNejOrdre oprettet
processingNejBetaling i gang
completedJaBetaling vellykket — lever varerne
cancelledJaBetaling annulleret af kunden
expiredJaBetalingslink udløbet
errorJaTeknisk fejl

Webhook best practices

  1. Verificer altid via API'et — webhook-payloaden indeholder kun ordre-ID'et, aldrig status. SDK'ets VerifyWebhookAsync() gør dette automatisk.
  2. Returner HTTP 200 for at bekræfte modtagelsen. Enhver anden kode udløser op til 10 genforsøg (2 minutters mellemrum).
  3. Implementer en backup-poller — for ordrer ældre end 10 minutter, der ikke har nået en endelig status, poll GetOrderAsync() som sikkerhedsnet.
  4. Vær idempotent — du kan modtage den samme webhook flere gange.

Testkort

Brug disse kort i Cost+ testtilstand (sandbox-website):

KortNummerNoter
Visa (succes)4111 1111 1111 1111Vilkårlig CVV
Mastercard (succes)5544 3300 0003 7Vilkårlig CVV
Visa (afvist)4111 1111 1111 1105Do Not Honor
Visa (utilstrækkelig saldo)4111 1111 1111 1151Insufficient Funds

Brug en vilkårlig fremtidig udløbsdato og en vilkårlig 3-cifret CVC.

Demo-app

En Docker-baseret ASP.NET Core demo-app er inkluderet i GitHub-repositoriet til test af det fulde betalingsflow.

Support

Brug for hjælp? Kontakt vores supportteam på support@costplus.io.

On this page