Cost+Docs

C# / .NET

Opinbert C#/.NET SDK fyrir greiðslugátt Cost+

Opinbert C#/.NET SDK fyrir greiðslugátt Cost+. Poenostavlja tok preusmeritve HPP (gostovane greiðslune strani), HMAC podpisovanje koristnih podatkov og staðfesting webhook-ov.

Eiginleikar

  • Engin dependency — uporablja le vgrajeni System.Text.Json og System.Security.Cryptography
  • Ciljno .NET 8.0 með lastnostmi C# 12 (records, file-scoped namespaces, pattern matching)
  • Nullable reference types omogočeni povsod
  • HMAC-SHA256 býr tilnje podpisov og staðfesting með konstantnim časom
  • Samodejno preslikovanje snake_case/PascalCase med API-jem og SDK-jem
  • Razčlenjevanje webhook-ov + staðfesting pantana á osnovi API-ja
  • V celoti asinhroni API vmesnik

Kröfur

Uppsetning

dotnet add package NoPayn

Ali kot lokalna referenca projekta:

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

Flýtiræsing

1. Frumstilltu biðlarann

using NoPayn;
using NoPayn.Models;

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

2. Ustvarite greiðsla og preusmerite á HPP

var result = await nopayn.GeneratePaymentUrlAsync(new CreateOrderParams
{
    Amount = 1295,              // €12.95 og 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 viðskiptavin
// result.OrderUrl   → HPP (viðskiptavinur izbere greiðslumáta)
// result.PaymentUrl → neposredna povezava do greiðslumátar prve transakcije
// result.Signature  → HMAC-SHA256 til staðfesting
// result.OrderId    → NoPayn UUID pantanir

3. Meðhöndlaðu 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")
    {
        // Uppfylldu pöntunina
    }

    return Results.Ok();
});

API tilvísun

new NoPaynClient(config, httpClient?)

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

Neobvezen HttpClient er mogoef podati kot drugi parameter konstruktorja til obdelavo HTTP eftir meri eða testiranje.

client.CreateOrderAsync(params): Task<Order>

Stofnar pöntun gegnum POST /v1/orders/.

ParameterTipObveznoOpis
AmountintDaZnesek í najmanjši valutni enoti (centi)
CurrencystringDaKoda ISO 4217 (EUR, GBP, USD, NOK, SEK)
MerchantOrderIdstring?NeVaša interna referenca pantanir
Descriptionstring?NeOpis pantanir
ReturnUrlstring?NePreusmeritev eftir uspešnem greiðsluu
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)

Tiltækir greiðslumátar: credit-card, apple-pay, google-pay, vipps-mobilepay

client.GetOrderAsync(orderId): Task<Order>

Sækir upplýsingar pöntunar gegnum GET /v1/orders/{id}/.

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

Gefðu út fulla eða hluta endurgreiðslu gegnum POST /v1/orders/{id}/refunds/.

client.GeneratePaymentUrlAsync(params): Task<PaymentUrlResult>

Þægileg aðferð, ki ustvari pöntun og vrne:

public record PaymentUrlResult(
    string OrderId,        // NoPayn UUID pantanir
    string OrderUrl,       // HPP URL
    string? PaymentUrl,    // Neposredni greiðsluni URL (prva transakcija)
    string Signature,      // HMAC-SHA256 od amount:currency:orderId
    Order Order            // Celoten objekt pantanir
);

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

Býr til HMAC-SHA256 šestnajstiški podpis.

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

Staðfesting HMAC-SHA256 podpisa með konstantnim časom.

client.VerifyWebhookAsync(rawBody): Task<VerifiedWebhook>

Greinir telo webhook-a, nato poklief GET /v1/orders/{id}/ til staðfesting dejanskega statusa.

Sjálfstæð HMAC tól

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

Villum meðhöndlun

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 pantana

StatusKončni?Opis
newNePöntun ustvarjeno
processingNeGreiðsla í teku
completedDaGreiðsla uspešno — dostavite blago
cancelledDaGreiðsla preklicano með strani viðskiptavinar
expiredDaPlačilna povezava er potekla
errorDaTehnična napaka

Bestu venjur fyrir webhook-a

  1. Vedno preverite gegnum API-ja — koristni podatki webhook-a vsebujejo aðeins ID pantanir, nikoli statusa. SDK-jev VerifyWebhookAsync() to naredi samodejno.
  2. Vrnite HTTP 200 til potrditev prejema. Katerakoli druga koda sproži do 10 ponovnih poskusov (2 minuti narazen).
  3. Implementirajte rezervno poizvedovanje — til pantanir, starejša od 10 minut, ki še niso dosegla končnega statusa, poizvedujte GetOrderAsync() kot varnostno mrežo.
  4. Vertu idempotent — isti webhook lahþegar prejmete večkrat.

Prófunarkort

Uporabite te kartice í testnem načinu Cost+ (vefsíðu sandboxa):

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 og katerokoli 3-mestno CVC kodo.

Sýnisforrit

Sýnisforrit á osnovi Docker ASP.NET Core er vključena í GitHub repozitorij til testiranje celotnega greiðslunega toka.

Aðstoð

Þarftu aðstoð? Hafðu samband við þjónustudeild okkar á support@costplus.io.

On this page