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.JsoneSystem.Security.Cryptographynativos - 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
- .NET 8.0 SDK ou superior
- Uma conta de comerciante Cost+ — dashboard.costplus.io
Instalação
dotnet add package NoPaynOu como referência de projeto local:
dotnet add reference path/to/src/NoPayn/NoPayn.csprojIní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 UUID3. 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âmetro | Tipo | Obrigatório | Predefinição |
|---|---|---|---|
ApiKey | string | Sim | — |
MerchantId | string | Sim | — |
BaseUrl | string | Não | https://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âmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
Amount | int | Sim | Montante na menor unidade monetária (cêntimos) |
Currency | string | Sim | Código ISO 4217 (EUR, GBP, USD, NOK, SEK) |
MerchantOrderId | string? | Não | A sua referência interna da encomenda |
Description | string? | Não | Descrição da encomenda |
ReturnUrl | string? | Não | Redirecionamento após pagamento bem-sucedido |
FailureUrl | string? | Não | Redirecionamento em cancelamento/expiração/erro |
WebhookUrl | string? | Não | Notificações assíncronas de alteração de estado |
Locale | string? | Não | Idioma do HPP (en-GB, de-DE, nl-NL, etc.) |
PaymentMethods | IReadOnlyList<string>? | Não | Filtrar métodos do HPP |
ExpirationPeriod | string? | Não | Duraçã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ção | Descrição |
|---|---|
NoPaynException | Exceção base (rede, parsing) |
ApiException | Erro HTTP da API |
WebhookException | Payload de webhook inválido |
Estados da Encomenda
| Estado | Final? | Descrição |
|---|---|---|
new | Não | Encomenda criada |
processing | Não | Pagamento em curso |
completed | Sim | Pagamento bem-sucedido — entregue a mercadoria |
cancelled | Sim | Pagamento cancelado pelo cliente |
expired | Sim | Link de pagamento expirou |
error | Sim | Falha técnica |
Boas Práticas para Webhooks
- 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. - Devolva HTTP 200 para confirmar a receção. Qualquer outro código desencadeia até 10 tentativas (com 2 minutos de intervalo).
- 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. - 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ão | Número | Notas |
|---|---|---|
| Visa (sucesso) | 4111 1111 1111 1111 | Qualquer CVV |
| Mastercard (sucesso) | 5544 3300 0003 7 | Qualquer CVV |
| Visa (recusado) | 4111 1111 1111 1105 | Do Not Honor |
| Visa (fundos insuficientes) | 4111 1111 1111 1151 | Insufficient 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.