Cost+Docs

C# / .NET

SDK oficial C#/.NET pentru gateway-ul de plăți Cost+

SDK oficial C#/.NET pentru gateway-ul de plăți Cost+. Simplifică fluxul de redirecționare HPP (pagina de plată găzduită), semnarea HMAC a payload-ului și verificarea webhook-urilor.

Funcționalități

  • Zero dependențe — folosește doar System.Text.Json și System.Security.Cryptography integrate
  • Țintește .NET 8.0 cu funcționalități C# 12 (records, file-scoped namespaces, pattern matching)
  • Tipuri referință nullable activate peste tot
  • Generare semnătură HMAC-SHA256 și verificare cu timp constant
  • Mapare automată snake_case/PascalCase între API și SDK
  • Parsare webhook + verificare comenzi bazată pe API
  • Suprafață API complet asincronă

Cerințe

Instalare

dotnet add package NoPayn

Sau ca referință de proiect local:

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

Pornire rapidă

1. Inițializați clientul

using NoPayn;
using NoPayn.Models;

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

2. Creați o plată și redirecționați către 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. Gestionați webhook-ul

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

Referință API

new NoPaynClient(config, httpClient?)

ParametruTipObligatoriuImplicit
ApiKeystringDa
MerchantIdstringDa
BaseUrlstringNuhttps://api.nopayn.co.uk

Un HttpClient opțional poate fi transmis ca al doilea parametru de constructor pentru gestionare HTTP personalizată sau testare.

client.CreateOrderAsync(params): Task<Order>

Creează o comandă prin POST /v1/orders/.

ParametruTipObligatoriuDescriere
AmountintDaSuma în cea mai mică unitate monetară (cenți)
CurrencystringDaCod ISO 4217 (EUR, GBP, USD, NOK, SEK)
MerchantOrderIdstring?NuReferința dvs. internă de comandă
Descriptionstring?NuDescrierea comenzii
ReturnUrlstring?NuRedirecționare după plata reușită
FailureUrlstring?NuRedirecționare la anulare/expirare/eroare
WebhookUrlstring?NuNotificări asincrone de schimbare status
Localestring?NuLimba HPP (en-GB, de-DE, nl-NL, etc.)
PaymentMethodsIReadOnlyList<string>?NuFiltrare metode HPP
ExpirationPeriodstring?NuDurată ISO 8601 (PT30M)

Metode de plată disponibile: credit-card, apple-pay, google-pay, vipps-mobilepay

client.GetOrderAsync(orderId): Task<Order>

Preia detaliile comenzii prin GET /v1/orders/{id}/.

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

Emite o rambursare totală sau parțială prin POST /v1/orders/{id}/refunds/.

client.GeneratePaymentUrlAsync(params): Task<PaymentUrlResult>

Metodă de convenință care creează o comandă și returnează:

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

Generează o semnătură hex HMAC-SHA256.

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

Verificare cu timp constant a unei semnături HMAC-SHA256.

client.VerifyWebhookAsync(rawBody): Task<VerifiedWebhook>

Parsează corpul webhook-ului, apoi apelează GET /v1/orders/{id}/ pentru a verifica statusul real.

Utilitare HMAC independente

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

Gestionarea erorilor

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
}
ExcepțieDescriere
NoPaynExceptionExcepție de bază (rețea, parsare)
ApiExceptionEroare HTTP de la API
WebhookExceptionPayload webhook invalid

Statusuri comandă

StatusFinal?Descriere
newNuComandă creată
processingNuPlată în curs
completedDaPlată reușită — livrați marfa
cancelledDaPlată anulată de client
expiredDaLinkul de plată a expirat
errorDaEroare tehnică

Bune practici pentru webhook-uri

  1. Verificați întotdeauna prin API — payload-ul webhook conține doar ID-ul comenzii, niciodată statusul. Metoda VerifyWebhookAsync() a SDK-ului face acest lucru automat.
  2. Returnați HTTP 200 pentru a confirma recepția. Orice alt cod declanșează până la 10 reîncercări (la 2 minute distanță).
  3. Implementați un poller de rezervă — pentru comenzile mai vechi de 10 minute care nu au ajuns la un status final, interogați GetOrderAsync() ca rețea de siguranță.
  4. Fiți idempotent — puteți primi același webhook de mai multe ori.

Carduri de test

Folosiți aceste carduri în modul de test Cost+ (site web sandbox):

CardNumărNote
Visa (succes)4111 1111 1111 1111Orice CVV
Mastercard (succes)5544 3300 0003 7Orice CVV
Visa (refuzat)4111 1111 1111 1105Do Not Honor
Visa (fonduri insuficiente)4111 1111 1111 1151Insufficient Funds

Folosiți orice dată de expirare viitoare și orice CVC de 3 cifre.

Aplicație demo

O aplicație demo ASP.NET Core bazată pe Docker este inclusă în depozitul GitHub pentru testarea fluxului complet de plată.

Suport

Aveți nevoie de ajutor? Contactați echipa noastră de suport la support@costplus.io.

On this page