Официальный TypeScript SDK для серверной интеграции с Robokassa.
SDK поддерживает Node.js 18+, ESM и CommonJS, поставляется с декларациями
TypeScript и использует встроенный fetch.
SDK предназначен только для серверного использования. Не добавляйте его в браузерную сборку и не передавайте пароли магазина на клиент.
- создание подписанной платежной ссылки без HTTP-запроса;
- создание платежа через form flow и Invoice JWT API;
- создание, деактивация и поиск счетов;
- проверка ResultURL и SuccessURL с безопасным сравнением подписи;
- получение валют, способов оплаты и состояния операции через XML API;
- возвраты, холдирование, рекуррентные платежи и SMS;
- отправка второго фискального чека и проверка его состояния;
- настраиваемый таймаут,
AbortSignal, собственныйfetchи endpoints; - структурированные ошибки без утечки секретов.
npm install @robokassa/sdkimport { RobokassaClient } from '@robokassa/sdk';
const robokassa = new RobokassaClient({
login: process.env.ROBOKASSA_LOGIN!,
password1: process.env.ROBOKASSA_PASSWORD1!,
password2: process.env.ROBOKASSA_PASSWORD2!,
hashAlgorithm: 'md5',
});
const paymentUrl = await robokassa.payment.sendJWT({
InvID: 1001,
OutSum: 99.9,
Description: 'Заказ №1001',
Culture: 'ru',
InvoiceItems: [
{
Name: 'Заказ №1001',
Quantity: 1,
Cost: 99.9,
Tax: 'none',
PaymentMethod: 'full_payment',
PaymentObject: 'service',
},
],
});
console.log(paymentUrl);InvID должен быть уникальным для нового счета. Параметр isTest относится к
классической платежной форме; Invoice JWT API не включает тестовый режим через
IsTest=1.
import { RobokassaClient } from '@robokassa/sdk';
const robokassa = new RobokassaClient({
login: process.env.ROBOKASSA_LOGIN,
password1: process.env.ROBOKASSA_PASSWORD1,
password2: process.env.ROBOKASSA_PASSWORD2,
});
const url = robokassa.payment.buildPaymentURL({
OutSum: '149.00',
InvID: '1002',
Description: 'Оплата заказа №1002',
Culture: 'ru',
Email: 'buyer@example.com',
ShpFields: { Shp_order: '1002' },
});const { RobokassaClient } = require('@robokassa/sdk');
const robokassa = new RobokassaClient({
login: process.env.ROBOKASSA_LOGIN,
password1: process.env.ROBOKASSA_PASSWORD1,
password2: process.env.ROBOKASSA_PASSWORD2,
});
const url = robokassa.payment.buildPaymentURL({
OutSum: '10.00',
InvID: '1001',
Description: 'Тестовый заказ',
});| Параметр | Обязательный | Назначение |
|---|---|---|
login |
да | Логин магазина |
password1 |
да | Создание платежей и проверка SuccessURL |
password2 |
да | Проверка ResultURL и запрос состояния операции |
password3 |
только для возвратов | Подпись запросов API возвратов |
testPassword1 |
при isTest: true |
Тестовый Пароль №1 |
testPassword2 |
при isTest: true |
Тестовый Пароль №2 |
isTest |
нет | Тестовый режим классической платежной формы |
hashAlgorithm |
нет | md5, sha256 или sha512; по умолчанию md5 |
refundHashAlgorithm |
нет | sha256, sha384 или sha512 |
timeoutMs |
нет | Таймаут запроса; по умолчанию 15 секунд |
fetch |
нет | Собственная реализация Fetch API |
endpoints |
нет | Частичное переопределение адресов сервисов |
const robokassa = new RobokassaClient({
login: process.env.ROBOKASSA_LOGIN!,
password1: process.env.ROBOKASSA_PASSWORD1!,
password2: process.env.ROBOKASSA_PASSWORD2!,
testPassword1: process.env.ROBOKASSA_TEST_PASSWORD1!,
testPassword2: process.env.ROBOKASSA_TEST_PASSWORD2!,
isTest: true,
});
const paymentUrl = robokassa.payment.buildPaymentURL({
OutSum: '10.00',
InvID: '900001',
Description: 'Тестовый заказ',
});Тестовый режим применяется только к классической платежной форме. Для Invoice
JWT API создайте отдельный клиент с обычными паролями и без isTest: true.
Локальная GET-ссылка:
const paymentUrl = robokassa.payment.buildPaymentURL({
OutSum: '100.00',
InvID: '1003',
Description: 'Заказ №1003',
Receipt: {
items: [
{
name: 'Подписка',
quantity: 1,
sum: 100,
tax: 'none',
payment_method: 'full_payment',
payment_object: 'service',
},
],
},
});Если форму нужно отрисовать самостоятельно:
const form = robokassa.payment.buildPaymentForm({
OutSum: '100.00',
InvID: '1004',
Description: 'Заказ №1004',
});Метод sendForm создаёт платёж через JSON endpoint и возвращает готовую
ссылку.
SDK не зависит от web-фреймворка. Например, с Express передайте разобранное form-body:
Перед отправкой подтверждения атомарно и идемпотентно зафиксируйте оплату в базе данных.
import express from 'express';
const app = express();
app.post(
'/robokassa/result',
express.urlencoded({ extended: false }),
(req, res) => {
try {
const notification = robokassa.notification.parseResultURL(req.body);
robokassa.notification.verifyResultURL(notification);
res.type('text/plain').send(
robokassa.notification.resultResponse(notification),
);
} catch {
res.status(400).send('invalid notification');
}
},
);verifyResultURL использует Пароль №2, а verifySuccessURL — Пароль №1.
Пользовательские поля Shp_* автоматически включаются в проверку в
алфавитном порядке.
Для дополнительного ResultUrl2 используйте
notification.verifyResultURL2(compactJWS, certificate). Передайте актуальный
сертификат Robokassa из официальной документации; метод проверит подпись до
возврата header и data. Для браузерного FailURL доступен
notification.parseFailURL.
| Сервис | Основные методы |
|---|---|
payment |
buildPaymentURL, buildPaymentForm, sendForm, sendJWT |
invoices |
create, deactivate, list |
status |
getInvoiceInformationList |
webService |
getPaymentMethods, getCurrencies, opState |
notification |
parseResultURL, verifyResultURL, parseSuccessURL, verifySuccessURL, parseFailURL, verifyResultURL2 |
refunds |
create, getState |
holding |
confirm, cancel |
recurring |
create |
messaging |
sendGet, sendPost |
receipt |
buildSecondCheckToken, sendSecondCheck, getCheckStatus |
Возвраты, холдирование, рекуррентные платежи, SMS и отдельные фискальные операции должны быть предварительно подключены для магазина.
API возвратов требует отдельного password3 и предварительного подключения
услуги:
const robokassa = new RobokassaClient({
login,
password1,
password2,
password3,
refundHashAlgorithm: 'sha256',
});
const refund = await robokassa.refunds.create({
OpKey: operationKey,
RefundSum: 50,
});import { RobokassaError } from '@robokassa/sdk';
try {
await robokassa.webService.opState(1001);
} catch (error) {
if (error instanceof RobokassaError) {
console.error(error.code, error.operation, error.statusCode);
}
}error.responseBody доступен для внутренней диагностики. Перед записью в
публичные логи его следует фильтровать.
Коды: VALIDATION_ERROR, CONFIGURATION_ERROR, NETWORK_ERROR, TIMEOUT,
HTTP_ERROR, API_ERROR, PARSE_ERROR, INVALID_SIGNATURE.
const controller = new AbortController();
const robokassa = new RobokassaClient({
login,
password1,
password2,
timeoutMs: 10_000,
fetch: customFetch,
});
await robokassa.webService.getCurrencies('ru', {
signal: controller.signal,
});endpoints можно переопределить для тестового HTTP-сервера. Это не меняет
правила подписи и не следует использовать для передачи секретов недоверенному
узлу.
npm ci
npm run lint
npm test
npm run typecheck
npm run buildUnit-тесты не обращаются к Robokassa и не выполняют реальные платежи.
MIT