C# / .NET
Официално C#/.NET SDK за разплащателния шлюз Cost+
Официално C#/.NET SDK за разплащателния шлюз Cost+. Опростява потока за пренасочване към HPP (хоствана страница за плащане), HMAC подписването на данни и верификацията на уебхукове.
Характеристики
- Нулеви зависимости — използва само вградените
System.Text.JsonиSystem.Security.Cryptography - Целева платформа .NET 8.0 с C# 12 характеристики (records, file-scoped namespaces, pattern matching)
- Nullable reference типове, активирани навсякъде
- HMAC-SHA256 генериране на подписи и верификация с постоянно време
- Автоматично съответствие snake_case/PascalCase между API и SDK
- Анализиране на уебхукове + верификация на поръчки, базирана на API
- Напълно асинхронна API повърхност
Изисквания
- .NET 8.0 SDK или по-нова версия
- Търговски акаунт в Cost+ — dashboard.costplus.io
Инсталация
dotnet add package NoPaynИли като локална референция към проект:
dotnet add reference path/to/src/NoPayn/NoPayn.csprojБързо начало
1. Инициализиране на клиента
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. Обработка на уебхука
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 | да | Сума в ISO 4217 второстепенна единица на валутата (например центове за EUR) |
Currency | string | Да | ISO 4217 код (EUR, GBP, USD, NOK, SEK) |
MerchantOrderId | string? | Не | Ваш вътрешен идентификатор на поръчка |
Description | string? | Не | Описание на поръчката |
ReturnUrl | string? | Не | Пренасочване след успешно плащане |
FailureUrl | string? | Не | Пренасочване при отказ/изтичане/грешка |
WebhookUrl | string? | Не | Асинхронни известия за промяна на статуса |
Locale | string? | Не | Език на HPP (en-GB, de-DE, nl-NL и др.) |
PaymentMethods | IReadOnlyList<string>? | Не | Филтриране на HPP методи |
ExpirationPeriod | string? | Не | ISO 8601 продължителност (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 шестнадесетичен подпис.
client.VerifySignature(amount, currency, orderId, signature): bool
Верификация с постоянно време на HMAC-SHA256 подпис.
client.VerifyWebhookAsync(rawBody): Task<VerifiedWebhook>
Анализира тялото на уебхука, след което извиква 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 | Невалидни данни от уебхук |
Статуси на поръчки
| Статус | Финален? | Описание |
|---|---|---|
new | Не | Поръчката е създадена |
processing | Не | Плащането е в ход |
completed | Да | Плащането е успешно — доставете стоката |
cancelled | Да | Плащането е отменено от клиента |
expired | Да | Линкът за плащане е изтекъл |
error | Да | Техническа грешка |
Добри практики за уебхукове
- Винаги проверявайте чрез API — данните от уебхука съдържат само идентификатора на поръчката, никога статуса.
VerifyWebhookAsync()на SDK-то прави това автоматично. - Връщайте HTTP 200, за да потвърдите получаването. Всеки друг код задейства до 10 повторни опита (през 2 минути).
- Въведете резервен polling — за поръчки, по-стари от 10 минути, които не са достигнали финален статус, правете polling с
GetOrderAsync()като мрежа за безопасност. - Бъдете идемпотентни — може да получите един и същ уебхук многократно.
Тестови карти
Използвайте тези карти в тестов режим на 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 хранилището за тестване на пълния поток на плащане.
Поддръжка
Нуждаете се от помощ? Свържете се с нашия екип за поддръжка на support@costplus.io.