C# / .NET
SDK oficial de C#/.NET para la pasarela de pago Cost+
SDK oficial de C#/.NET para la pasarela de pago Cost+. Simplifica el flujo de redireccion HPP (pagina de pago alojada), la firma de payloads HMAC y la verificacion de webhooks.
Caracteristicas
- Sin dependencias — usa solo
System.Text.JsonySystem.Security.Cryptographyintegrados - Compatible con .NET 8.0 con caracteristicas de C# 12 (records, file-scoped namespaces, pattern matching)
- Tipos de referencia nullable habilitados
- Generacion de firma HMAC-SHA256 y verificacion en tiempo constante
- Mapeo automatico de snake_case/PascalCase entre la API y el SDK
- Analisis de webhooks + verificacion de pedidos basada en API
- Superficie de API completamente asincrona
Requisitos
- .NET 8.0 SDK o posterior
- Una cuenta de comerciante Cost+ — dashboard.costplus.io
Instalacion
dotnet add package NoPaynO como referencia de proyecto local:
dotnet add reference path/to/src/NoPayn/NoPayn.csprojInicio rapido
1. Inicializar el cliente
using NoPayn;
using NoPayn.Models;
var nopayn = new NoPaynClient(new NoPaynConfig(
ApiKey: "your-api-key",
MerchantId: "your-project"
));2. Crear un pago y redirigir al 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. Gestionar el 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();
});Referencia de la API
new NoPaynClient(config, httpClient?)
| Parametro | Tipo | Obligatorio | Predeterminado |
|---|---|---|---|
ApiKey | string | Si | — |
MerchantId | string | Si | — |
BaseUrl | string | No | https://api.nopayn.co.uk |
Se puede pasar un HttpClient opcional como segundo parametro del constructor para manejo HTTP personalizado o pruebas.
client.CreateOrderAsync(params): Task<Order>
Crea un pedido via POST /v1/orders/.
| Parametro | Tipo | Obligatorio | Descripcion |
|---|---|---|---|
Amount | int | Si | Importe en la unidad monetaria mas pequena (centimos) |
Currency | string | Si | Codigo ISO 4217 (EUR, GBP, USD, NOK, SEK) |
MerchantOrderId | string? | No | Tu referencia interna de pedido |
Description | string? | No | Descripcion del pedido |
ReturnUrl | string? | No | Redireccion despues de pago exitoso |
FailureUrl | string? | No | Redireccion en cancelacion/expiracion/error |
WebhookUrl | string? | No | Notificaciones asincronas de cambio de estado |
Locale | string? | No | Idioma del HPP (en-GB, de-DE, nl-NL, etc.) |
PaymentMethods | IReadOnlyList<string>? | No | Filtrar metodos del HPP |
ExpirationPeriod | string? | No | Duracion ISO 8601 (PT30M) |
Metodos de pago disponibles: credit-card, apple-pay, google-pay, vipps-mobilepay
client.GetOrderAsync(orderId): Task<Order>
Obtiene los detalles del pedido via GET /v1/orders/{id}/.
client.CreateRefundAsync(orderId, amount, description?): Task<Refund>
Emite un reembolso total o parcial via POST /v1/orders/{id}/refunds/.
client.GeneratePaymentUrlAsync(params): Task<PaymentUrlResult>
Metodo de conveniencia que crea un pedido y devuelve:
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
Genera una firma HMAC-SHA256 en hexadecimal.
client.VerifySignature(amount, currency, orderId, signature): bool
Verificacion en tiempo constante de una firma HMAC-SHA256.
client.VerifyWebhookAsync(rawBody): Task<VerifiedWebhook>
Analiza el cuerpo del webhook, luego llama a GET /v1/orders/{id}/ para verificar el estado real.
Utilidades HMAC independientes
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);Gestion de errores
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
}| Excepcion | Descripcion |
|---|---|
NoPaynException | Excepcion base (red, parsing) |
ApiException | Error HTTP de la API |
WebhookException | Payload de webhook invalido |
Estados del pedido
| Estado | Final? | Descripcion |
|---|---|---|
new | No | Pedido creado |
processing | No | Pago en curso |
completed | Si | Pago exitoso — entregar los bienes |
cancelled | Si | Pago cancelado por el cliente |
expired | Si | El enlace de pago expiro |
error | Si | Fallo tecnico |
Mejores practicas para webhooks
- Verifica siempre via la API — el payload del webhook solo contiene el ID del pedido, nunca el estado. El metodo
VerifyWebhookAsync()del SDK hace esto automaticamente. - Devuelve HTTP 200 para confirmar la recepcion. Cualquier otro codigo activa hasta 10 reintentos (cada 2 minutos).
- Implementa un poller de respaldo — para pedidos de mas de 10 minutos que no hayan alcanzado un estado final, consulta
GetOrderAsync()como red de seguridad. - Se idempotente — puedes recibir el mismo webhook multiples veces.
Tarjetas de prueba
Usa estas tarjetas en modo de prueba de Cost+ (sitio web sandbox):
| Tarjeta | Numero | Notas |
|---|---|---|
| Visa (exito) | 4111 1111 1111 1111 | Cualquier CVV |
| Mastercard (exito) | 5544 3300 0003 7 | Cualquier CVV |
| Visa (rechazada) | 4111 1111 1111 1105 | Do Not Honor |
| Visa (fondos insuficientes) | 4111 1111 1111 1151 | Insufficient Funds |
Usa cualquier fecha de caducidad futura y cualquier CVC de 3 digitos.
App de demostracion
Se incluye una app de demostracion basada en Docker con ASP.NET Core en el repositorio de GitHub para probar el flujo completo de pago.
Soporte
Necesitas ayuda? Contacta a nuestro equipo de soporte en support@costplus.io.