Cost+Docs

C# / .NET

SDK oifigiúil C#/.NET do gheata íocaíochta Cost+

SDK oifigiúil C#/.NET do gheata íocaíochta Cost+. Simpliú an tsreabha atreoraithe HPP (Leathanach Íocaíochta Óstáilte), síniú sonraí HMAC, agus fíorú webhook.

Gnéithe

  • Nialas spleáchais -- ní úsáideann sé ach System.Text.Json agus System.Security.Cryptography ionsuite
  • Dírithe ar .NET 8.0 le gnéithe C# 12 (taifid, ainmspásanna comhadscóipe, meaitseáil phatrún)
  • Cineálacha tagartha neamh-nialasach cumasaithe ar fud
  • Giniúint sínithe HMAC-SHA256 agus fíorú ama-leanúnaigh
  • Mapáil uathoibríoch snake_case/PascalCase idir an API agus an SDK
  • Parsáil webhook + fíorú ordaithe bunaithe ar API
  • Dromchla API go hiomlán asincrónach

Riachtanais

Suiteáil

dotnet add package NoPayn

Nó mar thagairt tionscadail áitiúil:

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

Mearthosnú

1. Túsaigh an Cliant

using NoPayn;
using NoPayn.Models;

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

2. Cruthaigh Íocaíocht agus Atreorófar chuig an 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. Láimhseáil an 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();
});

Tagairt API

new NoPaynClient(config, httpClient?)

ParaiméadarCineálRiachtanachRéamhshocrú
ApiKeystringTá--
MerchantIdstringTá--
BaseUrlstringNílhttps://api.nopayn.co.uk

Is féidir HttpClient roghnach a sheoladh mar an dara paraiméadar cruthaitheora le haghaidh láimhseála HTTP saincheaptha nó tástála.

client.CreateOrderAsync(params): Task<Order>

Cruthaíonn ordú tríd an POST /v1/orders/.

ParaiméadarCineálRiachtanachCur Síos
AmountintTáMéid i mionaonad ISO 4217 an airgeadra (mar shampla, cent le haghaidh EUR)
CurrencystringTáCód ISO 4217 (EUR, GBP, USD, NOK, SEK)
MerchantOrderIdstring?NílDo thagairt inmheánach ordaithe
Descriptionstring?NílCur síos ar an ordú
ReturnUrlstring?NílAtreorú tar éis íocaíochta rathúla
FailureUrlstring?NílAtreorú ar cheallú/éag/earráid
WebhookUrlstring?NílFógraí athraithe stádais asincrónach
Localestring?NílTeanga HPP (en-GB, de-DE, nl-NL, srl.)
PaymentMethodsIReadOnlyList<string>?NílScag modhanna HPP
ExpirationPeriodstring?NílFad ISO 8601 (PT30M)

Modhanna íocaíochta ar fáil: credit-card, apple-pay, google-pay, vipps-mobilepay

client.GetOrderAsync(orderId): Task<Order>

Faigheann sonraí ordaithe tríd an GET /v1/orders/{id}/.

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

Eisíonn aisíocaíocht iomlán nó pháirteach tríd an POST /v1/orders/{id}/refunds/.

client.GeneratePaymentUrlAsync(params): Task<PaymentUrlResult>

Modh áise a chruthaíonn ordú agus a sheolann ar ais:

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

Gineann síniú HMAC-SHA256 hex.

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

Fíorú ama-leanúnaigh ar shíniú HMAC-SHA256.

client.VerifyWebhookAsync(rawBody): Task<VerifiedWebhook>

Parsáileann corp an webhook, ansin glaonn GET /v1/orders/{id}/ chun an stádas iarbhír a fhíorú.

Fóntais HMAC Neamhspleácha

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

Láimhseáil Earráidí

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
}
EisceachtCur Síos
NoPaynExceptionBunearráid (líonra, parsáil)
ApiExceptionEarráid HTTP ón API
WebhookExceptionSonraí webhook neamhbhailí

Stádais Ordaithe

StádasDeiridh?Cur Síos
newNílOrdú cruthaithe
processingNílÍocaíocht ar siúl
completedTáD'éirigh leis an íocaíocht -- seachaid na hearraí
cancelledTáCheal an custaiméir an íocaíocht
expiredTáD'éag an nasc íocaíochta
errorTáTeip theicniúil

Dea-Chleachtais Webhook

  1. Fíoraigh tríd an API i gcónaí -- ní bhíonn ach aitheantas an ordaithe sa sonraí webhook, ní an stádas riamh. Déanann VerifyWebhookAsync() an SDK é seo go huathoibríoch.
  2. Seol HTTP 200 ar ais chun fáiltiú a admháil. Spreagann aon chód eile suas le 10 n-atriail (2 nóiméad eatarthu).
  3. Cuir cúltaca pólaí i bhfeidhm -- d'orduithe atá níos sine ná 10 nóiméad nach bhfuil stádas deiridh bainte amach acu, pólail GetOrderAsync() mar líontán sábháilteachta.
  4. Bí idéimpotent -- d'fhéadfá an webhook céanna a fháil arís is arís eile.

Cártaí Tástála

Úsáid na cártaí seo i mód tástála Cost+ (suíomh gréasáin gaineamhchláir):

CártaUimhirNótaí
Visa (rath)4111 1111 1111 1111Aon CVV
Mastercard (rath)5544 3300 0003 7Aon CVV
Visa (diúltaithe)4111 1111 1111 1105Do Not Honor
Visa (cistí neamhleor)4111 1111 1111 1151Insufficient Funds

Úsáid aon dáta éaga amach anseo agus aon CVC 3 dhigit.

Aip Thaispeána

Tá aip thaispeána Docker-bhunaithe ASP.NET Core san áireamh sa stór GitHub chun an sreabhadh íocaíochta iomlán a thástáil.

Tacaíocht

Cabhair ag teastáil? Déan teagmháil lenár bhfoireann tacaíochta ag support@costplus.io.

On this page