YooKassa SDK

Современный TypeScript SDK для интеграции с YooKassa API. Поддерживает платежи, возвраты, чеки и многое другое.

Особенности

• 🚀 Полная типизация — написан на TypeScript с полной поддержкой типов
• 🔄 Автоматические повторы — retry с exponential backoff при сетевых ошибках
• 🔑 Идемпотентность — автоматическая генерация Idempotence-Key для безопасных повторов
• 🌐 Поддержка прокси — работа через HTTP/HTTPS прокси
• ⚡ Rate limiting — встроенное ограничение частоты запросов
• 🕐 Таймауты — настраиваемые таймауты запросов
• 📦 Кэширование инстансов — эффективное переиспользование соединений
• 🔧 Совместимость — работает с Node.js, Bun и другими рантаймами

Установка

# npm
npm install yookassa-api-sdk

# yarn
yarn add yookassa-api-sdk

# bun
bun add yookassa-api-sdk

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

import { YooKassa } from 'yookassa-api-sdk';

const sdk = YooKassa({
    shop_id: 'ваш_идентификатор_магазина',
    secret_key: 'ваш_секретный_ключ',
});

// Создание платежа
const payment = await sdk.payments.create({
    amount: { value: '100.00', currency: 'RUB' },
    confirmation: { type: 'redirect', return_url: 'https://example.com' },
    description: 'Заказ №1',
});

console.log(payment.confirmation.confirmation_url);

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

interface ConnectorOpts {
    /** Идентификатор магазина (обязательный) */
    shop_id: string;

    /** Секретный ключ магазина (обязательный) */
    secret_key: string;

    /** Режим отладки — логирует запросы и ответы */
    debug?: boolean;

    /** Таймаут запроса в миллисекундах (по умолчанию: 5000) */
    timeout?: number;

    /** Количество повторных попыток при ошибках (по умолчанию: 5) */
    retries?: number;

    /** Максимальное количество запросов в секунду (по умолчанию: 5) */
    maxRPS?: number;

    /** Прокси-сервер (строка URL или объект конфигурации) */
    proxy?: string | AxiosProxyConfig;

    /** Кастомный эндпоинт API */
    endpoint?: string;
}

Примеры инициализации

// Базовая инициализация
const sdk = YooKassa({
    shop_id: '123456',
    secret_key: 'test_secret_key',
});

// С отладкой и кастомными настройками
const sdk = YooKassa({
    shop_id: '123456',
    secret_key: 'live_secret_key',
    debug: true,
    timeout: 10000, // 10 секунд
    retries: 3, // 3 повтора
    maxRPS: 10, // 10 запросов в секунду
});

// С прокси (строка)
const sdk = YooKassa({
    shop_id: '123456',
    secret_key: 'live_secret_key',
    proxy: 'http://user:[email protected]:8080',
});

// С прокси (объект)
const sdk = YooKassa({
    shop_id: '123456',
    secret_key: 'live_secret_key',
    proxy: {
        host: 'proxy.example.com',
        port: 8080,
        auth: { username: 'user', password: 'password' },
    },
});

Кэширование инстансов

SDK автоматически кэширует инстансы по shop_id. Это позволяет:

• Переиспользовать соединения
• Работать с несколькими магазинами одновременно

// Оба вызова вернут один и тот же инстанс
const sdk1 = YooKassa({ shop_id: '123', secret_key: 'key1' });
const sdk2 = YooKassa({ shop_id: '123', secret_key: 'key1' });
console.log(sdk1 === sdk2); // true

// Разные магазины — разные инстансы
const shop1 = YooKassa({ shop_id: '111', secret_key: 'key1' });
const shop2 = YooKassa({ shop_id: '222', secret_key: 'key2' });

// Принудительное создание нового инстанса
const newSdk = YooKassa({ shop_id: '123', secret_key: 'new_key' }, true);

// Очистка кэша
import { clearYooKassaCache } from 'yookassa-api-sdk';
clearYooKassaCache('123'); // Удалить конкретный магазин
clearYooKassaCache(); // Очистить весь кэш

