Cost+Docs

C# / .NET

Uradni C#/.NET SDK za plačilni prehod Cost+

Uradni C#/.NET SDK za plačilni prehod Cost+. Poenostavlja tok preusmeritve HPP (gostovane plačilne strani), HMAC podpisovanje koristnih podatkov in preverjanje webhook-ov.

Lastnosti

  • Brez odvisnosti — uporablja le vgrajeni System.Text.Json in System.Security.Cryptography
  • Ciljno .NET 8.0 z lastnostmi C# 12 (records, file-scoped namespaces, pattern matching)
  • Nullable reference types omogočeni povsod
  • HMAC-SHA256 generiranje podpisov in preverjanje s konstantnim časom
  • Samodejno preslikovanje snake_case/PascalCase med API-jem in SDK-jem
  • Razčlenjevanje webhook-ov + preverjanje naročil na osnovi API-ja
  • V celoti asinhroni API vmesnik

Zahteve

Namestitev

dotnet add package NoPayn

Ali kot lokalna referenca projekta:

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

Hitri začetek

1. Inicializirajte odjemalca

using NoPayn;
using NoPayn.Models;

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

2. Ustvarite plačilo in preusmerite na 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",
});

// Preusmerite stranko
// result.OrderUrl   → HPP (stranka izbere plačilno metodo)
// result.PaymentUrl → neposredna povezava do plačilne metode prve transakcije
// result.Signature  → HMAC-SHA256 za preverjanje
// result.OrderId    → NoPayn UUID naročila

3. Obdelajte 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")
    {
        // Izpolnite naročilo
    }

    return Results.Ok();
});

API referenca

new NoPaynClient(config, httpClient?)

ParameterTipObveznoPrivzeto
ApiKeystringDa—
MerchantIdstringDa—
BaseUrlstringNehttps://api.nopayn.co.uk

Neobvezen HttpClient je mogoče podati kot drugi parameter konstruktorja za obdelavo HTTP po meri ali testiranje.

client.CreateOrderAsync(params): Task<Order>

Ustvari naročilo prek POST /v1/orders/.

ParameterTipObveznoOpis
AmountintjaZnesek v manjši enoti ISO 4217 valute (na primer centi za EUR)
CurrencystringDaKoda ISO 4217 (EUR, GBP, USD, NOK, SEK)
MerchantOrderIdstring?NeVaša interna referenca naročila
Descriptionstring?NeOpis naročila
ReturnUrlstring?NePreusmeritev po uspešnem plačilu
FailureUrlstring?NePreusmeritev ob preklicu/poteku/napaki
WebhookUrlstring?NeAsinhrona obvestila o spremembi statusa
Localestring?NeJezik HPP (en-GB, de-DE, nl-NL itd.)
PaymentMethodsIReadOnlyList<string>?NeFiltriraj metode HPP
ExpirationPeriodstring?NeTrajanje ISO 8601 (PT30M)

Razpoložljive plačilne metode: credit-card, apple-pay, google-pay, vipps-mobilepay

client.GetOrderAsync(orderId): Task<Order>

Pridobi podrobnosti naročila prek GET /v1/orders/{id}/.

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

Izda celotno ali delno vračilo prek POST /v1/orders/{id}/refunds/.

client.GeneratePaymentUrlAsync(params): Task<PaymentUrlResult>

Priročna metoda, ki ustvari naročilo in vrne:

public record PaymentUrlResult(
    string OrderId,        // NoPayn UUID naročila
    string OrderUrl,       // HPP URL
    string? PaymentUrl,    // Neposredni plačilni URL (prva transakcija)
    string Signature,      // HMAC-SHA256 od amount:currency:orderId
    Order Order            // Celoten objekt naročila
);

client.GenerateSignature(amount, currency, orderId): string

Generira HMAC-SHA256 šestnajstiški podpis.

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

Preverjanje HMAC-SHA256 podpisa s konstantnim časom.

client.VerifyWebhookAsync(rawBody): Task<VerifiedWebhook>

Razčleni telo webhook-a, nato pokliče GET /v1/orders/{id}/ za preverjanje dejanskega statusa.

Samostojne HMAC pripomočke

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

Obravnava napak

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
}
IzjemaOpis
NoPaynExceptionOsnovna izjema (omrežje, razčlenjevanje)
ApiExceptionHTTP napaka iz API-ja
WebhookExceptionNeveljaven koristni podatek webhook-a

Statusi naročil

StatusKončni?Opis
newNeNaročilo ustvarjeno
processingNePlačilo v teku
completedDaPlačilo uspešno — dostavite blago
cancelledDaPlačilo preklicano s strani stranke
expiredDaPlačilna povezava je potekla
errorDaTehnična napaka

Najboljše prakse za webhook-e

  1. Vedno preverite prek API-ja — koristni podatki webhook-a vsebujejo samo ID naročila, nikoli statusa. SDK-jev VerifyWebhookAsync() to naredi samodejno.
  2. Vrnite HTTP 200 za potrditev prejema. Katerakoli druga koda sproži do 10 ponovnih poskusov (2 minuti narazen).
  3. Implementirajte rezervno poizvedovanje — za naročila, starejša od 10 minut, ki še niso dosegla končnega statusa, poizvedujte GetOrderAsync() kot varnostno mrežo.
  4. Bodite idempotentni — isti webhook lahko prejmete večkrat.

Testne kartice

Uporabite te kartice v testnem načinu Cost+ (spletno mesto peskovnika):

KarticaŠtevilkaOpombe
Visa (uspeh)4111 1111 1111 1111Katerikoli CVV
Mastercard (uspeh)5544 3300 0003 7Katerikoli CVV
Visa (zavrnjena)4111 1111 1111 1105Zavrnitev
Visa (nezadostna sredstva)4111 1111 1111 1151Nezadostna sredstva

Uporabite katerikoli prihodnji datum veljavnosti in katerokoli 3-mestno CVC kodo.

Predstavitvena aplikacija

Predstavitvena aplikacija na osnovi Docker ASP.NET Core je vključena v GitHub repozitorij za testiranje celotnega plačilnega toka.

Podpora

Potrebujete pomoč? Obrnite se na našo ekipo za podporo na support@costplus.io.

On this page