Cost+Docs

C# / .NET

Επίσημο C#/.NET SDK για την πύλη πληρωμών Cost+

Επίσημο C#/.NET SDK για την πύλη πληρωμών Cost+. Απλοποιεί τη ροή ανακατεύθυνσης HPP (Φιλοξενούμενη Σελίδα Πληρωμής), την υπογραφή HMAC payload και την επαλήθευση webhook.

Χαρακτηριστικά

  • Μηδέν εξαρτήσεις — uses only built-in System.Text.Json and System.Security.Cryptography
  • Targets .NET 8.0 with C# 12 features (records, file-scoped namespaces, pattern matching)
  • Nullable reference types enabled throughout
  • HMAC-SHA256 signature generation and constant-time verification
  • Automatic snake_case/PascalCase mapping between the API and the SDK
  • Webhook parsing + API-based order verification
  • Fully async API surface

Απαιτήσεις

Εγκατάσταση

dotnet add package NoPayn

Ή ως τοπική αναφορά project:

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

Γρήγορη Εκκίνηση

1. Αρχικοποίηση του Client

using NoPayn;
using NoPayn.Models;

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

2. Δημιουργία Πληρωμής και Ανακατεύθυνση στο 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. Διαχείριση του 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

new NoPaynClient(config, httpClient?)

ΠαράμετροςΤύποςΑπαιτούμενηΠροεπιλογή
ApiKeystringΝαι
MerchantIdstringΝαι
BaseUrlstringΌχιhttps://api.nopayn.co.uk

Ένας προαιρετικός HttpClient μπορεί να περαστεί ως δεύτερη παράμετρος κατασκευαστή για προσαρμοσμένη διαχείριση HTTP ή δοκιμές.

client.CreateOrderAsync(params): Task<Order>

Δημιουργεί παραγγελία μέσω POST /v1/orders/.

ΠαράμετροςΤύποςΑπαιτούμενηΠεριγραφή
AmountintΝαιΠοσό στη μικρότερη μονάδα νομίσματος (λεπτά)
CurrencystringΝαιISO 4217 code (EUR, GBP, USD, NOK, SEK)
MerchantOrderIdstring?ΌχιΗ εσωτερική αναφορά παραγγελίας σας
Descriptionstring?ΌχιΠεριγραφή παραγγελίας
ReturnUrlstring?ΌχιΑνακατεύθυνση μετά από επιτυχή πληρωμή
FailureUrlstring?ΌχιΑνακατεύθυνση σε ακύρωση/λήξη/σφάλμα
WebhookUrlstring?ΌχιΑσύγχρονες ειδοποιήσεις αλλαγής κατάστασης
Localestring?ΌχιHPP language (en-GB, de-DE, nl-NL, etc.)
PaymentMethodsIReadOnlyList<string>?ΌχιΦιλτράρισμα μεθόδων HPP
ExpirationPeriodstring?ΌχιISO 8601 duration (PT30M)

Διαθέσιμες μέθοδοι πληρωμής: credit-card, apple-pay, google-pay, vipps-mobilepay

client.GetOrderAsync(orderId): Task<Order>

Ανακτά λεπτομέρειες παραγγελίας μέσω GET /v1/orders/{id}/.

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

Εκδίδει πλήρη ή μερική επιστροφή χρημάτων μέσω POST /v1/orders/{id}/refunds/.

client.GeneratePaymentUrlAsync(params): Task<PaymentUrlResult>

Μέθοδος ευκολίας που δημιουργεί παραγγελία και επιστρέφει:

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.

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

Επαλήθευση σταθερού χρόνου υπογραφής HMAC-SHA256.

client.VerifyWebhookAsync(rawBody): Task<VerifiedWebhook>

Αναλύει το σώμα webhook, στη συνέχεια καλεί GET /v1/orders/{id}/ για επαλήθευση πραγματικής κατάστασης.

Αυτόνομα Εργαλεία HMAC

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

Διαχείριση Σφαλμάτων

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
}
ΕξαίρεσηΠεριγραφή
NoPaynExceptionΒασική εξαίρεση (δίκτυο, ανάλυση)
ApiExceptionΣφάλμα HTTP από το API
WebhookExceptionΜη έγκυρο payload webhook

Καταστάσεις Παραγγελίας

ΚατάστασηΤελική;Περιγραφή
newΌχιΗ παραγγελία δημιουργήθηκε
processingΌχιΠληρωμή σε εξέλιξη
completedΝαιΗ πληρωμή ήταν επιτυχής — παραδώστε τα αγαθά
cancelledΝαιΗ πληρωμή ακυρώθηκε από τον πελάτη
expiredΝαιΟ σύνδεσμος πληρωμής έληξε
errorΝαιΤεχνική αποτυχία

Βέλτιστες Πρακτικές Webhook

  1. Πάντα επαληθεύετε μέσω API — το payload webhook περιέχει μόνο το αναγνωριστικό παραγγελίας, ποτέ την κατάσταση. Η μέθοδος VerifyWebhookAsync() του SDK το κάνει αυτόματα.
  2. Επιστρέψτε HTTP 200 για επιβεβαίωση λήψης. Οποιοσδήποτε άλλος κωδικός ενεργοποιεί έως 10 επαναπροσπάθειες (2 λεπτά μεταξύ τους).
  3. Υλοποιήστε εφεδρικό poller — για παραγγελίες παλαιότερες από 10 λεπτά που δεν έχουν φτάσει σε τελική κατάσταση, κάντε polling GetOrderAsync() ως δίχτυ ασφαλείας.
  4. Να είστε idempotent — μπορεί να λάβετε το ίδιο webhook πολλές φορές.

Δοκιμαστικές Κάρτες

Χρησιμοποιήστε αυτές τις κάρτες στη δοκιμαστική λειτουργία Cost+ (ιστοσελίδα sandbox):

ΚάρταΑριθμόςΣημειώσεις
Visa (επιτυχία)4111 1111 1111 1111Οποιοδήποτε CVV
Mastercard (επιτυχία)5544 3300 0003 7Οποιοδήποτε CVV
Visa (απόρριψη)4111 1111 1111 1105Do Not Honor
Visa (ανεπαρκές υπόλοιπο)4111 1111 1111 1151Insufficient Funds

Χρησιμοποιήστε οποιαδήποτε μελλοντική ημερομηνία λήξης και οποιοδήποτε 3ψήφιο CVC.

Εφαρμογή Επίδειξης

Μια εφαρμογή επίδειξης βασισμένη σε Docker ASP.NET Core περιλαμβάνεται στο GitHub repository για δοκιμή πλήρους ροής πληρωμής.

Υποστήριξη

Χρειάζεστε βοήθεια; Επικοινωνήστε με την ομάδα υποστήριξης στο support@costplus.io.

On this page