tochka-sbp

TypeScript SDK для работы с СБП (Система Быстрых Платежей) через API Точка Банка.

Возможности:

• Авторизация по JWT-токену (без необходимости обновлять токен каждый день)
• Создание динамических и статических QR-кодов для приёма оплаты
• Мгновенная проверка и автоматический polling статуса оплаты
• Инициирование и отслеживание возвратов
• Полная типизация TypeScript
• Встроенная обработка ошибок с отдельными классами для каждого сценария

Установка

npm install

Получение JWT-токена

1. Откройте Интернет-банк Точки
2. Перейдите: Интеграции и API → Подключить → Сгенерировать JWT-ключ
3. Введите название токена, выберите TTL и разрешения:
   • EditSBPData — создание QR-кодов, возвраты
   • ReadSBPData — проверка статусов, список платежей
4. Подтвердите SMS-кодом
5. Скопируйте токен и client_id

Документация: Авторизация по JWT-токену

Быстрый старт

cp .env.example .env
# Заполните переменные в .env

Создать клиент

import { TochkaSBP } from './src';

const tochka = new TochkaSBP({
  jwt:     process.env.TOCHKA_JWT!,
  sandbox: false, // true для тестов
});

Создать QR-код и принять оплату

// Создаём динамический QR-код на 1 рубль
const payment = await tochka.createSBP({
  merchantId:  process.env.TOCHKA_MERCHANT_ID!,
  accountId:   process.env.TOCHKA_ACCOUNT_ID!,
  amount:      100,          // 1 рубль = 100 копеек
  description: 'Оплата заказа #42',
  qrcType:     'DYNAMIC',    // одноразовый с фиксированной суммой
  ttl:         300,          // действителен 5 минут
});

console.log('QR-код:', payment.payUrl);         // URL для сканирования
console.log('Сумма:', payment.amountRubles, 'руб.');

Однократная проверка статуса

const status = await payment.getStatus();
console.log(status.operationStatus);
// 'NTST' — ожидание, 'ACWP' — оплачен, 'RJCT' — отклонён

Ожидать оплаты (polling)

import { TochkaPaymentTimeoutError, TochkaPaymentRejectedError } from './src';

try {
  const result = await payment.waitForPayment({
    timeoutMs:   10 * 60_000,   // ждать до 10 минут
    intervalMs:  3_000,          // проверять каждые 3 секунды
    onStatusCheck: (status, elapsed) => {
      console.log(`[${Math.round(elapsed / 1000)}s] ${status}`);
    },
  });

  console.log('✅ Платёж получен!');
  console.log('Транзакция:', result.transactionId);

} catch (err) {
  if (err instanceof TochkaPaymentTimeoutError) {
    console.log('⏰ Время ожидания истекло');
  } else if (err instanceof TochkaPaymentRejectedError) {
    console.log('❌ Платёж отклонён:', err.status);
  }
}

Примеры

Базовый пример

npm run example:basic

Создаёт QR-код на 1 рубль и однократно проверяет статус.

Пример с polling

npm run example:polling

Создаёт QR-код на 2 рубля и ждёт оплаты в реальном времени с выводом таймера. Сразу после поступления средств выводит детали транзакции.

API Reference

new TochkaSBP(config)

| Поле | Тип | Обязательное | Описание | |------|-----|:---:|---------| | jwt | string | ✅ | JWT-токен из интернет-банка Точки | | baseUrl | string | — | Кастомный базовый URL API | | timeout | number | — | Таймаут запросов в мс (по умолчанию: 30000) | | sandbox | boolean | — | Использовать тестовое окружение |

tochka.createSBP(params) → Promise<SBPPayment>

Создаёт QR-код СБП. Требует разрешение EditSBPData.

| Параметр | Тип | Обязательное | Описание | |----------|-----|:---:|---------| | merchantId | string | ✅ | ID торговой точки в СБП | | accountId | string | ✅ | Расчётный счёт (20 цифр) | | description | string | ✅ | Назначение платежа (макс. 140 симв.) | | amount | number | ✅* | Сумма в копейках (нужна для DYNAMIC) | | qrcType | 'DYNAMIC' | 'STATIC' | — | Тип QR (по умолч.: DYNAMIC) | | ttl | number | — | Время жизни в секундах (0 = макс.) | | redirectUrl | string | — | Редирект после оплаты | | imageParams | QRImageParams | — | Параметры изображения |

