Cost+Docs

C# / .NET

Službeni C#/.NET SDK za Cost+ platni pristupnik

Službeni C#/.NET SDK za Cost+ platni pristupnik. Pojednostavljuje tijek preusmjeravanja na HPP (hosted stranicu za plaćanje), HMAC potpisivanje podataka i verifikaciju webhookova.

Značajke

  • Bez ovisnosti — koristi samo ugrađene System.Text.Json i System.Security.Cryptography
  • Cilja .NET 8.0 s C# 12 značajkama (recordi, file-scoped namespacei, pattern matching)
  • Nullable referentni tipovi omogućeni svugdje
  • HMAC-SHA256 generiranje potpisa i verifikacija konstantnim vremenom
  • Automatsko mapiranje snake_case/PascalCase između API-ja i SDK-a
  • Raščlamba webhookova + verifikacija narudžbe temeljena na API-ju
  • Potpuno asinkrona API površina

Zahtjevi

Instalacija

dotnet add package NoPayn

Ili kao lokalna referenca projekta:

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

Brzi početak

1. Inicijalizirajte klijent

using NoPayn;
using NoPayn.Models;

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

2. Stvorite plaćanje i preusmjerite 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",
});

// 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. Obradite 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 referenca

new NoPaynClient(config, httpClient?)

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

Opcionalni HttpClient može se proslijediti kao drugi parametar konstruktora za prilagođeno HTTP rukovanje ili testiranje.

client.CreateOrderAsync(params): Task<Order>

Stvara narudžbu putem POST /v1/orders/.

ParametarTipObaveznoOpis
AmountintDaIznos u manjoj jedinici ISO 4217 valute (na primjer, centi za EUR)
CurrencystringDaISO 4217 kod (EUR, GBP, USD, NOK, SEK)
MerchantOrderIdstring?NeVaša interna referenca narudžbe
Descriptionstring?NeOpis narudžbe
ReturnUrlstring?NePreusmjeravanje nakon uspješnog plaćanja
FailureUrlstring?NePreusmjeravanje pri poništenju/isteku/grešci
WebhookUrlstring?NeAsinkrone obavijesti o promjeni statusa
Localestring?NeJezik HPP-a (en-GB, de-DE, nl-NL itd.)
PaymentMethodsIReadOnlyList<string>?NeFiltriranje HPP načina
ExpirationPeriodstring?NeISO 8601 trajanje (PT30M)

Dostupni načini plaćanja: credit-card, apple-pay, google-pay, vipps-mobilepay

client.GetOrderAsync(orderId): Task<Order>

Dohvaća detalje narudžbe putem GET /v1/orders/{id}/.

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

Izdaje potpuni ili djelomični povrat putem POST /v1/orders/{id}/refunds/.

client.GeneratePaymentUrlAsync(params): Task<PaymentUrlResult>

Praktična metoda koja stvara narudžbu i vraća:

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

Generira HMAC-SHA256 heksadecimalni potpis.

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

Verifikacija HMAC-SHA256 potpisa konstantnim vremenom.

client.VerifyWebhookAsync(rawBody): Task<VerifiedWebhook>

Raščlanjuje tijelo webhooka, zatim poziva GET /v1/orders/{id}/ za provjeru stvarnog statusa.

Samostalni HMAC alati

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

Rukovanje greškama

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
}
IznimkaOpis
NoPaynExceptionBazna iznimka (mreža, raščlamba)
ApiExceptionHTTP greška iz API-ja
WebhookExceptionNevaljani webhook podaci

Statusi narudžbe

StatusKonačan?Opis
newNeNarudžba stvorena
processingNePlaćanje u tijeku
completedDaPlaćanje uspjelo — isporučite robu
cancelledDaPlaćanje poništeno od strane kupca
expiredDaPoveznica za plaćanje je istekla
errorDaTehnički kvar

Najbolje prakse za webhookove

  1. Uvijek provjerite putem API-ja — webhook podaci sadrže samo ID narudžbe, nikada status. SDK-ov VerifyWebhookAsync() to radi automatski.
  2. Vratite HTTP 200 za potvrdu primitka. Bilo koji drugi kod pokreće do 10 ponovnih pokušaja (svake 2 minute).
  3. Implementirajte rezervno anketiranje — za narudžbe starije od 10 minuta koje nisu dosegle konačni status, anketirajte GetOrderAsync() kao sigurnosnu mrežu.
  4. Budite idempotentni — možete primiti isti webhook više puta.

Testne kartice

Koristite ove kartice u Cost+ testnom načinu (sandbox web stranica):

KarticaBrojNapomene
Visa (uspjeh)4111 1111 1111 1111Bilo koji CVV
Mastercard (uspjeh)5544 3300 0003 7Bilo koji CVV
Visa (odbijena)4111 1111 1111 1105Do Not Honor
Visa (nedovoljna sredstva)4111 1111 1111 1151Insufficient Funds

Koristite bilo koji budući datum isteka i bilo koji 3-znamenkasti CVC.

Demo aplikacija

Docker-bazirana ASP.NET Core demo aplikacija uključena je u GitHub repozitoriju za testiranje potpunog tijeka plaćanja.

Podrška

Trebate pomoć? Obratite se našem timu za podršku na support@costplus.io.

On this page