C# / .NET
Oficiālais C#/.NET SDK Cost+ maksājumu vārtejai
Oficiālais C#/.NET SDK Cost+ maksājumu vārtejai. Vienkāršo HPP (mitinātās maksājuma lapas) novirzīšanas plūsmu, HMAC datu parakstīšanu un webhook verifikāciju.
Funkcijas
- Nulles atkarības — izmanto tikai iebūvētos
System.Text.JsonunSystem.Security.Cryptography - Mērķis .NET 8.0 ar C# 12 funkcijām (records, file-scoped namespaces, pattern matching)
- Nullable atsauču tipi iespējoti visur
- HMAC-SHA256 parakstu ģenerēšana un konstantā laika verifikācija
- Automātiska snake_case/PascalCase kartēšana starp API un SDK
- Webhook parsēšana + API bāzēta pasūtījuma verifikācija
- Pilnībā asinhrona API virsma
Prasības
- .NET 8.0 SDK vai jaunāka versija
- Cost+ tirgotāja konts — dashboard.costplus.io
Instalācija
dotnet add package NoPaynVai kā lokāla projekta atsauce:
dotnet add reference path/to/src/NoPayn/NoPayn.csprojĀtrais sākums
1. Inicializējiet klientu
using NoPayn;
using NoPayn.Models;
var nopayn = new NoPaynClient(new NoPaynConfig(
ApiKey: "your-api-key",
MerchantId: "your-project"
));2. Izveidojiet maksājumu un novirziet uz 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. Apstrādājiet 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 atsauce
new NoPaynClient(config, httpClient?)
| Parametrs | Tips | Obligāts | Noklusējums |
|---|---|---|---|
ApiKey | string | Jā | — |
MerchantId | string | Jā | — |
BaseUrl | string | Nē | https://api.nopayn.co.uk |
Neobligāts HttpClient var tikt padots kā otrais konstruktora parametrs pielāgotai HTTP apstrādei vai testēšanai.
client.CreateOrderAsync(params): Task<Order>
Izveido pasūtījumu caur POST /v1/orders/.
| Parametrs | Tips | Obligāts | Apraksts |
|---|---|---|---|
Amount | int | Jā | Summa mazākajā valūtas vienībā (centos) |
Currency | string | Jā | ISO 4217 kods (EUR, GBP, USD, NOK, SEK) |
MerchantOrderId | string? | Nē | Jūsu iekšējā pasūtījuma atsauce |
Description | string? | Nē | Pasūtījuma apraksts |
ReturnUrl | string? | Nē | Novirzīšana pēc veiksmīga maksājuma |
FailureUrl | string? | Nē | Novirzīšana atcelšanas/termiņa beigšanās/kļūdas gadījumā |
WebhookUrl | string? | Nē | Asinhroniem statusa izmaiņu paziņojumiem |
Locale | string? | Nē | HPP valoda (en-GB, de-DE, nl-NL utt.) |
PaymentMethods | IReadOnlyList<string>? | Nē | Filtrēt HPP metodes |
ExpirationPeriod | string? | Nē | ISO 8601 ilgums (PT30M) |
Pieejamās maksājumu metodes: credit-card, apple-pay, google-pay, vipps-mobilepay
client.GetOrderAsync(orderId): Task<Order>
Iegūst pasūtījuma datus caur GET /v1/orders/{id}/.
client.CreateRefundAsync(orderId, amount, description?): Task<Refund>
Veic pilnu vai daļēju atmaksu caur POST /v1/orders/{id}/refunds/.
client.GeneratePaymentUrlAsync(params): Task<PaymentUrlResult>
Ērtuma metode, kas izveido pasūtījumu un atgriež:
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
Ģenerē HMAC-SHA256 heksadecimālo parakstu.
client.VerifySignature(amount, currency, orderId, signature): bool
Konstantā laika HMAC-SHA256 paraksta verifikācija.
client.VerifyWebhookAsync(rawBody): Task<VerifiedWebhook>
Parsē webhook saturu, tad izsauc GET /v1/orders/{id}/, lai verificētu faktisko statusu.
Atsevišķās HMAC utilītas
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);Kļūdu apstrāde
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
}| Izņēmums | Apraksts |
|---|---|
NoPaynException | Bāzes izņēmums (tīkls, parsēšana) |
ApiException | HTTP kļūda no API |
WebhookException | Nederīgs webhook saturs |
Pasūtījumu statusi
| Statuss | Galīgs? | Apraksts |
|---|---|---|
new | Nē | Pasūtījums izveidots |
processing | Nē | Maksājums procesā |
completed | Jā | Maksājums veiksmīgs — piegādājiet preci |
cancelled | Jā | Maksājums atcelts klienta |
expired | Jā | Maksājuma saites termiņš beidzies |
error | Jā | Tehniska kļūme |
Webhook labākā prakse
- Vienmēr verificējiet caur API — webhook saturs satur tikai pasūtījuma ID, nekad statusu. SDK
VerifyWebhookAsync()to dara automātiski. - Atgrieziet HTTP 200, lai apstiprinātu saņemšanu. Jebkurš cits kods izsauc līdz 10 atkārtojumiem (2 minūtes starpā).
- Ieviesiet rezerves aptaujātāju — pasūtījumiem, kas vecāki par 10 minūtēm un nav sasnieguši galīgo statusu, aptaujājiet
GetOrderAsync()kā drošības tīklu. - Esiet idempotents — jūs varat saņemt vienu un to pašu webhook vairākas reizes.
Testa kartes
Izmantojiet šīs kartes Cost+ testa režīmā (sandbox vietne):
| Karte | Numurs | Piezīmes |
|---|---|---|
| Visa (veiksmīgs) | 4111 1111 1111 1111 | Jebkurš CVV |
| Mastercard (veiksmīgs) | 5544 3300 0003 7 | Jebkurš CVV |
| Visa (noraidīts) | 4111 1111 1111 1105 | Do Not Honor |
| Visa (nepietiekami līdzekļi) | 4111 1111 1111 1151 | Insufficient Funds |
Izmantojiet jebkuru nākotnes derīguma termiņu un jebkuru 3 ciparu CVC.
Demo lietotne
Docker bāzēta ASP.NET Core demo lietotne ir iekļauta GitHub repozitorijā pilnas maksājumu plūsmas testēšanai.
Atbalsts
Nepieciešama palīdzība? Sazinieties ar mūsu atbalsta komandu: support@costplus.io.