Cost+Docs

C# / .NET

Virallinen C#/.NET SDK Cost+-maksuportille

Virallinen C#/.NET SDK Cost+-maksuportille. Yksinkertaistaa HPP (isännöidyn maksusivun) uudelleenohjausta, HMAC-allekirjoitusta ja webhook-vahvistusta.

Ominaisuudet

  • Nolla riippuvuutta — käyttää vain sisäänrakennettuja System.Text.Json- ja System.Security.Cryptography-moduuleja
  • Kohdistaa .NET 8.0:aan C# 12 -ominaisuuksilla (recordit, tiedostolaajuiset nimiavaruudet, hahmontunnistus)
  • Nullable-viitetyypit käytössä kauttaaltaan
  • HMAC-SHA256-allekirjoituksen luonti ja vakioaikainen vahvistus
  • Automaattinen snake_case/PascalCase-muunnos API:n ja SDK:n välillä
  • Webhook-jäsennys + API-pohjainen tilauksen vahvistus
  • Täysin asynkroninen API-pinta

Vaatimukset

Asennus

dotnet add package NoPayn

Tai paikallisena projektiviittauksena:

dotnet add reference path/to/src/NoPayn/NoPayn.csproj

Pikaopas

1. Alusta asiakas

using NoPayn;
using NoPayn.Models;

var nopayn = new NoPaynClient(new NoPaynConfig(
    ApiKey: "your-api-key",
    MerchantId: "your-project"
));

2. Luo maksu ja ohjaa HPP:hen

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. Käsittele 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-viite

new NoPaynClient(config, httpClient?)

ParametriTyyppiPakollinenOletus
ApiKeystringKyllä
MerchantIdstringKyllä
BaseUrlstringEihttps://api.nopayn.co.uk

Valinnainen HttpClient voidaan antaa toisena konstruktoriparametrina mukautettua HTTP-käsittelyä tai testausta varten.

client.CreateOrderAsync(params): Task<Order>

Luo tilauksen kutsulla POST /v1/orders/.

ParametriTyyppiPakollinenKuvaus
AmountintKylläSumma pienimmässä valuuttayksikössä (senteissä)
CurrencystringKylläISO 4217 -koodi (EUR, GBP, USD, NOK, SEK)
MerchantOrderIdstring?EiOma sisäinen tilausviitteesi
Descriptionstring?EiTilauksen kuvaus
ReturnUrlstring?EiUudelleenohjaus onnistuneen maksun jälkeen
FailureUrlstring?EiUudelleenohjaus peruutuksen/vanhenemisen/virheen yhteydessä
WebhookUrlstring?EiAsynkroniset tilanmuutosilmoitukset
Localestring?EiHPP:n kieli (en-GB, de-DE, nl-NL jne.)
PaymentMethodsIReadOnlyList<string>?EiSuodata HPP:n maksutapoja
ExpirationPeriodstring?EiISO 8601 -kesto (PT30M)

Käytettävissä olevat maksutavat: credit-card, apple-pay, google-pay, vipps-mobilepay

client.GetOrderAsync(orderId): Task<Order>

Hakee tilauksen tiedot kutsulla GET /v1/orders/{id}/.

client.CreateRefundAsync(orderId, amount, description?): Task<Refund>

Tekee täyden tai osittaisen palautuksen kutsulla POST /v1/orders/{id}/refunds/.

client.GeneratePaymentUrlAsync(params): Task<PaymentUrlResult>

Apumetodi, joka luo tilauksen ja palauttaa:

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

Luo HMAC-SHA256 hex-allekirjoituksen.

client.VerifySignature(amount, currency, orderId, signature): bool

Vakioaikainen HMAC-SHA256-allekirjoituksen vahvistus.

client.VerifyWebhookAsync(rawBody): Task<VerifiedWebhook>

Jäsentää webhook-rungon ja kutsuu sitten GET /v1/orders/{id}/ varmistaakseen todellisen tilan.

Erilliset HMAC-apufunktiot

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);

Virheenkäsittely

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
}
PoikkeusKuvaus
NoPaynExceptionPeruspoikkeus (verkko, jäsennys)
ApiExceptionHTTP-virhe API:sta
WebhookExceptionVirheellinen webhook-data

Tilausten tilat

TilaLopullinen?Kuvaus
newEiTilaus luotu
processingEiMaksu käynnissä
completedKylläMaksu onnistui — toimita tavarat
cancelledKylläAsiakas peruutti maksun
expiredKylläMaksulinkki vanheni
errorKylläTekninen virhe

Webhook-parhaat käytännöt

  1. Vahvista aina API:n kautta — webhook-data sisältää vain tilauksen tunnisteen, ei koskaan tilaa. SDK:n VerifyWebhookAsync() tekee tämän automaattisesti.
  2. Palauta HTTP 200 kuittauksena. Mikä tahansa muu koodi käynnistää enintään 10 uudelleenyritystä (2 minuutin välein).
  3. Toteuta varapolleri — yli 10 minuuttia vanhoille tilauksille, jotka eivät ole saavuttaneet lopullista tilaa, pollaa GetOrderAsync() turvavarana.
  4. Ole idempotentti — saatat vastaanottaa saman webhookin useita kertoja.

Testikortit

Käytä näitä kortteja Cost+:n testitilassa (sandbox-verkkosivusto):

KorttiNumeroHuomautukset
Visa (onnistunut)4111 1111 1111 1111Mikä tahansa CVV
Mastercard (onnistunut)5544 3300 0003 7Mikä tahansa CVV
Visa (hylätty)4111 1111 1111 1105Do Not Honor
Visa (riittämätön kate)4111 1111 1111 1151Insufficient Funds

Käytä mitä tahansa tulevaa voimassaolopäivää ja mitä tahansa 3-numeroista CVC:tä.

Demosovellus

Docker-pohjainen ASP.NET Core -demosovellus sisältyy GitHub-tietovarastoon täyden maksukulun testaamiseksi.

Tuki

Tarvitsetko apua? Ota yhteyttä tukitiimiimme osoitteessa support@costplus.io.

On this page