C# / .NET
Službeni C#/.NET SDK za Cost+ platni pristupnik
Službeni C#/.NET SDK za Cost+ platni pristupnik. Pojednostavljuje tijek preusmjeravanja na HPP (hosted stranicu za plaćanje), HMAC potpisivanje podataka i verifikaciju webhookova.
Značajke
- Bez ovisnosti — koristi samo ugrađene
System.Text.JsoniSystem.Security.Cryptography - Cilja .NET 8.0 s C# 12 značajkama (recordi, file-scoped namespacei, pattern matching)
- Nullable referentni tipovi omogućeni svugdje
- HMAC-SHA256 generiranje potpisa i verifikacija konstantnim vremenom
- Automatsko mapiranje snake_case/PascalCase između API-ja i SDK-a
- Raščlamba webhookova + verifikacija narudžbe temeljena na API-ju
- Potpuno asinkrona API površina
Zahtjevi
- .NET 8.0 SDK ili noviji
- Cost+ trgovački račun — dashboard.costplus.io
Instalacija
dotnet add package NoPaynIli kao lokalna referenca projekta:
dotnet add reference path/to/src/NoPayn/NoPayn.csprojBrzi početak
1. Inicijalizirajte klijent
using NoPayn;
using NoPayn.Models;
var nopayn = new NoPaynClient(new NoPaynConfig(
ApiKey: "your-api-key",
MerchantId: "your-project"
));2. Stvorite plaćanje i preusmjerite na 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. Obradite 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 referenca
new NoPaynClient(config, httpClient?)
| Parametar | Tip | Obavezno | Zadano |
|---|---|---|---|
ApiKey | string | Da | — |
MerchantId | string | Da | — |
BaseUrl | string | Ne | https://api.nopayn.co.uk |
Opcionalni HttpClient može se proslijediti kao drugi parametar konstruktora za prilagođeno HTTP rukovanje ili testiranje.
client.CreateOrderAsync(params): Task<Order>
Stvara narudžbu putem POST /v1/orders/.
| Parametar | Tip | Obavezno | Opis |
|---|---|---|---|
Amount | int | Da | Iznos u manjoj jedinici ISO 4217 valute (na primjer, centi za EUR) |
Currency | string | Da | ISO 4217 kod (EUR, GBP, USD, NOK, SEK) |
MerchantOrderId | string? | Ne | Vaša interna referenca narudžbe |
Description | string? | Ne | Opis narudžbe |
ReturnUrl | string? | Ne | Preusmjeravanje nakon uspješnog plaćanja |
FailureUrl | string? | Ne | Preusmjeravanje pri poništenju/isteku/grešci |
WebhookUrl | string? | Ne | Asinkrone obavijesti o promjeni statusa |
Locale | string? | Ne | Jezik HPP-a (en-GB, de-DE, nl-NL itd.) |
PaymentMethods | IReadOnlyList<string>? | Ne | Filtriranje HPP načina |
ExpirationPeriod | string? | Ne | ISO 8601 trajanje (PT30M) |
Dostupni načini plaćanja: credit-card, apple-pay, google-pay, vipps-mobilepay
client.GetOrderAsync(orderId): Task<Order>
Dohvaća detalje narudžbe putem GET /v1/orders/{id}/.
client.CreateRefundAsync(orderId, amount, description?): Task<Refund>
Izdaje potpuni ili djelomični povrat putem POST /v1/orders/{id}/refunds/.
client.GeneratePaymentUrlAsync(params): Task<PaymentUrlResult>
Praktična metoda koja stvara narudžbu i vraća:
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
Generira HMAC-SHA256 heksadecimalni potpis.
client.VerifySignature(amount, currency, orderId, signature): bool
Verifikacija HMAC-SHA256 potpisa konstantnim vremenom.
client.VerifyWebhookAsync(rawBody): Task<VerifiedWebhook>
Raščlanjuje tijelo webhooka, zatim poziva GET /v1/orders/{id}/ za provjeru stvarnog statusa.
Samostalni HMAC alati
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);Rukovanje greškama
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
}| Iznimka | Opis |
|---|---|
NoPaynException | Bazna iznimka (mreža, raščlamba) |
ApiException | HTTP greška iz API-ja |
WebhookException | Nevaljani webhook podaci |
Statusi narudžbe
| Status | Konačan? | Opis |
|---|---|---|
new | Ne | Narudžba stvorena |
processing | Ne | Plaćanje u tijeku |
completed | Da | Plaćanje uspjelo — isporučite robu |
cancelled | Da | Plaćanje poništeno od strane kupca |
expired | Da | Poveznica za plaćanje je istekla |
error | Da | Tehnički kvar |
Najbolje prakse za webhookove
- Uvijek provjerite putem API-ja — webhook podaci sadrže samo ID narudžbe, nikada status. SDK-ov
VerifyWebhookAsync()to radi automatski. - Vratite HTTP 200 za potvrdu primitka. Bilo koji drugi kod pokreće do 10 ponovnih pokušaja (svake 2 minute).
- Implementirajte rezervno anketiranje — za narudžbe starije od 10 minuta koje nisu dosegle konačni status, anketirajte
GetOrderAsync()kao sigurnosnu mrežu. - Budite idempotentni — možete primiti isti webhook više puta.
Testne kartice
Koristite ove kartice u Cost+ testnom načinu (sandbox web stranica):
| Kartica | Broj | Napomene |
|---|---|---|
| Visa (uspjeh) | 4111 1111 1111 1111 | Bilo koji CVV |
| Mastercard (uspjeh) | 5544 3300 0003 7 | Bilo koji CVV |
| Visa (odbijena) | 4111 1111 1111 1105 | Do Not Honor |
| Visa (nedovoljna sredstva) | 4111 1111 1111 1151 | Insufficient Funds |
Koristite bilo koji budući datum isteka i bilo koji 3-znamenkasti CVC.
Demo aplikacija
Docker-bazirana ASP.NET Core demo aplikacija uključena je u GitHub repozitoriju za testiranje potpunog tijeka plaćanja.
Podrška
Trebate pomoć? Obratite se našem timu za podršku na support@costplus.io.