Cost+Docs

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 és System.Security.Cryptography modulokat 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

Telepítés

dotnet add package NoPayn

Vagy helyi projekt hivatkozásként:

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

Gyorsindí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 UUID

3. 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éterTípusKötelezőAlapértelmezett
ApiKeystringIgen
MerchantIdstringIgen
BaseUrlstringNemhttps://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éterTípusKötelezőLeírás
AmountintIgenÖsszeg a legkisebb pénznem-egységben (cent)
CurrencystringIgenISO 4217 kód (EUR, GBP, USD, NOK, SEK)
MerchantOrderIdstring?NemAz Ön belső rendelési hivatkozása
Descriptionstring?NemRendelés leírása
ReturnUrlstring?NemÁtirányítás sikeres fizetés után
FailureUrlstring?NemÁtirányítás törlés/lejárat/hiba esetén
WebhookUrlstring?NemAszinkron állapotváltozási értesítések
Localestring?NemHPP nyelv (en-GB, de-DE, nl-NL stb.)
PaymentMethodsIReadOnlyList<string>?NemHPP módok szűrése
ExpirationPeriodstring?NemISO 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ételLeírás
NoPaynExceptionAlap kivétel (hálózat, feldolgozás)
ApiExceptionHTTP hiba az API-tól
WebhookExceptionÉrvénytelen webhook adatcsomag

Rendelés állapotok

ÁllapotVégleges?Leírás
newNemRendelés létrehozva
processingNemFizetés folyamatban
completedIgenFizetés sikeres — szállítsa az árut
cancelledIgenFizetés törölve az ügyfél által
expiredIgenA fizetési link lejárt
errorIgenTechnikai hiba

Webhook bevált gyakorlatok

  1. 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.
  2. 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).
  3. 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.
  4. 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ártyaSzámMegjegyzés
Visa (sikeres)4111 1111 1111 1111Bármely CVV
Mastercard (sikeres)5544 3300 0003 7Bármely CVV
Visa (elutasítva)4111 1111 1111 1105Do Not Honor
Visa (elégtelen fedezet)4111 1111 1111 1151Insufficient 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.

On this page