SBPPayment

Объект, возвращаемый createSBP().

| Свойство | Тип | Описание | |----------|-----|---------| | qrcId | string | ID QR-кода в СБП | | payload | string | Строка payload QR-кода | | payUrl | string | URL для сканирования / перехода | | amount | number? | Сумма в копейках | | amountRubles | number? | Сумма в рублях (computed) | | imageBase64 | string? | QR-изображение в base64 | | imageDataUri | string? | Data URI для <img src="..."> | | currency | string | Валюта (всегда 'RUB') |

| Метод | Возвращает | Описание | |-------|-----------|---------| | getStatus() | Promise<PaymentStatusData> | Однократная проверка статуса | | isPaid() | Promise<boolean> | Проверить — оплачен ли | | waitForPayment(opts) | Promise<PaymentStatusData> | Ожидать оплаты с polling |

Статусы платежей (НСПК / ISO 20022)

| Статус | Значение | |--------|---------| | NTST | Нет транзакции / ожидание оплаты | | ACTC | Техническая валидация пройдена (в обработке) | | ACWP | ✅ Платёж принят (деньги поступили) | | ACSC | ✅ Расчёт завершён | | RJCT | ❌ Отклонён | | CANC | ❌ Отменён |

Прочие методы клиента

// Проверить статус по ID QR-кода
await tochka.getPaymentStatus('QRCID001');
await tochka.getPaymentStatus(['QRCID001', 'QRCID002']); // batch

// Получить QR-код по ID
const payment = await tochka.getQRCode('QRCID001');

// Список QR-кодов юрлица
const list = await tochka.listQRCodes(process.env.TOCHKA_LEGAL_ID!);

// Список входящих платежей за период
const payments = await tochka.getPayments({
  fromDate: '2024-01-01',
  toDate:   '2024-01-31',
});

// Возврат (только для динамических QR-кодов)
const refund = await tochka.startRefund({
  accountCode:   '40702810000000000001',
  amount:        100,   // копейки
  qrcId:         'QRCID001',
  transactionId: 'TRX001',
  purpose:       'Возврат заказа',
});

// Статус возврата
const refundStatus = await tochka.getRefundStatus(refund.requestId);

// Список мерчантов юрлица
const merchants = await tochka.getMerchants(process.env.TOCHKA_LEGAL_ID!);

Классы ошибок

| Класс | Когда возникает | |-------|----------------| | TochkaError | Базовый класс всех ошибок SDK | | TochkaAPIError | HTTP-ошибка от сервера (содержит statusCode, response) | | TochkaAuthError | 401 — истёкший или неверный JWT | | TochkaForbiddenError | 403 — недостаточно прав (EditSBPData / ReadSBPData) | | TochkaNotFoundError | 404 — ресурс не найден | | TochkaValidationError | 400 — некорректный запрос | | TochkaPaymentTimeoutError | Время ожидания в waitForPayment истекло | | TochkaPaymentRejectedError | Платёж отклонён (RJCT/CANC) в waitForPayment |

Структура проекта

tochka-sbp/
├── src/
│   ├── index.ts       # Точка входа, публичные экспорты
│   ├── client.ts      # TochkaSBP — основной клиент
│   ├── payment.ts     # SBPPayment — объект платежа
│   ├── types.ts       # Все TypeScript-типы и интерфейсы
│   └── errors.ts      # Классы ошибок
├── examples/
│   ├── basic-payment.ts    # Пример: создать QR + проверить статус
│   └── polling-payment.ts  # Пример: ждать оплаты в реальном времени
├── dist/              # Скомпилированный JavaScript (после npm run build)
├── .env.example       # Шаблон переменных окружения
├── package.json
└── tsconfig.json

Ссылки

• Точка API — СБП документация
• Авторизация по JWT
• Register QR Code API
• Тестирование в Sandbox