yookassa-sbp
Skill0 starsChanged 32 days agoMITView on GitHub
Интеграция приёма оплаты ЮKassa и СБП в код — создание платежа (POST /v3/payments, payment_method_data sbp, Idempotence-Key), страница оплаты, вебхук payment.succeeded с проверкой IP и статуса, чек 54-ФЗ, возвраты, тестовый магазин; скрипт scripts/yookassa-sbp.mjs для проверки. Применяй, когда просят «подключить ЮKassa», «оплату по СБП», «принять платёж в приложении / боте / на сайте», «вебхук оплаты».
- Reads credentials
- Sends data out
In this repository60 other files it gives its agents.
- skills/universal/vercel-composition-patterns/AGENTS.mdAGENTS.md
- skills/universal/vercel-react-best-practices/AGENTS.mdAGENTS.md
- frontend-designSkill
- internal-commsSkill
- mcp-builderSkill
- skill-creatorSkill
- theme-factorySkill
- webapp-testingSkill
- dsh-error-handlingSkill
- dsh-find-simplificationsSkill
- dsh-trim-cot-leakageSkill
- record-browser-gifSkill
- glm-master-skillSkill
- glmocr-sdkSkill
- glmv-doc-based-writingSkill
- glmv-prd-to-appSkill
- glmv-prompt-genSkill
- glmv-resume-screenSkill
- glmv-web-replicationSkill
- cli-creatorSkill
- define-goalSkill
- gh-address-commentsSkill
- gh-fix-ciSkill
- jupyter-notebookSkill
- linearSkill
- migrate-to-codexSkill
- openai-docsSkill
- playwrightSkill
- security-best-practicesSkill
- security-ownership-mapSkill
- security-threat-modelSkill
- vercel-deploySkill
- amocrm-followupSkill
- avito-repliesSkill
- bitrix24-leadsSkill
- ozon-questionsSkill
- ru-legal-docsSkill
- tkbk-setupSkill
- tz-from-chatSkill
- wb-reviewsSkill
- yandex-market-stockSkill
- api-and-interface-designSkill
- brainstormingSkill
- code-review-and-qualitySkill
- debugging-and-error-recoverySkill
- documentation-and-adrsSkill
- executing-plansSkill
- performance-optimizationSkill
- planning-and-task-breakdownSkill
- requesting-code-reviewSkill
- security-and-hardeningSkill
- systematic-debuggingSkill
- test-driven-developmentSkill
- using-git-worktreesSkill
- vercel-composition-patternsSkill
- vercel-react-best-practicesSkill
- verification-before-completionSkill
- web-design-guidelinesSkill
- writing-guidelinesSkill
- writing-plansSkill
The file
Files
Оплата ЮKassa и СБП в коде
Скил ведёт разработчика по интеграции ЮKassa от тестового магазина до боевого вебхука. Логика одна для сайта, Telegram-бота и мобильного приложения: создать платёж на сервере → отправить пользователя на оплату → узнать результат по вебхуку → проверить его → выдать товар.
Когда применять
- «Подключи ЮKassa / СБП», «добавь оплату картой и по СБП», «сделай кнопку оплаты в боте».
- «Напиши обработчик вебхука ЮKassa», «почему платёж висит в pending», «сделай возврат».
Что нужно
| Что | Откуда |
YOOKASSA_SHOP_ID | Кабинет ЮKassa → Интеграция → Ключи API → shopId |
YOOKASSA_SECRET_KEY | там же, секретный ключ. Для разработки — тестовый магазин (ключ начинается с test_) |
| HTTPS-адрес для вебхука | порт 443 или 8443; локально — туннель |
Ключи кладём в переменные окружения / секреты сервера. В код, репозиторий, логи и чат — никогда. Секретный ключ даёт право создавать возвраты, то есть выводить деньги: утечка = прямые убытки.
Факты API, которые надо знать
- База:
https://api.yookassa.ru/v3/. Аутентификация: HTTP BasicshopId:secretKey. - Каждый
POST— с заголовкомIdempotence-Key(UUID v4, свой на каждую попытку одного и того же действия). Повтор с тем же ключом вернёт тот же результат, а не второй платёж. - Сумма — строка с двумя знаками:
"100.00", валютаRUB.description— до 128 символов, видна покупателю. capture: true— одностадийный платёж (деньги списываются сразу). СБП двухстадийный не поддерживает.- Способ оплаты:
payment_method_data: {"type": "sbp"}— только СБП; безpayment_method_data— покупатель выберет сам на странице ЮKassa (карта, СБП, SberPay …, по настройкам магазина). - Подтверждение:
confirmation: {"type": "redirect", "return_url": "…"}→ в ответеconfirmation.confirmation_url— страница ЮKassa (на десктопе QR для СБП, на телефоне — список банков). Для своей формы естьembedded(виджет) и мобильные SDK. metadata— до 16 пар ключ-значение: положиorder_id,user_id, они вернутся в вебхуке.- Статусы:
pending→ (waiting_for_capture) →succeededилиcanceled. СБП-платёж живёт 1 час. Лимит СБП: 1 ₽ – 700 000 ₽. - Вебхук:
POSTна ваш URL с телом{"type": "notification", "event": "payment.succeeded", "object": {…платёж…}}. События включаются в кабинете (Интеграция → HTTP-уведомления):payment.succeeded,payment.canceled,payment.waiting_for_capture,refund.succeeded. Ответить надоHTTP 200, иначе ЮKassa повторяет 24 часа. - Возврат:
POST /v3/refundsс{"payment_id": "…", "amount": {"value": "…", "currency": "RUB"}}, тоже сIdempotence-Key. СБП возвращает полностью и частично. - Чек по 54-ФЗ (если магазин использует облачную кассу через ЮKassa): в платёж добавляется
receiptсcustomer(emailилиphone) иitems(description,quantity,amount,vat_code,payment_subject,payment_mode). Без него платёж с включённой фискализацией отклоняется.
Порядок интеграции
- Тестовый магазин. Получи у пользователя тестовые shopId и ключ (или попроси создать тестовый магазин в
кабинете). Проверь связь:
node scripts/yookassa-sbp.mjs create 10 "Тест" --return-url https://example.com/ok. - Создание платежа на сервере. Эндпоинт
POST /api/payв приложении пользователя: принимаетorder_id, считает сумму на сервере (не доверяй сумме из клиента), создаёт платёж, сохраняетpayment.idрядом с заказом со статусомpending, отдаёт клиентуconfirmation_url. - Отправка на оплату. Сайт — редирект или кнопка; Telegram-бот — inline-кнопка с
confirmation_url; приложение — открыть ссылку (или SDK). - Вебхук. Эндпоинт
POST /api/yookassa/webhook:- принять JSON, ответить
200быстро (обработку — после ответа или в очереди); - проверить IP отправителя по списку ЮKassa (
185.71.76.0/27,185.71.77.0/27,77.75.153.0/25,77.75.156.11,77.75.156.35,77.75.154.128/25,2a02:5180::/32) — за прокси братьX-Forwarded-Forтолько если прокси ваш; - не верить телу: взять
object.idи запроситьGET /v3/payments/{id}— статус из этого ответа и есть истина; - сверить
amount.valueиmetadata.order_idс заказом в базе; - идемпотентно: если заказ уже
paid— ничего не делать; - только теперь выдать товар / зачислить баланс / отправить сообщение в бот.
- принять JSON, ответить
- Запасной путь. Страница
return_urlне означает оплату: на ней показывай статус из своей базы, а если вебхук ещё не пришёл — запросиGET /v3/payments/{id}сам (илиnode scripts/yookassa-sbp.mjs wait <id>). - Возвраты и отмены. Отдельный серверный эндпоинт для админа;
refund.succeededв вебхуке → пометить заказ. - Боевой режим. Заменить ключи на боевые, включить события в кабинете на боевой URL, провести платёж на минимальную сумму и возврат, проверить чек (если есть касса).
Пример: создание платежа (Node, без SDK)
import { randomUUID } from "node:crypto";
export async function createPayment({ amountRub, description, orderId, returnUrl, sbpOnly = false }) {
const auth = Buffer.from(`${process.env.YOOKASSA_SHOP_ID}:${process.env.YOOKASSA_SECRET_KEY}`).toString("base64");
const body = {
amount: { value: amountRub.toFixed(2), currency: "RUB" },
capture: true,
description: description.slice(0, 128),
confirmation: { type: "redirect", return_url: returnUrl },
metadata: { order_id: String(orderId) },
...(sbpOnly ? { payment_method_data: { type: "sbp" } } : {}),
};
const res = await fetch("https://api.yookassa.ru/v3/payments", {
method: "POST",
headers: { Authorization: `Basic ${auth}`, "Idempotence-Key": randomUUID(), "Content-Type": "application/json" },
body: JSON.stringify(body),
});
if (!res.ok) throw new Error(`YooKassa ${res.status}: ${await res.text()}`);
const p = await res.json(); // { id, status: "pending", confirmation: { confirmation_url } }
return { paymentId: p.id, url: p.confirmation.confirmation_url };
}(toString("base64") здесь — стандартная кодировка HTTP Basic, не обфускация.)
Пример: вебхук (Express)
app.post("/api/yookassa/webhook", express.json(), async (req, res) => {
res.sendStatus(200); // confirm receipt first; YooKassa retries for 24 h otherwise
const { event, object } = req.body ?? {};
if (!event?.startsWith("payment.") || !object?.id) return;
const payment = await getPayment(object.id); // GET /v3/payments/{id} with the same Basic auth
const order = await db.orders.findByPaymentId(payment.id);
if (!order || order.status === "paid") return;
if (payment.status === "succeeded" && payment.amount.value === order.amount && payment.metadata?.order_id === order.id) {
await db.orders.markPaid(order.id, payment);
await fulfil(order);
} else if (payment.status === "canceled") {
await db.orders.markCanceled(order.id, payment.cancellation_details?.reason);
}
});Python: пакет yookassa (Configuration.account_id, Configuration.secret_key, Payment.create(body, idempotence_key)),
логика та же.
Скрипт для проверки
node scripts/yookassa-sbp.mjs create 10 "Заказ 1" --return-url https://example.com/ok [--sbp]
node scripts/yookassa-sbp.mjs get <payment_id>
node scripts/yookassa-sbp.mjs wait <payment_id> # опрашивает до succeeded/canceled, до 10 минут
node scripts/yookassa-sbp.mjs refund <payment_id> 10Типичные ошибки
| Симптом | Причина | Решение |
401 | неверный shopId/ключ или ключ другого магазина (тест/бой) | проверить пару ключей |
400 invalid_request «receipt» | у магазина включена касса, а чека нет | добавить receipt |
платёж canceled, cancellation_details.reason: payment_expired | покупатель не оплатил за час (СБП) | создать новый платёж |
| вебхук не приходит | не включены события, не HTTPS, не 443/8443, ответ не 200 | проверить настройки и логи |
| товар выдан дважды | обработчик не идемпотентен | проверять статус заказа до выдачи |
| товар выдан без денег | поверили телу вебхука | всегда GET /v3/payments/{id} |
Ссылки
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

