C# / .NET
Hivatalos C#/.NET SDK a Cost+ fizetési átjáróhoz
Hivatalos C#/.NET SDK a Cost+ fizetési átjáróhoz. Egyszerűsíti a HPP (tárolt fizetési oldal) átirányítási folyamatot, a HMAC adatcsomag-aláírást és a webhook ellenőrzést.
Funkciók
- Nulla függőség — csak a beépített
System.Text.JsonésSystem.Security.Cryptographymodulokat használja - .NET 8.0 célzás C# 12 funkciókkal (rekordok, fájlszintű névterek, mintaillesztés)
- Nullable referencia típusok mindenhol engedélyezve
- HMAC-SHA256 aláírás generálás és állandó idejű ellenőrzés
- Automatikus snake_case/PascalCase leképezés az API és az SDK között
- Webhook feldolgozás + API-alapú rendelés ellenőrzés
- Teljesen aszinkron API felület
Követelmények
- .NET 8.0 SDK vagy újabb
- Cost+ kereskedői fiók — dashboard.costplus.io
Telepítés
dotnet add package NoPaynVagy helyi projekt hivatkozásként:
dotnet add reference path/to/src/NoPayn/NoPayn.csprojGyorsindítás
1. A kliens inicializálása
using NoPayn;
using NoPayn.Models;
var nopayn = new NoPaynClient(new NoPaynConfig(
ApiKey: "your-api-key",
MerchantId: "your-project"
));2. Fizetés létrehozása és átirányítás a HPP-re
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. Webhook kezelése
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-referencia
new NoPaynClient(config, httpClient?)
| Paraméter | Típus | Kötelező | Alapértelmezett |
|---|---|---|---|
ApiKey | string | Igen | — |
MerchantId | string | Igen | — |
BaseUrl | string | Nem | https://api.nopayn.co.uk |
Opcionális HttpClient adható meg második konstruktor paraméterként egyéni HTTP kezeléshez vagy teszteléshez.
client.CreateOrderAsync(params): Task<Order>
Rendelést hoz létre a POST /v1/orders/ végponton.
| Paraméter | Típus | Kötelező | Leírás |
|---|---|---|---|
Amount | int | Igen | Összeg a legkisebb pénznem-egységben (cent) |
Currency | string | Igen | ISO 4217 kód (EUR, GBP, USD, NOK, SEK) |
MerchantOrderId | string? | Nem | Az Ön belső rendelési hivatkozása |
Description | string? | Nem | Rendelés leírása |
ReturnUrl | string? | Nem | Átirányítás sikeres fizetés után |
FailureUrl | string? | Nem | Átirányítás törlés/lejárat/hiba esetén |
WebhookUrl | string? | Nem | Aszinkron állapotváltozási értesítések |
Locale | string? | Nem | HPP nyelv (en-GB, de-DE, nl-NL stb.) |
PaymentMethods | IReadOnlyList<string>? | Nem | HPP módok szűrése |
ExpirationPeriod | string? | Nem | ISO 8601 időtartam (PT30M) |
Elérhető fizetési módok: credit-card, apple-pay, google-pay, vipps-mobilepay
client.GetOrderAsync(orderId): Task<Order>
Rendelés részleteinek lekérdezése a GET /v1/orders/{id}/ végponton.
client.CreateRefundAsync(orderId, amount, description?): Task<Refund>
Teljes vagy részleges visszatérítés kiadása a POST /v1/orders/{id}/refunds/ végponton.
client.GeneratePaymentUrlAsync(params): Task<PaymentUrlResult>
Kényelmi metódus, amely rendelést hoz létre és visszaadja:
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
HMAC-SHA256 hex aláírást generál.
client.VerifySignature(amount, currency, orderId, signature): bool
HMAC-SHA256 aláírás állandó idejű ellenőrzése.
client.VerifyWebhookAsync(rawBody): Task<VerifiedWebhook>
Feldolgozza a webhook törzset, majd meghívja a GET /v1/orders/{id}/ végpontot az aktuális állapot ellenőrzéséhez.
Önálló HMAC segédeszközök
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);Hibakezelés
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
}| Kivétel | Leírás |
|---|---|
NoPaynException | Alap kivétel (hálózat, feldolgozás) |
ApiException | HTTP hiba az API-tól |
WebhookException | Érvénytelen webhook adatcsomag |
Rendelés állapotok
| Állapot | Végleges? | Leírás |
|---|---|---|
new | Nem | Rendelés létrehozva |
processing | Nem | Fizetés folyamatban |
completed | Igen | Fizetés sikeres — szállítsa az árut |
cancelled | Igen | Fizetés törölve az ügyfél által |
expired | Igen | A fizetési link lejárt |
error | Igen | Technikai hiba |
Webhook bevált gyakorlatok
- Mindig ellenőrizze az API-n keresztül — a webhook adatcsomag csak a rendelés azonosítóját tartalmazza, soha nem az állapotot. Az SDK
VerifyWebhookAsync()metódusa ezt automatikusan elvégzi. - Válaszoljon HTTP 200-zal a fogadás nyugtázásához. Bármely más kód legfeljebb 10 újrapróbálkozást vált ki (2 percenként).
- Alkalmazzon tartalék lekérdezést — a 10 percnél régebbi, végleges állapotot még el nem ért rendelésekhez kérdezze le a
GetOrderAsync()metódust biztonsági hálóként. - Legyen idempotens — ugyanazt a webhookot többször is megkaphatja.
Tesztkártyák
Használja ezeket a kártyákat Cost+ teszt módban (sandbox weboldal):
| Kártya | Szám | Megjegyzés |
|---|---|---|
| Visa (sikeres) | 4111 1111 1111 1111 | Bármely CVV |
| Mastercard (sikeres) | 5544 3300 0003 7 | Bármely CVV |
| Visa (elutasítva) | 4111 1111 1111 1105 | Do Not Honor |
| Visa (elégtelen fedezet) | 4111 1111 1111 1151 | Insufficient Funds |
Használjon bármely jövőbeli lejárati dátumot és bármely 3 számjegyű CVC-t.
Demo alkalmazás
Egy Docker-alapú ASP.NET Core demo alkalmazás található a GitHub tárolóban a teljes fizetési folyamat teszteléséhez.
Támogatás
Segítségre van szüksége? Forduljon ügyfélszolgálatunkhoz: support@costplus.io.