Cost+Docs

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 UUID

3. Обработка на уебхука

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даСума в ISO 4217 второстепенна единица на валутата (например центове за EUR)
CurrencystringДаISO 4217 код (EUR, GBP, USD, NOK, SEK)
MerchantOrderIdstring?НеВаш вътрешен идентификатор на поръчка
Descriptionstring?НеОписание на поръчката
ReturnUrlstring?НеПренасочване след успешно плащане
FailureUrlstring?НеПренасочване при отказ/изтичане/грешка
WebhookUrlstring?НеАсинхронни известия за промяна на статуса
Localestring?НеЕзик на HPP (en-GB, de-DE, nl-NL и др.)
PaymentMethodsIReadOnlyList<string>?НеФилтриране на HPP методи
ExpirationPeriodstring?Не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Базово изключение (мрежа, анализиране)
ApiExceptionHTTP грешка от API-то
WebhookExceptionНевалидни данни от уебхук

Статуси на поръчки

СтатусФинален?Описание
newНеПоръчката е създадена
processingНеПлащането е в ход
completedДаПлащането е успешно — доставете стоката
cancelledДаПлащането е отменено от клиента
expiredДаЛинкът за плащане е изтекъл
errorДаТехническа грешка

Добри практики за уебхукове

  1. Винаги проверявайте чрез API — данните от уебхука съдържат само идентификатора на поръчката, никога статуса. VerifyWebhookAsync() на SDK-то прави това автоматично.
  2. Връщайте HTTP 200, за да потвърдите получаването. Всеки друг код задейства до 10 повторни опита (през 2 минути).
  3. Въведете резервен polling — за поръчки, по-стари от 10 минути, които не са достигнали финален статус, правете polling с GetOrderAsync() като мрежа за безопасност.
  4. Бъдете идемпотентни — може да получите един и същ уебхук многократно.

Тестови карти

Използвайте тези карти в тестов режим на 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 хранилището за тестване на пълния поток на плащане.

Поддръжка

Нуждаете се от помощ? Свържете се с нашия екип за поддръжка на support@costplus.io.

On this page