Cost+Docs

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.Json y System.Security.Cryptography integrados
  • 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

Instalacion

dotnet add package NoPayn

O como referencia de proyecto local:

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

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

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

ParametroTipoObligatorioPredeterminado
ApiKeystringSi
MerchantIdstringSi
BaseUrlstringNohttps://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/.

ParametroTipoObligatorioDescripcion
AmountintSiImporte en la unidad monetaria mas pequena (centimos)
CurrencystringSiCodigo ISO 4217 (EUR, GBP, USD, NOK, SEK)
MerchantOrderIdstring?NoTu referencia interna de pedido
Descriptionstring?NoDescripcion del pedido
ReturnUrlstring?NoRedireccion despues de pago exitoso
FailureUrlstring?NoRedireccion en cancelacion/expiracion/error
WebhookUrlstring?NoNotificaciones asincronas de cambio de estado
Localestring?NoIdioma del HPP (en-GB, de-DE, nl-NL, etc.)
PaymentMethodsIReadOnlyList<string>?NoFiltrar metodos del HPP
ExpirationPeriodstring?NoDuracion 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
}
ExcepcionDescripcion
NoPaynExceptionExcepcion base (red, parsing)
ApiExceptionError HTTP de la API
WebhookExceptionPayload de webhook invalido

Estados del pedido

EstadoFinal?Descripcion
newNoPedido creado
processingNoPago en curso
completedSiPago exitoso — entregar los bienes
cancelledSiPago cancelado por el cliente
expiredSiEl enlace de pago expiro
errorSiFallo tecnico

Mejores practicas para webhooks

  1. 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.
  2. Devuelve HTTP 200 para confirmar la recepcion. Cualquier otro codigo activa hasta 10 reintentos (cada 2 minutos).
  3. 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.
  4. Se idempotente — puedes recibir el mismo webhook multiples veces.

Tarjetas de prueba

Usa estas tarjetas en modo de prueba de Cost+ (sitio web sandbox):

TarjetaNumeroNotas
Visa (exito)4111 1111 1111 1111Cualquier CVV
Mastercard (exito)5544 3300 0003 7Cualquier CVV
Visa (rechazada)4111 1111 1111 1105Do Not Honor
Visa (fondos insuficientes)4111 1111 1111 1151Insufficient 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.

On this page