YooKassa Skill

Install

Copy the skill folder from github.com/gulivan/yookassa-skill into ~/.claude/skills/yookassa. Follow the SKILL.md rules and the examples folder when integrating YooKassa.

This is third-party code. Review the repository files before installing.

What it does

The skill is documentation only: a YooKassa REST API v3 reference and TypeScript examples using the @a2seven/yoo-checkout SDK. It covers the payment lifecycle, payment methods such as SBP, SberPay and Mir, webhook handling, refunds, 54-FZ fiscalization and retry strategies. SKILL.md lists key rules: an idempotency key per operation, server-side status checks and amounts as strings.

Who it is for. For TypeScript and Node.js developers adding YooKassa payments.

Example request

Add YooKassa order payment with a webhook and a 54-FZ receipt to my Express app

Limitations

The skill does not call the API; it only guides the agent in writing code. Examples are tied to the @a2seven/yoo-checkout SDK. The app needs YOOKASSA_SHOP_ID and YOOKASSA_SECRET_KEY.

How to disable. Remove the yookassa folder from the Claude Code skills directory.

Security check

• The skill contains only documentation and code examples

README in short

The README briefly describes a documentation-only Claude Code skill for the YooKassa payment gateway. It shows the structure: SKILL.md, references on auth, payment lifecycle, payment methods, webhooks, fiscalization and errors, plus four TypeScript examples. It lists the SDK dependencies and shop environment variables.

SKILL.md

---
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

Related