Скилл ЮKassa

---
name: yookassa
description: Russian payment gateway integration using YooKassa. Use when creating payments, processing transactions, handling webhooks, managing refunds, or implementing Russian fiscalization via 54-FZ.
keywords: [payment, gateway, yookassa, russia, 54-fz, sbp]
---

# Yookassa Payment Gateway

## Quick Reference

| Concept | Details |
|---------|---------|
| **API Version** | v3 |
| **Base URL** | `https://api.yookassa.ru/v3` |
| **Auth** | Basic (shop_id:secret_key) |
| **Required Header** | `Idempotence-Key` (UUID v4, unique per operation) |
| **Primary SDK** | `@a2seven/yoo-checkout` |
| **Amount Format** | String with 2 decimals: `"100.00"` |
| **Currency** | `RUB` (primary), `USD`, `EUR` supported |

## When to Use

Use this skill when you need to:
- Create one-time or recurring payments
- Handle Russian payment methods (SBP, SberPay, YooMoney, T-Pay, Mir)
- Implement 54-FZ fiscalization (receipts)
- Process refunds and cancellations
- Handle async payment confirmation via webhooks
- Implement two-stage (hold + capture) payments
- Manage saved payment methods for returning customers

## Core Payment Flow

```
1. Create Payment → 2. Redirect User → 3. Webhook (status update) → 4. Verify → 5. Capture (if two-stage)
```

## SDK Quick Start

```typescript
import { YooCheckout } from '@a2seven/yoo-checkout';

const checkout = new YooCheckout({
  shopId: process.env.YOOKASSA_SHOP_ID!,
  secretKey: process.env.YOOKASSA_SECRET_KEY!,
});
```

## Critical Rules

1. **Always use idempotency keys** - Every create/capture/cancel/refund needs a unique `Idempotence-Key`
2. **Never trust client-side** - Always verify payment status server-side via API or webhooks
3. **Amount is a string** - `{ value: "100.00", currency: "RUB" }` not a number
4. **Webhooks require 200 response** - Return HTTP 200 within 10 seconds or Yookassa retries
5. **Verify webhook IPs** - Whitelist Yookassa IP ranges for security
6. **54-FZ receipts** - Required for Russian merchants; include `receipt` object with items