Cost+Docs

C# / .NET

Officiele C#/.NET SDK voor de Cost+ betaalgateway

Officiele C#/.NET SDK voor de Cost+ betaalgateway. Vereenvoudigt de HPP (Hosted Payment Page) doorverwijzingsflow, HMAC-payloadondertekening en webhookverificatie.

Kenmerken

  • Geen afhankelijkheden — gebruikt alleen ingebouwde System.Text.Json en System.Security.Cryptography
  • Vereist .NET 8.0 met C# 12-functies (records, file-scoped namespaces, pattern matching)
  • Nullable reference types overal ingeschakeld
  • HMAC-SHA256-handtekeninggeneratie en constant-time verificatie
  • Automatische snake_case/PascalCase-mapping tussen de API en de SDK
  • Webhook-parsing + API-gebaseerde bestellingsverificatie
  • Volledig async API-oppervlak

Vereisten

Installatie

dotnet add package NoPayn

Of als lokale projectreferentie:

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

Snelstart

1. De client initialiseren

using NoPayn;
using NoPayn.Models;

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

2. Een betaling aanmaken en doorverwijzen naar de 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. De webhook afhandelen

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

new NoPaynClient(config, httpClient?)

ParameterTypeVereistStandaard
ApiKeystringJa
MerchantIdstringJa
BaseUrlstringNeehttps://api.nopayn.co.uk

Een optionele HttpClient kan als tweede constructorparameter worden meegegeven voor aangepaste HTTP-afhandeling of testen.

client.CreateOrderAsync(params): Task<Order>

Maakt een bestelling aan via POST /v1/orders/.

ParameterTypeVereistBeschrijving
AmountintJaBedrag in kleinste valuta-eenheid (centen)
CurrencystringJaISO 4217-code (EUR, GBP, USD, NOK, SEK)
MerchantOrderIdstring?NeeUw interne bestellingsreferentie
Descriptionstring?NeeBestellingsbeschrijving
ReturnUrlstring?NeeDoorverwijzing na geslaagde betaling
FailureUrlstring?NeeDoorverwijzing bij annulering/verloop/fout
WebhookUrlstring?NeeAsynchrone statuswijzigingsmeldingen
Localestring?NeeHPP-taal (en-GB, de-DE, nl-NL, enz.)
PaymentMethodsIReadOnlyList<string>?NeeHPP-methoden filteren
ExpirationPeriodstring?NeeISO 8601-duur (PT30M)

Beschikbare betaalmethoden: credit-card, apple-pay, google-pay, vipps-mobilepay

client.GetOrderAsync(orderId): Task<Order>

Haalt bestellingsdetails op via GET /v1/orders/{id}/.

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

Voert een volledige of gedeeltelijke terugbetaling uit via POST /v1/orders/{id}/refunds/.

client.GeneratePaymentUrlAsync(params): Task<PaymentUrlResult>

Hulpmethode die een bestelling aanmaakt en retourneert:

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

Genereert een HMAC-SHA256 hex-handtekening.

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

Constant-time verificatie van een HMAC-SHA256-handtekening.

client.VerifyWebhookAsync(rawBody): Task<VerifiedWebhook>

Parst de webhook-body en roept vervolgens GET /v1/orders/{id}/ aan om de werkelijke status te verifieren.

Standalone HMAC-hulpmiddelen

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

Foutafhandeling

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
}
UitzonderingBeschrijving
NoPaynExceptionBasisuitzondering (netwerk, parsing)
ApiExceptionHTTP-fout van de API
WebhookExceptionOngeldige webhook-payload

Bestellingsstatussen

StatusDefinitief?Beschrijving
newNeeBestelling aangemaakt
processingNeeBetaling wordt verwerkt
completedJaBetaling geslaagd — lever de goederen
cancelledJaBetaling geannuleerd door klant
expiredJaBetaallink verlopen
errorJaTechnische storing

Best practices voor webhooks

  1. Verifieer altijd via de API — de webhook-payload bevat alleen het bestelling-ID, nooit de status. De VerifyWebhookAsync() van de SDK doet dit automatisch.
  2. Retourneer HTTP 200 om de ontvangst te bevestigen. Elke andere code triggert tot 10 herhaalpogingen (2 minuten tussenpozen).
  3. Implementeer een backup-poller — voor bestellingen ouder dan 10 minuten die nog geen definitieve status hebben bereikt, poll GetOrderAsync() als vangnet.
  4. Wees idempotent — u kunt dezelfde webhook meerdere keren ontvangen.

Testkaarten

Gebruik deze kaarten in Cost+ testmodus (sandbox-website):

KaartNummerOpmerkingen
Visa (geslaagd)4111 1111 1111 1111Willekeurige CVV
Mastercard (geslaagd)5544 3300 0003 7Willekeurige CVV
Visa (geweigerd)4111 1111 1111 1105Do Not Honor
Visa (onvoldoende saldo)4111 1111 1111 1151Insufficient Funds

Gebruik een willekeurige toekomstige vervaldatum en een willekeurige 3-cijferige CVC.

Demo-app

Een op Docker gebaseerde ASP.NET Core demo-app is opgenomen in de GitHub-repository om de volledige betalingsflow te testen.

Ondersteuning

Hulp nodig? Neem contact op met ons supportteam via support@costplus.io.

On this page