Cost+Docs

C# / .NET

Officiellt C#/.NET SDK för Cost+ betalningsgateway

Officiellt C#/.NET SDK för Cost+ betalningsgateway. Förenklar HPP-omdirigeringsflödet (Hosted Payment Page), HMAC payload-signering och webhook-verifiering.

Funktioner

  • Inga beroenden — använder bara inbyggda System.Text.Json och System.Security.Cryptography
  • Riktar sig mot .NET 8.0 med C# 12-funktioner (records, file-scoped namespaces, pattern matching)
  • Nullable reference types aktiverat genomgående
  • HMAC-SHA256 signaturgenerering och verifiering med konstant tid
  • Automatisk snake_case/PascalCase-mappning mellan API:et och SDK:t
  • Webhook-tolkning + API-baserad orderverifiering
  • Fullt asynkron API-yta

Krav

Installation

dotnet add package NoPayn

Eller som lokal projektreferens:

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

Snabbstart

1. Initiera klienten

using NoPayn;
using NoPayn.Models;

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

2. Skapa en betalning och omdirigera till 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 UUID

3. Hantera 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-referens

new NoPaynClient(config, httpClient?)

ParameterTypObligatoriskStandard
ApiKeystringJa
MerchantIdstringJa
BaseUrlstringNejhttps://api.nopayn.co.uk

En valfri HttpClient kan skickas som den andra konstruktorparametern för anpassad HTTP-hantering eller testning.

client.CreateOrderAsync(params): Task<Order>

Skapar en order via POST /v1/orders/.

ParameterTypObligatoriskBeskrivning
AmountintJaBelopp i minsta valutaenhet (cent)
CurrencystringJaISO 4217-kod (EUR, GBP, USD, NOK, SEK)
MerchantOrderIdstring?NejDin interna orderreferens
Descriptionstring?NejOrderbeskrivning
ReturnUrlstring?NejOmdirigering efter lyckad betalning
FailureUrlstring?NejOmdirigering vid avbrytning/utgång/fel
WebhookUrlstring?NejAsynkrona statusändringsnotifieringar
Localestring?NejHPP-språk (en-GB, de-DE, nl-NL, etc.)
PaymentMethodsIReadOnlyList<string>?NejFiltrera HPP-metoder
ExpirationPeriodstring?NejISO 8601-duration (PT30M)

Tillgängliga betalningsmetoder: credit-card, apple-pay, google-pay, vipps-mobilepay

client.GetOrderAsync(orderId): Task<Order>

Hämtar orderdetaljer via GET /v1/orders/{id}/.

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

Utfärdar en fullständig eller partiell återbetalning via POST /v1/orders/{id}/refunds/.

client.GeneratePaymentUrlAsync(params): Task<PaymentUrlResult>

Bekvämlighetsmetod som skapar en order och returnerar:

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

Genererar en HMAC-SHA256 hex-signatur.

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

Verifiering med konstant tid av en HMAC-SHA256-signatur.

client.VerifyWebhookAsync(rawBody): Task<VerifiedWebhook>

Tolkar webhook-kroppen och anropar sedan GET /v1/orders/{id}/ för att verifiera faktisk status.

Fristående HMAC-verktyg

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

Felhantering

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
}
UndantagBeskrivning
NoPaynExceptionBasundantag (nätverk, tolkning)
ApiExceptionHTTP-fel från API:et
WebhookExceptionOgiltig webhook-payload

Orderstatusar

StatusSlutgiltig?Beskrivning
newNejOrder skapad
processingNejBetalning pågår
completedJaBetalning lyckades — leverera varorna
cancelledJaBetalning avbruten av kunden
expiredJaBetalningslänken löpte ut
errorJaTekniskt fel

Bästa praxis för webhooks

  1. Verifiera alltid via API:et — webhook-payloaden innehåller bara order-ID:t, aldrig statusen. SDK:ts VerifyWebhookAsync() gör detta automatiskt.
  2. Returnera HTTP 200 för att bekräfta mottagandet. Annan kod utlöser upp till 10 omförsök (2 minuter emellan).
  3. Implementera en reservpoller — för ordrar äldre än 10 minuter som inte har nått slutgiltig status, polla GetOrderAsync() som säkerhetsnät.
  4. Var idempotent — du kan ta emot samma webhook flera gånger.

Testkort

Använd dessa kort i Cost+ testläge (sandbox-webbplats):

KortNummerNoteringar
Visa (lyckad)4111 1111 1111 1111Valfritt CVV
Mastercard (lyckad)5544 3300 0003 7Valfritt CVV
Visa (nekad)4111 1111 1111 1105Do Not Honor
Visa (otillräckligt saldo)4111 1111 1111 1151Insufficient Funds

Använd valfritt framtida utgångsdatum och valfri 3-siffrig CVC.

Demoapplikation

En Docker-baserad ASP.NET Core-demoapplikation ingår i GitHub-repositoryt för att testa det fullständiga betalningsflödet.

Support

Behöver du hjälp? Kontakta vårt supportteam på support@costplus.io.

On this page