Cost+Docs

Node.js / TypeScript

Официално Node.js SDK за разплащателния шлюз Cost+

Официално Node.js/TypeScript SDK за разплащателния шлюз Cost+. Опростява потока за пренасочване към HPP (хоствана страница за плащане), HMAC подписването на данни и верификацията на уебхукове.

Характеристики

  • Нулеви зависимости — използва само вградените в Node.js crypto и fetch
  • Пълни TypeScript типове с карти на декларациите
  • HMAC-SHA256 генериране на подписи и верификация с постоянно време
  • Автоматично съответствие snake_case/camelCase между API и SDK
  • Анализиране на уебхукове + верификация на поръчки, базирана на API
  • Тествано с Node.js 18, 20 и 22

Изисквания

  • Node.js 18 или по-нова версия (използва вградения fetch)
  • Търговски акаунт в Cost+ — dashboard.costplus.io

Инсталация

npm install nopayn-node-sdk

Бързо начало

1. Инициализиране на клиента

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. Създаване на плащане и пренасочване към 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. Обработка на уебхука

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

API справочник

new NoPaynClient(config)

ПараметърТипЗадължителенПо подразбиране
apiKeystringДа—
merchantIdstringДа—
baseUrlstringНеhttps://api.nopayn.co.uk

client.createOrder(params)

Създава поръчка чрез POST /v1/orders/.

ПараметърТипЗадължителенОписание
amountnumberдаСума в ISO 4217 второстепенна единица на валутата (например центове за EUR)
currencystringДаISO 4217 код (EUR, GBP, USD, NOK, SEK)
merchantOrderIdstringНеВаш вътрешен идентификатор на поръчка
descriptionstringНеОписание на поръчката
returnUrlstringНеПренасочване след успешно плащане
failureUrlstringНеПренасочване при отказ/изтичане/грешка
webhookUrlstringНеАсинхронни известия за промяна на статуса
localestringНеЕзик на HPP (en-GB, de-DE, nl-NL и др.)
paymentMethodsPaymentMethod[]НеФилтриране на HPP методи
expirationPeriodstringНеISO 8601 продължителност (PT30M)

Налични методи на плащане: credit-card, apple-pay, google-pay, vipps-mobilepay

client.getOrder(orderId)

Извлича детайли на поръчка чрез GET /v1/orders/{id}/.

client.createRefund(orderId, amount, description?)

Издава пълно или частично възстановяване чрез POST /v1/orders/{id}/refunds/.

client.generatePaymentUrl(params)

Удобен метод, който създава поръчка и връща:

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

Генерира HMAC-SHA256 шестнадесетичен подпис. Каноничното съобщение е ${amount}:${currency}:${orderId}, подписано с API ключа.

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

Верификация с постоянно време на HMAC-SHA256 подпис. Връща true, ако е валиден.

client.verifyWebhook(rawBody)

Анализира тялото на уебхука, след което извиква GET /v1/orders/{id}/, за да провери действителния статус. Връща:

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

client.parseWebhookBody(rawBody)

Анализира и валидира тялото на уебхук без извикване на API.

Самостоятелни HMAC помощни функции

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

Обработка на грешки

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
  }
}

Статуси на поръчки

СтатусФинален?Описание
newНеПоръчката е създадена
processingНеПлащането е в ход
completedДаПлащането е успешно — доставете стоката
cancelledДаПлащането е отменено от клиента
expiredДаЛинкът за плащане е изтекъл
errorДаТехническа грешка

Добри практики за уебхукове

  1. Винаги проверявайте чрез API — данните от уебхука съдържат само идентификатора на поръчката, никога статуса. verifyWebhook() на SDK-то прави това автоматично.
  2. Връщайте HTTP 200, за да потвърдите получаването. Всеки друг код задейства до 10 повторни опита (през 2 минути).
  3. Въведете резервен polling — за поръчки, по-стари от 10 минути, които не са достигнали финален статус, правете polling с getOrder() като мрежа за безопасност.
  4. Бъдете идемпотентни — може да получите един и същ уебхук многократно.

Тестови карти

Използвайте тези карти в тестов режим на Cost+ (sandbox уебсайт):

КартаНомерБележки
Visa (успех)4111 1111 1111 1111Произволен CVV
Mastercard (успех)5544 3300 0003 7Произволен CVV
Visa (отхвърлена)4111 1111 1111 1105Do Not Honor
Visa (недостатъчни средства)4111 1111 1111 1151Insufficient Funds

Използвайте произволна бъдеща дата на валидност и произволен 3-цифрен CVC.

Демо приложение

Демо приложение, базирано на Docker, е включено в GitHub хранилището за тестване на пълния поток на плащане:

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

Отворете http://localhost:3000, за да видите демо страницата за каса.

Поддръжка

Нуждаете се от помощ? Свържете се с нашия екип за поддръжка на support@costplus.io.

On this page