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 UUID3. Обработка на уебхука
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)
| Параметър | Тип | Задължителен | По подразбиране |
|---|---|---|---|
apiKey | string | Да | — |
merchantId | string | Да | — |
baseUrl | string | Не | https://api.nopayn.co.uk |
client.createOrder(params)
Създава поръчка чрез POST /v1/orders/.
| Параметър | Тип | Задължителен | Описание |
|---|---|---|---|
amount | number | да | Сума в ISO 4217 второстепенна единица на валутата (например центове за EUR) |
currency | string | Да | ISO 4217 код (EUR, GBP, USD, NOK, SEK) |
merchantOrderId | string | Не | Ваш вътрешен идентификатор на поръчка |
description | string | Не | Описание на поръчката |
returnUrl | string | Не | Пренасочване след успешно плащане |
failureUrl | string | Не | Пренасочване при отказ/изтичане/грешка |
webhookUrl | string | Не | Асинхронни известия за промяна на статуса |
locale | string | Не | Език на HPP (en-GB, de-DE, nl-NL и др.) |
paymentMethods | PaymentMethod[] | Не | Филтриране на HPP методи |
expirationPeriod | string | Не | 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 | Да | Техническа грешка |
Добри практики за уебхукове
- Винаги проверявайте чрез API — данните от уебхука съдържат само идентификатора на поръчката, никога статуса.
verifyWebhook()на SDK-то прави това автоматично. - Връщайте HTTP 200, за да потвърдите получаването. Всеки друг код задейства до 10 повторни опита (през 2 минути).
- Въведете резервен polling — за поръчки, по-стари от 10 минути, които не са достигнали финален статус, правете polling с
getOrder()като мрежа за безопасност. - Бъдете идемпотентни — може да получите един и същ уебхук многократно.
Тестови карти
Използвайте тези карти в тестов режим на Cost+ (sandbox уебсайт):
| Карта | Номер | Бележки |
|---|---|---|
| Visa (успех) | 4111 1111 1111 1111 | Произволен CVV |
| Mastercard (успех) | 5544 3300 0003 7 | Произволен CVV |
| Visa (отхвърлена) | 4111 1111 1111 1105 | Do Not Honor |
| Visa (недостатъчни средства) | 4111 1111 1111 1151 | Insufficient 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.