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- jaSystem.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
- .NET 8.0 SDK tai uudempi
- Cost+-kauppiastili — dashboard.costplus.io
Asennus
dotnet add package NoPaynTai paikallisena projektiviittauksena:
dotnet add reference path/to/src/NoPayn/NoPayn.csprojPikaopas
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 UUID3. 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?)
| Parametri | Tyyppi | Pakollinen | Oletus |
|---|---|---|---|
ApiKey | string | Kyllä | — |
MerchantId | string | Kyllä | — |
BaseUrl | string | Ei | https://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/.
| Parametri | Tyyppi | Pakollinen | Kuvaus |
|---|---|---|---|
Amount | int | Kyllä | Summa pienimmässä valuuttayksikössä (senteissä) |
Currency | string | Kyllä | ISO 4217 -koodi (EUR, GBP, USD, NOK, SEK) |
MerchantOrderId | string? | Ei | Oma sisäinen tilausviitteesi |
Description | string? | Ei | Tilauksen kuvaus |
ReturnUrl | string? | Ei | Uudelleenohjaus onnistuneen maksun jälkeen |
FailureUrl | string? | Ei | Uudelleenohjaus peruutuksen/vanhenemisen/virheen yhteydessä |
WebhookUrl | string? | Ei | Asynkroniset tilanmuutosilmoitukset |
Locale | string? | Ei | HPP:n kieli (en-GB, de-DE, nl-NL jne.) |
PaymentMethods | IReadOnlyList<string>? | Ei | Suodata HPP:n maksutapoja |
ExpirationPeriod | string? | Ei | ISO 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
}| Poikkeus | Kuvaus |
|---|---|
NoPaynException | Peruspoikkeus (verkko, jäsennys) |
ApiException | HTTP-virhe API:sta |
WebhookException | Virheellinen webhook-data |
Tilausten tilat
| Tila | Lopullinen? | Kuvaus |
|---|---|---|
new | Ei | Tilaus luotu |
processing | Ei | Maksu käynnissä |
completed | Kyllä | Maksu onnistui — toimita tavarat |
cancelled | Kyllä | Asiakas peruutti maksun |
expired | Kyllä | Maksulinkki vanheni |
error | Kyllä | Tekninen virhe |
Webhook-parhaat käytännöt
- Vahvista aina API:n kautta — webhook-data sisältää vain tilauksen tunnisteen, ei koskaan tilaa. SDK:n
VerifyWebhookAsync()tekee tämän automaattisesti. - Palauta HTTP 200 kuittauksena. Mikä tahansa muu koodi käynnistää enintään 10 uudelleenyritystä (2 minuutin välein).
- Toteuta varapolleri — yli 10 minuuttia vanhoille tilauksille, jotka eivät ole saavuttaneet lopullista tilaa, pollaa
GetOrderAsync()turvavarana. - Ole idempotentti — saatat vastaanottaa saman webhookin useita kertoja.
Testikortit
Käytä näitä kortteja Cost+:n testitilassa (sandbox-verkkosivusto):
| Kortti | Numero | Huomautukset |
|---|---|---|
| Visa (onnistunut) | 4111 1111 1111 1111 | Mikä tahansa CVV |
| Mastercard (onnistunut) | 5544 3300 0003 7 | Mikä tahansa CVV |
| Visa (hylätty) | 4111 1111 1111 1105 | Do Not Honor |
| Visa (riittämätön kate) | 4111 1111 1111 1151 | Insufficient 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.