Payout

Node.js

Node.js SDK для интеграции с Payment Easy Payout API.

Node.js

Node.js SDK для интеграции с Payment Easy Payout API.

Установка

git clone https://github.com/unitewt/sdk-payout.git
cd sdk-payout/nodejs
npm install

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

const fs = require('fs');
const { Config, PayoutClient, ServiceCode, BankCode } = require('payout-sdk');

const config = new Config({
  baseUrl: 'https://your-server.example.com',
  username: 'your_username',
  privateKeyPem: fs.readFileSync('./private-key.pem', 'utf8'),
});

const client = new PayoutClient(config);

// Запрос баланса
const balance = await client.balance();
console.log(`Баланс: ${balance.balance} копеек`);

// Выплата на карту
const resp = await client.payment({
  id: 'unique-tx-id',
  sum: 100000, // 1000 рублей в копейках
  service: ServiceCode.BANK_CARD,
  account: '4277255555555555',
  date: new Date(),
  phone: '79999999999',
});

if (resp.isFinalState()) {
  console.log(`Успех: ${resp.isSuccessful()}`);
}

// Проверка статуса
const status = await client.getStatus('unique-tx-id');
console.log(`code=${status.code}, state=${status.state}, final=${status.final}`);

Конфигурация

const config = new Config({
  baseUrl: 'https://your-server.example.com',       // URL сервера
  username: 'your_username',                         // имя пользователя
  privateKeyPem: '-----BEGIN PRIVATE KEY-----...',   // RSA приватный ключ (PEM)
  serverPublicKeyPem: '-----BEGIN PUBLIC KEY-----...', // опционально: верификация ответов
  timeoutMs: 300000,                                 // таймаут в мс (по умолчанию 300000)
});

Параметр	Тип	Обязательный	По умолчанию	Описание
`baseUrl`	`string`	да	—	URL сервера
`username`	`string`	да	—	Имя пользователя
`privateKeyPem`	`string`	да	—	RSA приватный ключ (PEM)
`serverPublicKeyPem`	`string`	нет	`null`	Публичный ключ сервера
`timeoutMs`	`number`	нет	`300000`	HTTP таймаут (мс)

API

`PayoutClient`

Метод	Описание	Возвращает
`balance()`	Запрос баланса	`Promise<BalanceResponse>`
`payment(params)`	Выполнение выплаты	`Promise<PaymentResponse>`
`getStatus(txId)`	Проверка статуса	`Promise<PaymentResponse>`

Параметры `payment()`

Параметр	Тип	Обязательный	Описание
`id`	`string`	да	Уникальный ID транзакции (до 64 байт)
`sum`	`number`	да	Сумма в копейках
`service`	`ServiceCode`	да	Тип сервиса
`account`	`string`	да	Номер карты / телефона / кошелька
`date`	`Date`	да	Дата транзакции
`phone`	`string`	да	Телефон плательщика
`payeeBankCode`	`string`	нет	Код банка получателя (для СБП)

`PaymentResponse`

Свойство/Метод	Тип	Описание
`id`	`string`	Ваш ID транзакции
`code`	`number`	Код результата
`state`	`number`	Состояние платежа
`final`	`number`	1 = финальный статус
`trans`	`string`	ID транзакции на стороне шлюза
`fee`	`number\|null`	Комиссия в копейках
`errorDescription`	`string\|null`	Описание ошибки
`isSuccessful()`	`boolean`	code=0, state=60, final=1
`isFailed()`	`boolean`	code=20, state=80, final=1
`isNotFound()`	`boolean`	code=15, state=-2, final=1
`isProcessing()`	`boolean`	code=1, state=40, final=0
`isFinalState()`	`boolean`	final=1

`BalanceResponse`

Свойство	Тип	Описание
`balance`	`number`	Баланс в копейках
`overdraft`	`number`	Овердрафт в копейках

Сервисы

ServiceCode.BANK_CARD    // 24 — банковские карты
ServiceCode.QIWI_WALLET  // 25 — кошельки QIWI
ServiceCode.SBP           // 26 — СБП
ServiceCode.MOBILE_PHONE  // 28 — мобильные телефоны

Коды банков (СБП)

BankCode.SBERBANK_OF_RUSSIA  // '100000000111'
BankCode.TINKOFF_BANK        // '100000000004'
BankCode.ALFA_BANK           // '100000000008'
// ... 238 банков

Выплата через СБП

const resp = await client.payment({
  id: 'sbp-tx-id',
  sum: 50000,
  service: ServiceCode.SBP,
  account: '79876543210',
  date: new Date(),
  phone: '79999999999',
  payeeBankCode: BankCode.SBERBANK_OF_RUSSIA,
});

Обработка ошибок

SDK определяет три класса ошибок:

PayoutError — базовый класс
ApiError — ошибки API (свойства: transactionId, statusCode)
SignatureError — ошибки подписи

const { ApiError, SignatureError } = require('payout-sdk');

try {
  const resp = await client.payment(params);
} catch (err) {
  if (err instanceof ApiError) {
    console.error(`API ошибка: ${err.message}, status=${err.statusCode}`);
  } else if (err instanceof SignatureError) {
    console.error(`Ошибка подписи: ${err.message}`);
  }
}

Примеры

examples/generate_keys.js — генерация RSA-ключей
examples/integration_test.js — полный интеграционный тест

# Генерация ключей
npm run generate-keys

# Интеграционный тест
export PAYOUT_BASE_URL="https://your-server.example.com"
export PAYOUT_USERNAME="your_username"
export PAYOUT_PRIVATE_KEY_PATH="./private-key.pem"

npm run integration-test

Go-модуль для интеграции с Payment Easy Payout API.

PHP

PHP SDK для интеграции с Payment Easy Payout API.