Cost+Docs

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.Json un System.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

Instalācija

dotnet add package NoPayn

Vai 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 UUID

3. 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?)

ParametrsTipsObligātsNoklusējums
ApiKeystring
MerchantIdstring
BaseUrlstringhttps://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/.

ParametrsTipsObligātsApraksts
AmountintSumma mazākajā valūtas vienībā (centos)
CurrencystringISO 4217 kods (EUR, GBP, USD, NOK, SEK)
MerchantOrderIdstring?Jūsu iekšējā pasūtījuma atsauce
Descriptionstring?Pasūtījuma apraksts
ReturnUrlstring?Novirzīšana pēc veiksmīga maksājuma
FailureUrlstring?Novirzīšana atcelšanas/termiņa beigšanās/kļūdas gadījumā
WebhookUrlstring?Asinhroniem statusa izmaiņu paziņojumiem
Localestring?HPP valoda (en-GB, de-DE, nl-NL utt.)
PaymentMethodsIReadOnlyList<string>?Filtrēt HPP metodes
ExpirationPeriodstring?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ņēmumsApraksts
NoPaynExceptionBāzes izņēmums (tīkls, parsēšana)
ApiExceptionHTTP kļūda no API
WebhookExceptionNederīgs webhook saturs

Pasūtījumu statusi

StatussGalīgs?Apraksts
newPasūtījums izveidots
processingMaksājums procesā
completedMaksājums veiksmīgs — piegādājiet preci
cancelledMaksājums atcelts klienta
expiredMaksājuma saites termiņš beidzies
errorTehniska kļūme

Webhook labākā prakse

  1. Vienmēr verificējiet caur API — webhook saturs satur tikai pasūtījuma ID, nekad statusu. SDK VerifyWebhookAsync() to dara automātiski.
  2. Atgrieziet HTTP 200, lai apstiprinātu saņemšanu. Jebkurš cits kods izsauc līdz 10 atkārtojumiem (2 minūtes starpā).
  3. 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.
  4. 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):

KarteNumursPiezīmes
Visa (veiksmīgs)4111 1111 1111 1111Jebkurš CVV
Mastercard (veiksmīgs)5544 3300 0003 7Jebkurš CVV
Visa (noraidīts)4111 1111 1111 1105Do Not Honor
Visa (nepietiekami līdzekļi)4111 1111 1111 1151Insufficient 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.

On this page