Cost+Docs

C# / .NET

Oficialus C#/.NET SDK Cost+ mokėjimų šliuzui

Oficialus C#/.NET SDK Cost+ mokėjimų šliuzui. Supaprastina HPP (mokėjimo puslapio) nukreipimo procesą, HMAC turinio pasirašymą ir webhook patvirtinimą.

Savybės

  • Jokių priklausomybių — naudoja tik integruotus System.Text.Json ir System.Security.Cryptography
  • Skirta .NET 8.0 su C# 12 funkcijomis (records, file-scoped namespaces, pattern matching)
  • Nullable nuorodų tipai įjungti visur
  • HMAC-SHA256 parašo generavimas ir pastovaus laiko patikrinimas
  • Automatinis snake_case/PascalCase atitikimas tarp API ir SDK
  • Webhook analizė + API pagrįstas užsakymo patikrinimas
  • Visiškai asinchroninė API sąsaja

Reikalavimai

Diegimas

dotnet add package NoPayn

Arba kaip vietinė projekto nuoroda:

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

Greitas startas

1. Inicializuokite klientą

using NoPayn;
using NoPayn.Models;

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

2. Sukurkite mokėjimą ir nukreipkite į 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. Apdorokite Webhook

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 nuoroda

new NoPaynClient(config, httpClient?)

ParametrasTipasPrivalomasNumatytasis
ApiKeystringTaip
MerchantIdstringTaip
BaseUrlstringNehttps://api.nopayn.co.uk

Neprivalomas HttpClient gali būti perduotas kaip antras konstruktoriaus parametras pasirinktiniam HTTP tvarkymui ar testavimui.

client.CreateOrderAsync(params): Task<Order>

Sukuria užsakymą per POST /v1/orders/.

ParametrasTipasPrivalomasAprašymas
AmountintTaipSuma mažiausiu valiutos vienetu (centais)
CurrencystringTaipISO 4217 kodas (EUR, GBP, USD, NOK, SEK)
MerchantOrderIdstring?NeJūsų vidinis užsakymo nuorodos ID
Descriptionstring?NeUžsakymo aprašymas
ReturnUrlstring?NeNukreipimas po sėkmingo mokėjimo
FailureUrlstring?NeNukreipimas atšaukimo/galiojimo pabaigos/klaidos atveju
WebhookUrlstring?NeAsinchroniniai būsenos pakeitimo pranešimai
Localestring?NeHPP kalba (en-GB, de-DE, nl-NL ir kt.)
PaymentMethodsIReadOnlyList<string>?NeFiltruoti HPP mokėjimo būdus
ExpirationPeriodstring?NeISO 8601 trukmė (PT30M)

Prieinami mokėjimo būdai: credit-card, apple-pay, google-pay, vipps-mobilepay

client.GetOrderAsync(orderId): Task<Order>

Gauna užsakymo detales per GET /v1/orders/{id}/.

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

Atlieka pilną arba dalinį grąžinimą per POST /v1/orders/{id}/refunds/.

client.GeneratePaymentUrlAsync(params): Task<PaymentUrlResult>

Patogus metodas, kuris sukuria užsakymą ir grąžina:

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

Generuoja HMAC-SHA256 hex parašą.

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

Pastovaus laiko HMAC-SHA256 parašo patikrinimas.

client.VerifyWebhookAsync(rawBody): Task<VerifiedWebhook>

Analizuoja webhook turinį, tada iškviečia GET /v1/orders/{id}/, kad patikrintų tikrąją būseną.

Atskiros HMAC priemonės

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

Klaidų tvarkymas

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
}
IšimtisAprašymas
NoPaynExceptionBazinė išimtis (tinklas, analizė)
ApiExceptionHTTP klaida iš API
WebhookExceptionNetinkamas webhook turinys

Užsakymo būsenos

BūsenaGalutinė?Aprašymas
newNeUžsakymas sukurtas
processingNeMokėjimas vykdomas
completedTaipMokėjimas sėkmingas — pristatykite prekes
cancelledTaipMokėjimas atšauktas kliento
expiredTaipMokėjimo nuorodos laikas baigėsi
errorTaipTechninė klaida

Webhook geriausios praktikos

  1. Visada patikrinkite per API — webhook turinys pateikia tik užsakymo ID, niekada būsenos. SDK VerifyWebhookAsync() tai atlieka automatiškai.
  2. Grąžinkite HTTP 200, kad patvirtintumėte gavimą. Bet koks kitas kodas suaktyvina iki 10 pakartotinių bandymų (kas 2 minutes).
  3. Įgyvendinkite atsarginį tikrintuvą — užsakymams, senesniems nei 10 minučių, kurie nepasiekė galutinės būsenos, naudokite GetOrderAsync() kaip saugos tinklą.
  4. Būkite idempotentiški — galite gauti tą patį webhook kelis kartus.

Testinės kortelės

Naudokite šias korteles Cost+ testavimo režimu (testavimo svetainė):

KortelėNumerisPastabos
Visa (sėkminga)4111 1111 1111 1111Bet koks CVV
Mastercard (sėkminga)5544 3300 0003 7Bet koks CVV
Visa (atmesta)4111 1111 1111 1105Do Not Honor
Visa (nepakankamos lėšos)4111 1111 1111 1151Insufficient Funds

Naudokite bet kurią ateities galiojimo datą ir bet kokį 3 skaitmenų CVC.

Demonstracinė programa

Docker pagrįsta ASP.NET Core demonstracinė programa įtraukta į GitHub saugyklą pilnam mokėjimo proceso testavimui.

Palaikymas

Reikia pagalbos? Kreipkitės į mūsų palaikymo komandą adresu support@costplus.io.

On this page