C# / .NET
Επίσημο C#/.NET SDK για την πύλη πληρωμών Cost+
Επίσημο C#/.NET SDK για την πύλη πληρωμών Cost+. Απλοποιεί τη ροή ανακατεύθυνσης HPP (Φιλοξενούμενη Σελίδα Πληρωμής), την υπογραφή HMAC payload και την επαλήθευση webhook.
Χαρακτηριστικά
- Μηδέν εξαρτήσεις — uses only built-in
System.Text.JsonandSystem.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
Απαιτήσεις
- .NET 8.0 SDK or later
- Λογαριασμός εμπόρου Cost+ — dashboard.costplus.io
Εγκατάσταση
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 UUID3. Διαχείριση του 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?)
| Παράμετρος | Τύπος | Απαιτούμενη | Προεπιλογή |
|---|---|---|---|
ApiKey | string | Ναι | — |
MerchantId | string | Ναι | — |
BaseUrl | string | Όχι | https://api.nopayn.co.uk |
Ένας προαιρετικός HttpClient μπορεί να περαστεί ως δεύτερη παράμετρος κατασκευαστή για προσαρμοσμένη διαχείριση HTTP ή δοκιμές.
client.CreateOrderAsync(params): Task<Order>
Δημιουργεί παραγγελία μέσω POST /v1/orders/.
| Παράμετρος | Τύπος | Απαιτούμενη | Περιγραφή |
|---|---|---|---|
Amount | int | Ναι | Ποσό στη μικρότερη μονάδα νομίσματος (λεπτά) |
Currency | string | Ναι | ISO 4217 code (EUR, GBP, USD, NOK, SEK) |
MerchantOrderId | string? | Όχι | Η εσωτερική αναφορά παραγγελίας σας |
Description | string? | Όχι | Περιγραφή παραγγελίας |
ReturnUrl | string? | Όχι | Ανακατεύθυνση μετά από επιτυχή πληρωμή |
FailureUrl | string? | Όχι | Ανακατεύθυνση σε ακύρωση/λήξη/σφάλμα |
WebhookUrl | string? | Όχι | Ασύγχρονες ειδοποιήσεις αλλαγής κατάστασης |
Locale | string? | Όχι | HPP language (en-GB, de-DE, nl-NL, etc.) |
PaymentMethods | IReadOnlyList<string>? | Όχι | Φιλτράρισμα μεθόδων HPP |
ExpirationPeriod | string? | Όχι | 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
- Πάντα επαληθεύετε μέσω API — το payload webhook περιέχει μόνο το αναγνωριστικό παραγγελίας, ποτέ την κατάσταση. Η μέθοδος
VerifyWebhookAsync()του SDK το κάνει αυτόματα. - Επιστρέψτε HTTP 200 για επιβεβαίωση λήψης. Οποιοσδήποτε άλλος κωδικός ενεργοποιεί έως 10 επαναπροσπάθειες (2 λεπτά μεταξύ τους).
- Υλοποιήστε εφεδρικό poller — για παραγγελίες παλαιότερες από 10 λεπτά που δεν έχουν φτάσει σε τελική κατάσταση, κάντε polling
GetOrderAsync()ως δίχτυ ασφαλείας. - Να είστε idempotent — μπορεί να λάβετε το ίδιο webhook πολλές φορές.
Δοκιμαστικές Κάρτες
Χρησιμοποιήστε αυτές τις κάρτες στη δοκιμαστική λειτουργία Cost+ (ιστοσελίδα sandbox):
| Κάρτα | Αριθμός | Σημειώσεις |
|---|---|---|
| Visa (επιτυχία) | 4111 1111 1111 1111 | Οποιοδήποτε CVV |
| Mastercard (επιτυχία) | 5544 3300 0003 7 | Οποιοδήποτε CVV |
| Visa (απόρριψη) | 4111 1111 1111 1105 | Do Not Honor |
| Visa (ανεπαρκές υπόλοιπο) | 4111 1111 1111 1151 | Insufficient Funds |
Χρησιμοποιήστε οποιαδήποτε μελλοντική ημερομηνία λήξης και οποιοδήποτε 3ψήφιο CVC.
Εφαρμογή Επίδειξης
Μια εφαρμογή επίδειξης βασισμένη σε Docker ASP.NET Core περιλαμβάνεται στο GitHub repository για δοκιμή πλήρους ροής πληρωμής.
Υποστήριξη
Χρειάζεστε βοήθεια; Επικοινωνήστε με την ομάδα υποστήριξης στο support@costplus.io.