YooKassa SDK

README на русском | Documentation

Modern TypeScript SDK for YooKassa API integration. Supports payments, refunds, receipts, webhooks and more.

Features

• 🚀 Full TypeScript support — complete type definitions for all API entities
• 🔄 Automatic retries — exponential backoff on network errors
• 🔑 Idempotency — automatic Idempotence-Key generation
• 🌐 Proxy support — HTTP/HTTPS proxy configuration
• ⚡ Rate limiting — built-in request throttling
• 🕐 Timeouts — configurable request timeouts
• 📦 Instance caching — efficient connection reuse
• 🔧 Multi-runtime — works with Node.js, Bun, and other runtimes

Installation

npm install @webzaytsev/yookassa-ts-sdk

Quick Start

import { YooKassa } from '@webzaytsev/yookassa-ts-sdk';

const sdk = YooKassa({
    shop_id: 'your_shop_id',
    secret_key: 'your_secret_key',
});

// Create a payment
const payment = await sdk.payments.create({
    amount: { value: '100.00', currency: 'RUB' },
    confirmation: { type: 'redirect', return_url: 'https://example.com' },
    description: 'Order #1',
});

console.log(payment.confirmation.confirmation_url);

Documentation

| Section | Description | | --- | --- | | Getting Started | Configuration, instance caching | | Payments | Create, capture, cancel, list payments | | Refunds | Create and list refunds | | Receipts | Create and list receipts (54-FZ) | | Webhooks | Webhook management & incoming notifications | | Error Handling | Error codes, retries | | API Reference | TypeScript types, interfaces, enums |

API Reference

Payments

| Method | Description | | --- | --- | | sdk.payments.create(data, idempotenceKey?) | Create payment | | sdk.payments.load(id) | Get payment by ID | | sdk.payments.list(filter?) | List payments | | sdk.payments.capture(id, payload?, key?) | Capture payment | | sdk.payments.cancel(id, idempotenceKey?) | Cancel payment |

Refunds

| Method | Description | | --- | --- | | sdk.refunds.create(data, idempotenceKey?) | Create refund | | sdk.refunds.load(id) | Get refund by ID | | sdk.refunds.list(filter?) | List refunds |

Receipts

| Method | Description | | --- | --- | | sdk.receipts.create(data, idempotenceKey?) | Create receipt | | sdk.receipts.load(id) | Get receipt by ID | | sdk.receipts.list(filter?) | List receipts |

Webhooks (OAuth required)

| Method | Description | | --- | --- | | sdk.webhooks.create(data, idempotenceKey?) | Create webhook | | sdk.webhooks.list() | List webhooks | | sdk.webhooks.delete(id) | Delete webhook |

Shop (OAuth required)

| Method | Description | | --- | --- | | sdk.shop.info() | Get shop information |

Error Handling

import { YooKassaErr } from '@webzaytsev/yookassa-ts-sdk';

try {
    const payment = await sdk.payments.create({ ... });
} catch (error) {
    if (error instanceof YooKassaErr) {
        console.error(error.name);    // Error code
        console.error(error.message); // Error description
        console.error(error.id);      // Request ID
    }
}

Roadmap

• [ ] Payouts — disbursements to cards/wallets
• [ ] Deals — Safe Deal (escrow for marketplaces)
• [ ] Personal Data — payout recipient data
• [ ] Self-Employed — payouts to self-employed
• [ ] SBP Banks — list of banks for SBP

Maintainer

WEBzaytsev (@WEBzaytsev)

Acknowledgements

This project is a fork of yookassa-sdk by Aleksey Aleksyuk (@awardix).

Original project based on yookassa-sdk by Dmitriy (@Mityayka1). Thanks for the original implementation!

License

MIT