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șiSystem.Security.Cryptographyintegrate - Ț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
- .NET 8.0 SDK sau mai nou
- Un cont de comerciant Cost+ — dashboard.costplus.io
Instalare
dotnet add package NoPaynSau ca referință de proiect local:
dotnet add reference path/to/src/NoPayn/NoPayn.csprojPornire 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 UUID3. 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?)
| Parametru | Tip | Obligatoriu | Implicit |
|---|---|---|---|
ApiKey | string | Da | — |
MerchantId | string | Da | — |
BaseUrl | string | Nu | https://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/.
| Parametru | Tip | Obligatoriu | Descriere |
|---|---|---|---|
Amount | int | Da | Suma în cea mai mică unitate monetară (cenți) |
Currency | string | Da | Cod ISO 4217 (EUR, GBP, USD, NOK, SEK) |
MerchantOrderId | string? | Nu | Referința dvs. internă de comandă |
Description | string? | Nu | Descrierea comenzii |
ReturnUrl | string? | Nu | Redirecționare după plata reușită |
FailureUrl | string? | Nu | Redirecționare la anulare/expirare/eroare |
WebhookUrl | string? | Nu | Notificări asincrone de schimbare status |
Locale | string? | Nu | Limba HPP (en-GB, de-DE, nl-NL, etc.) |
PaymentMethods | IReadOnlyList<string>? | Nu | Filtrare metode HPP |
ExpirationPeriod | string? | Nu | Durată 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ție | Descriere |
|---|---|
NoPaynException | Excepție de bază (rețea, parsare) |
ApiException | Eroare HTTP de la API |
WebhookException | Payload webhook invalid |
Statusuri comandă
| Status | Final? | Descriere |
|---|---|---|
new | Nu | Comandă creată |
processing | Nu | Plată în curs |
completed | Da | Plată reușită — livrați marfa |
cancelled | Da | Plată anulată de client |
expired | Da | Linkul de plată a expirat |
error | Da | Eroare tehnică |
Bune practici pentru webhook-uri
- 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. - 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ță).
- 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ță. - 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):
| Card | Număr | Note |
|---|---|---|
| Visa (succes) | 4111 1111 1111 1111 | Orice CVV |
| Mastercard (succes) | 5544 3300 0003 7 | Orice CVV |
| Visa (refuzat) | 4111 1111 1111 1105 | Do Not Honor |
| Visa (fonduri insuficiente) | 4111 1111 1111 1151 | Insufficient 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.