Package Exports

yookassa-api-sdk
yookassa-api-sdk/dist/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (yookassa-api-sdk) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

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:password@proxy.example.com: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: 'customer@example.com' },
        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: 'customer@example.com',
    },
    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