YooKassa SDK

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

A modern TypeScript SDK for integrating with the YooKassa API. It covers payments, refunds, receipts, webhooks, and more.

Features

• 🚀 Full TypeScript support — types aligned with the YooKassa OpenAPI paths covered by this SDK
• 🔄 Automatic retries — exponential backoff on network failures
• 🔑 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 — runs on Node.js, Bun, and other runtimes

Installation

npm install @webzaytsev/yookassa-ts-sdk

Developing this repository

corepack enable
pnpm install
pnpm run check
pnpm run build

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 and instance caching | | Payments | Create, capture, cancel, and list payments | | Refunds | Create and list refunds | | Payouts | Create, load, and list payouts (gateway credentials) | | Deals | Safe Deal: create, load, and list | | Webhooks | Webhook management and incoming notifications | | Error Handling | Error codes and retries | | API Reference | TypeScript types, interfaces, and enums |

API Reference

Payments

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

Refunds

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

Receipts

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

Payouts

Use the payout gateway shop_id and secret_key from your YooKassa dashboard (payouts).

| Method | Description | | --- | --- | | sdk.payouts.create(data, idempotenceKey?) | Create a payout | | sdk.payouts.load(id) | Get a payout by ID | | sdk.payouts.list(filter?) | List payouts (supports succeeded_at, payout_destination.type, and more) | | sdk.payouts.search(filter?) | Search payouts by metadata and created_at (last 3 months) |

SBP banks

| Method | Description | | --- | --- | | sdk.sbpBanks.list() | List FPS (SBP) participant banks |

Saved payment methods

| Method | Description | | --- | --- | | sdk.paymentMethods.create(data, idempotenceKey?) | Create a saved payment method (e.g. bank card binding) | | sdk.paymentMethods.load(id) | Get a saved payment method by ID |

Personal data (payouts)

| Method | Description | | --- | --- | | sdk.personalData.create(data, idempotenceKey?) | Create a personal data object | | sdk.personalData.load(id) | Get personal data by ID |

Deals (Safe Deal)

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

Invoices

| Method | Description | | --- | --- | | sdk.invoices.create(data, idempotenceKey?) | Create an invoice | | sdk.invoices.load(id) | Get an invoice by ID |

Webhooks

CRUD methods (create, list, delete) require an OAuth token. verify* methods work with the standard API key.

| Method | Description | | --- | --- | | sdk.webhooks.create(data, idempotenceKey?) | Create a webhook (OAuth) | | sdk.webhooks.list() | List webhooks (OAuth) | | sdk.webhooks.delete(id) | Delete a webhook (OAuth) | | sdk.webhooks.verify(body) | Parse and re-fetch a notification (payment or refund) | | sdk.webhooks.verifyPayment(body) | Parse and re-fetch a payment notification | | sdk.webhooks.verifyRefund(body) | Parse and re-fetch a refund notification |

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

• [x] Payouts — create, load, list, search
• [x] Deals, personal data, SBP banks, invoices, saved payment methods — see API tables above
• [ ] Self-Employed — dedicated scenarios beyond generic payout types

Maintainer

WEBzaytsev (@WEBzaytsev)

Acknowledgements

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

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

License

MIT