Cost+Docs

C# / .NET

SDK oficial C#/.NET para o gateway de pagamento Cost+

SDK oficial C#/.NET para o gateway de pagamento Cost+. Simplifica o fluxo de redirecionamento HPP (Página de Pagamento Alojada), assinatura de payloads HMAC e verificação de webhooks.

Funcionalidades

  • Zero dependências — utiliza apenas System.Text.Json e System.Security.Cryptography nativos
  • Alvo .NET 8.0 com funcionalidades C# 12 (records, file-scoped namespaces, pattern matching)
  • Tipos de referência anuláveis ativados em todo o código
  • Geração de assinaturas HMAC-SHA256 e verificação em tempo constante
  • Mapeamento automático snake_case/PascalCase entre a API e o SDK
  • Análise de webhooks + verificação de encomendas baseada na API
  • Superfície da API totalmente assíncrona

Requisitos

Instalação

dotnet add package NoPayn

Ou como referência de projeto local:

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

Início Rápido

1. Inicializar o Cliente

using NoPayn;
using NoPayn.Models;

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

2. Criar um Pagamento e Redirecionar para o 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. Tratar o 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();
});

Referência da API

new NoPaynClient(config, httpClient?)

ParâmetroTipoObrigatórioPredefinição
ApiKeystringSim
MerchantIdstringSim
BaseUrlstringNãohttps://api.nopayn.co.uk

Um HttpClient opcional pode ser passado como segundo parâmetro do construtor para tratamento HTTP personalizado ou testes.

client.CreateOrderAsync(params): Task<Order>

Cria uma encomenda via POST /v1/orders/.

ParâmetroTipoObrigatórioDescrição
AmountintSimMontante na menor unidade monetária (cêntimos)
CurrencystringSimCódigo ISO 4217 (EUR, GBP, USD, NOK, SEK)
MerchantOrderIdstring?NãoA sua referência interna da encomenda
Descriptionstring?NãoDescrição da encomenda
ReturnUrlstring?NãoRedirecionamento após pagamento bem-sucedido
FailureUrlstring?NãoRedirecionamento em cancelamento/expiração/erro
WebhookUrlstring?NãoNotificações assíncronas de alteração de estado
Localestring?NãoIdioma do HPP (en-GB, de-DE, nl-NL, etc.)
PaymentMethodsIReadOnlyList<string>?NãoFiltrar métodos do HPP
ExpirationPeriodstring?NãoDuração ISO 8601 (PT30M)

Métodos de pagamento disponíveis: credit-card, apple-pay, google-pay, vipps-mobilepay

client.GetOrderAsync(orderId): Task<Order>

Obtém detalhes da encomenda via GET /v1/orders/{id}/.

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

Emite um reembolso total ou parcial via POST /v1/orders/{id}/refunds/.

client.GeneratePaymentUrlAsync(params): Task<PaymentUrlResult>

Método de conveniência que cria uma encomenda e devolve:

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

Gera uma assinatura HMAC-SHA256 em hexadecimal.

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

Verificação em tempo constante de uma assinatura HMAC-SHA256.

client.VerifyWebhookAsync(rawBody): Task<VerifiedWebhook>

Analisa o corpo do webhook, depois chama GET /v1/orders/{id}/ para verificar o estado real.

Utilitários HMAC Autónomos

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

Tratamento de Erros

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
}
ExceçãoDescrição
NoPaynExceptionExceção base (rede, parsing)
ApiExceptionErro HTTP da API
WebhookExceptionPayload de webhook inválido

Estados da Encomenda

EstadoFinal?Descrição
newNãoEncomenda criada
processingNãoPagamento em curso
completedSimPagamento bem-sucedido — entregue a mercadoria
cancelledSimPagamento cancelado pelo cliente
expiredSimLink de pagamento expirou
errorSimFalha técnica

Boas Práticas para Webhooks

  1. Verifique sempre através da API — o payload do webhook contém apenas o ID da encomenda, nunca o estado. O VerifyWebhookAsync() do SDK faz isto automaticamente.
  2. Devolva HTTP 200 para confirmar a receção. Qualquer outro código desencadeia até 10 tentativas (com 2 minutos de intervalo).
  3. Implemente um poller de backup — para encomendas com mais de 10 minutos que não atingiram um estado final, consulte GetOrderAsync() como rede de segurança.
  4. Seja idempotente — pode receber o mesmo webhook várias vezes.

Cartões de Teste

Utilize estes cartões no modo de teste da Cost+ (website sandbox):

CartãoNúmeroNotas
Visa (sucesso)4111 1111 1111 1111Qualquer CVV
Mastercard (sucesso)5544 3300 0003 7Qualquer CVV
Visa (recusado)4111 1111 1111 1105Do Not Honor
Visa (fundos insuficientes)4111 1111 1111 1151Insufficient Funds

Utilize qualquer data de validade futura e qualquer CVC de 3 dígitos.

Aplicação de Demonstração

Uma aplicação de demonstração ASP.NET Core baseada em Docker está incluída no repositório GitHub para testar o fluxo completo de pagamento.

Suporte

Precisa de ajuda? Contacte a nossa equipa de suporte em support@costplus.io.

On this page