Платежи

Создание платежа

import { CurrencyEnum } from 'yookassa-api-sdk';

const payment = await sdk.payments.create({
    amount: {
        value: '100.00',
        currency: CurrencyEnum.RUB,
    },
    confirmation: {
        type: 'redirect',
        return_url: 'https://example.com/return',
    },
    capture: true,
    description: 'Заказ №123',
    receipt: {
        customer: { email: '[email protected]' },
        items: [
            {
                description: 'Товар',
                quantity: 1,
                amount: { value: '100.00', currency: CurrencyEnum.RUB },
                vat_code: 1,
            },
        ],
    },
    metadata: {
        order_id: '123',
    },
});

Документация по созданию платежа

Получение информации о платеже

const payment = await sdk.payments.load('payment_id');
console.log(payment.status); // pending, waiting_for_capture, succeeded, canceled

Документация

Список платежей

const payments = await sdk.payments.list({
    created_at: { gte: '2024-01-01T00:00:00.000Z' },
    status: 'succeeded',
    limit: 50,
});

Документация

Подтверждение платежа

const payment = await sdk.payments.capture('payment_id');

Документация

Отмена платежа

const payment = await sdk.payments.cancel('payment_id');

Документация

Возвраты

Создание возврата

const refund = await sdk.refunds.create({
    payment_id: 'payment_id',
    amount: {
        value: '50.00',
        currency: CurrencyEnum.RUB,
    },
});

Документация

Получение информации о возврате

const refund = await sdk.refunds.load('refund_id');

Документация

Список возвратов

const refunds = await sdk.refunds.list({
    payment_id: 'payment_id',
    limit: 10,
});

Документация

Чеки

Создание чека

const receipt = await sdk.receipts.create({
    type: 'payment',
    payment_id: 'payment_id',
    customer: {
        email: '[email protected]',
    },
    items: [
        {
            description: 'Товар',
            quantity: 1,
            amount: { value: '100.00', currency: CurrencyEnum.RUB },
            vat_code: 1,
        },
    ],
    send: true,
});

Документация

Получение информации о чеке

const receipt = await sdk.receipts.load('receipt_id');

Документация

Список чеков

const receipts = await sdk.receipts.list({
    payment_id: 'payment_id',
});

Документация

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

SDK возвращает унифицированный формат ответа:

try {
    const payment = await sdk.payments.create({ ... })
    // Успех
} catch (error) {
    // YooKassaErr содержит:
    // - error.name — код ошибки (например, 'invalid_request')
    // - error.message — описание ошибки
    // - error.id — идентификатор запроса
    console.error(error.name, error.message)
}

Типы ошибок

| Код | Описание | | ----------------------- | ----------------------- | | invalid_request | Неверный запрос | | invalid_credentials | Неверные учётные данные | | forbidden | Доступ запрещён | | not_found | Объект не найден | | too_many_requests | Превышен лимит запросов | | internal_server_error | Ошибка сервера | | NETWORK_ERROR | Сетевая ошибка | | ECONNABORTED | Таймаут запроса |

Справочник методов

Payments

| Метод | Описание | | -------------- | ----------------------- | | create(data) | Создание платежа | | load(id) | Получение платежа по ID | | list(filter) | Список платежей | | capture(id) | Подтверждение платежа | | cancel(id) | Отмена платежа |

Refunds

| Метод | Описание | | -------------- | ------------------------ | | create(data) | Создание возврата | | load(id) | Получение возврата по ID | | list(filter) | Список возвратов |

Receipts

| Метод | Описание | | -------------- | -------------------- | | create(data) | Создание чека | | load(id) | Получение чека по ID | | list(filter) | Список чеков |

Автор

Aleksey Aleksyuk (@awardix)

Благодарности

Этот проект является форком yookassa-sdk от Dmitriy (@Mityayka1). Спасибо за оригинальную реализацию!

Лицензия

MIT