Cost+Docs

C# / .NET

Ametlik C#/.NET SDK Cost+ makselüüsi jaoks

Ametlik C#/.NET SDK Cost+ makselüüsi jaoks. Lihtsustab HPP (hostitud makselehe) ümbersuunamise voogu, HMAC andmete allkirjastamist ja veebihaagi kontrollimist.

Funktsioonid

  • Null sõltuvust — kasutab ainult sisseehitatud System.Text.Json ja System.Security.Cryptography
  • Sihtplatvorm .NET 8.0 C# 12 funktsioonidega (kirjed, failiskoobi nimeruumid, mustrite sobitamine)
  • Nullable viitetüübid lubatud kõikjal
  • HMAC-SHA256 allkirja genereerimine ja konstantse aja kontrollimine
  • Automaatne snake_case/PascalCase vastendamine API ja SDK vahel
  • Veebihaagi parsimine + API-põhine tellimuse kontrollimine
  • Täielikult asünkroonne API pind

Nõuded

Paigaldamine

dotnet add package NoPayn

Või kohaliku projekti viitena:

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

Kiirstart

1. Kliendi initsialiseerimine

using NoPayn;
using NoPayn.Models;

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

2. Makse loomine ja HPP-le suunamine

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. Veebihaagi käsitlemine

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 viide

new NoPaynClient(config, httpClient?)

ParameeterTüüpKohustuslikVaikeväärtus
ApiKeystringJah
MerchantIdstringJah
BaseUrlstringEihttps://api.nopayn.co.uk

Valikulise HttpClient saab edastada teise konstruktori parameetrina kohandatud HTTP käsitluseks või testimiseks.

client.CreateOrderAsync(params): Task<Order>

Loob tellimuse päringuga POST /v1/orders/.

ParameeterTüüpKohustuslikKirjeldus
AmountintJahSumma väikseimas valuutaühikus (sendid)
CurrencystringJahISO 4217 kood (EUR, GBP, USD, NOK, SEK)
MerchantOrderIdstring?EiTeie sisemine tellimuse viide
Descriptionstring?EiTellimuse kirjeldus
ReturnUrlstring?EiÜmbersuunamine pärast edukat makset
FailureUrlstring?EiÜmbersuunamine tühistamise/aegumise/vea korral
WebhookUrlstring?EiAsünkroonsed olekumuutuse teavitused
Localestring?EiHPP keel (en-GB, de-DE, nl-NL jne)
PaymentMethodsIReadOnlyList<string>?EiHPP meetodite filtreerimine
ExpirationPeriodstring?EiISO 8601 kestvus (PT30M)

Saadaolevad makseviisid: credit-card, apple-pay, google-pay, vipps-mobilepay

client.GetOrderAsync(orderId): Task<Order>

Pärib tellimuse üksikasjad päringuga GET /v1/orders/{id}/.

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

Teeb täieliku või osalise tagasimakse päringuga POST /v1/orders/{id}/refunds/.

client.GeneratePaymentUrlAsync(params): Task<PaymentUrlResult>

Abimeetod, mis loob tellimuse ja tagastab:

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

Genereerib HMAC-SHA256 hex allkirja.

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

Konstantse aja HMAC-SHA256 allkirja kontrollimine.

client.VerifyWebhookAsync(rawBody): Task<VerifiedWebhook>

Parsib veebihaagi keha, seejärel kutsub GET /v1/orders/{id}/, et kontrollida tegelikku olekut.

Eraldiseisvad HMAC utiliidid

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

Veakäsitlus

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
}
ErandKirjeldus
NoPaynExceptionBaaserrand (võrk, parsimine)
ApiExceptionHTTP viga API-st
WebhookExceptionVigane veebihaagi andmepakk

Tellimuse olekud

OlekLõplik?Kirjeldus
newEiTellimus loodud
processingEiMakse pooleli
completedJahMakse edukas — tarnige kaup
cancelledJahMakse tühistatud kliendi poolt
expiredJahMakselink aegunud
errorJahTehniline tõrge

Veebihaagi parimad tavad

  1. Kontrollige alati API kaudu — veebihaagi andmed sisaldavad ainult tellimuse ID-d, mitte kunagi olekut. SDK VerifyWebhookAsync() teeb seda automaatselt.
  2. Tagastage HTTP 200 kättesaamise kinnitamiseks. Iga muu kood käivitab kuni 10 korduskatset (2 minuti vahega).
  3. Rakendage varuküsitleja — tellimuste jaoks, mis on vanemad kui 10 minutit ja pole jõudnud lõppolekusse, küsitlege GetOrderAsync() turvavõrguna.
  4. Olge idempotentne — võite sama veebihaagi saada mitu korda.

Testkaardid

Kasutage neid kaarte Cost+ testrežiimis (liivakasti veebileht):

KaartNumberMärkused
Visa (edukas)4111 1111 1111 1111Suvaline CVV
Mastercard (edukas)5544 3300 0003 7Suvaline CVV
Visa (keeldutud)4111 1111 1111 1105Do Not Honor
Visa (ebapiisav saldo)4111 1111 1111 1151Insufficient Funds

Kasutage suvalist tulevast aegumiskuupäeva ja suvalist 3-kohalist CVC-d.

Demorakendus

Dockeri-põhine ASP.NET Core demorakendus on kaasas GitHub hoidlas täieliku maksevoo testimiseks.

Tugi

Vajate abi? Võtke ühendust meie tugimeeskonnaga aadressil support@costplus.io.

On this page