Node.js / TypeScript

SDK oficial Node.js/TypeScript 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 crypto e fetch nativos do Node.js
Tipos TypeScript completos com declaration maps
Geração de assinaturas HMAC-SHA256 e verificação em tempo constante
Mapeamento automático snake_case/camelCase entre a API e o SDK
Análise de webhooks + verificação de encomendas baseada na API
Testado com Node.js 18, 20 e 22

Requisitos

Node.js 18 ou superior (utiliza fetch nativo)
Uma conta de comerciante Cost+ — dashboard.costplus.io

Instalação

npm install nopayn-node-sdk

Início Rápido

1. Inicializar o Cliente

import { NoPaynClient } from 'nopayn-node-sdk';

const nopayn = new NoPaynClient({
  apiKey: 'your-api-key',      // From the NoPayn merchant portal
  merchantId: 'your-project',  // Your project/merchant ID
});

2. Criar um Pagamento e Redirecionar para o HPP

const result = await nopayn.generatePaymentUrl({
  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.post('/webhook', async (req, res) => {
  const verified = await nopayn.verifyWebhook(JSON.stringify(req.body));

  console.log(verified.order.status); // 'completed', 'cancelled', etc.
  console.log(verified.isFinal);      // true when the order won't change

  if (verified.order.status === 'completed') {
    // Fulfil the order
  }

  res.sendStatus(200);
});

Referência da API

`new NoPaynClient(config)`

Parâmetro	Tipo	Obrigatório	Predefinição
`apiKey`	`string`	Sim	—
`merchantId`	`string`	Sim	—
`baseUrl`	`string`	Não	`https://api.nopayn.co.uk`

`client.createOrder(params)`

Cria uma encomenda via POST /v1/orders/.

Parâmetro	Tipo	Obrigatório	Descrição
`amount`	`number`	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`	`PaymentMethod[]`	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.getOrder(orderId)`

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

`client.createRefund(orderId, amount, description?)`

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

`client.generatePaymentUrl(params)`

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

{
  orderId: string;     // NoPayn order UUID
  orderUrl: string;    // HPP URL
  paymentUrl?: string; // Direct payment URL (first transaction)
  signature: string;   // HMAC-SHA256 of amount:currency:orderId
  order: Order;        // Full order object
}

`client.generateSignature(amount, currency, orderId)`

Gera uma assinatura HMAC-SHA256 em hexadecimal. A mensagem canónica é ${amount}:${currency}:${orderId}, assinada com a chave API.

`client.verifySignature(amount, currency, orderId, signature)`

Verificação em tempo constante de uma assinatura HMAC-SHA256. Devolve true se válida.

`client.verifyWebhook(rawBody)`

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

{
  orderId: string;
  order: Order;     // Verified via API
  isFinal: boolean; // true for completed/cancelled/expired/error
}

`client.parseWebhookBody(rawBody)`

Analisa e valida o corpo de um webhook sem chamar a API.

Utilitários HMAC Autónomos

import { generateSignature, verifySignature } from 'nopayn-node-sdk';

const sig = generateSignature('your-api-key', 1295, 'EUR', 'order-uuid');
const ok  = verifySignature('your-api-key', 1295, 'EUR', 'order-uuid', sig);

Tratamento de Erros

import { NoPaynApiError, NoPaynError, NoPaynWebhookError } from 'nopayn-node-sdk';

try {
  await nopayn.createOrder({ amount: 100, currency: 'EUR' });
} catch (err) {
  if (err instanceof NoPaynApiError) {
    console.error(err.statusCode); // 401, 400, etc.
    console.error(err.errorBody);  // Raw API error response
  } else if (err instanceof NoPaynError) {
    console.error(err.message);    // Network or parsing error
  }
}

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 verifyWebhook() 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 getOrder() 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 baseada em Docker está incluída no repositório GitHub para testar o fluxo completo de pagamento:

cd demo

cat > .env << EOF
NOPAYN_API_KEY=your-api-key
NOPAYN_MERCHANT_ID=your-merchant-id
PUBLIC_URL=http://localhost:3000
EOF

docker compose up --build

Abra http://localhost:3000 para ver a página de demonstração do checkout.

Suporte

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

On this page