Loaded automatically when its description matches the active task. Read only the section you need, then follow the link to the relevant reference file for full detail.
Use this skill when
Building a CloudPayments checkout — embedding the JS widget (cp.CloudPayments) or calling REST API directly
Migrating from a sandbox key to production — keys, IP whitelist (notification gates), test cards
Do not use this skill when
Task is YooKassa / ЮKassa / Tinkoff / Stripe / Robokassa / Tochka payment integration — use the respective skill
Task is purely about 54-ФЗ fiscalization with another OFD/provider — use fiscalization (cascade marker)
Task is generic webhook handling without HMAC signature verification — use nodejs (webhook patterns) instead
Task is Telegram Stars / XTR / Telegram Payments 2.0 native — use telegram-bot (Stars are NOT CloudPayments)
Task is wallet-style consumer P2P transfers — CloudPayments is a merchant gateway, not a wallet
Purpose
CloudPayments is one of the dominant Russian payment gateways (alongside ЮKassa и Tinkoff Касса), used heavily by Russian e-commerce, subscription services, fintech, and donation platforms. Its differentiator: a strong customizable JS widget for in-page checkout (no redirect), full-featured REST API for server-side flows, native СБП / Tinkoff Pay / SberPay support, and built-in 54-ФЗ fiscal receipt generation through the merchant's OFD account.
This skill covers the merchant integration path end-to-end: widget initialization, two- vs one-step payments, tokenization for recurrent billing, the six webhook gates (Check is the most important — it gates the charge), HMAC signature verification, error code semantics (CardExpired, InsufficientFunds, Need3ds, decline reasons), 54-ФЗ receipt payload shape, СБП-specific behavior, and recurrent subscription primitives. The skill owns the payment-domain knowledge; the runtime skill (nodejs, fastify, hono) owns the HTTP plumbing.
CloudPayments is a Russian MoR (Merchant of Record); business operates under Russian tax law (НДС, ОСН/УСН), uses ЦБ official exchange rates for FX, and reports to OFD (Operator Fiscal Data) per 54-ФЗ.
Capabilities
Widget integration (in-page checkout)
Embed https://widget.cloudpayments.ru/bundles/cloudpayments.js, instantiate cp.CloudPayments({ publicId }), call widget.pay(scheme, options, callbacks). Two payment schemes: 'charge' (one-step, money debited immediately) and 'auth' (two-step, hold then capture). Widget handles card UI, 3-D Secure ACS redirect, СБП QR/deep-link generation, and returns the transaction outcome via callbacks (onSuccess, onFail, onComplete). Pass data to embed metadata that flows through to webhook notifications.
Base URL: https://api.cloudpayments.ru. Auth: HTTP Basic with publicId (username) + apiSecret (password). Key endpoints: /payments/cards/charge (charge by raw card cryptogram from widget tokenization), /payments/tokens/charge (charge by saved token), /payments/cards/auth (hold), /payments/confirm (capture), /payments/void (release hold), /payments/refund (refund), /payments/get (fetch state), /payments/find (by InvoiceId). All requests are JSON POST. Amounts in major units (rubles, not kopecks), strings allowed, Currency: "RUB".
CloudPayments calls merchant endpoints for: Check (gate before charge — return {code: 0} to allow, anything else to reject), Pay (success — must idempotently mark order paid), Confirm (two-step capture committed), Fail (decline reason in Reason/ReasonCode), Refund (refund executed), Recurrent (subscription state change). Each request body is x-www-form-urlencoded or JSON depending on dashboard setting. Response shape: {code: 0} for success, non-zero rejects (Check) or signals retry. Idempotency by TransactionId.
Every webhook request carries a Content-HMAC header (legacy: X-Content-HMAC) — HMAC-SHA256 of the raw request body using the merchant's API Secret as the key, base64-encoded. Verify with crypto.timingSafeEqual to prevent timing attacks. Read the raw body BEFORE any JSON parsing — body-parser middleware that consumes the stream breaks signature math. Whitelist CloudPayments IPs at the firewall/Angie layer as defence-in-depth (published in dashboard).
After the first charge (or 1 RUB auth probe), CloudPayments returns a Token — a card surrogate stored on their side. Use /payments/tokens/charge for server-driven rebill. For automated subscriptions: /subscriptions/create defines a plan (Interval=Month/Week/Day, Period, MaxPeriods, Amount, StartDate); CloudPayments fires Recurrent webhook on each cycle. /subscriptions/update and /subscriptions/cancel manage lifecycle. PCI scope stays at CloudPayments — merchant never sees raw PAN.
To issue a fiscal receipt (чек) per Federal Law 54-ФЗ, attach a CustomerReceipt object to the charge request (or include via widget data). Shape: { Items: [{Label, Price, Quantity, Amount, Vat, Method, Object}], taxationSystem: 0..5, email | phone, isBso, AgentSign, AmountsHelp }. Vat values: null (НДС не облагается) | 0 | 10 | 20. Method (sign of method of calculation): 1..7. Object (sign of subject of calculation): 1..13. CloudPayments transmits to OFD; merchant gets fiscal data in Pay webhook.
Two-step auth not yet captured → /payments/void (releases hold, no money moved). Captured/single-step charge → /payments/refund with Amount (full or partial). Refunds also require a CustomerReceipt if the original payment had one — chequed return per 54-ФЗ. Refund triggers Refund webhook. Multiple partial refunds allowed up to original Amount.
Merchant integration is PCI DSS SAQ A-EP (widget) or SAQ A (full hosted) — no raw PAN ever touches merchant servers. Cryptograms from widget are one-time. API Secret is server-only — never ship to browser. Use HTTPS-only callbacks, restrict webhook source IPs, verify HMAC, log replays without persisting secrets. Test mode uses a separate test API key + magic test card numbers (e.g., 4242 4242 4242 4242, 5555 5555 5555 4444).
Test environment uses identical API at https://api.cloudpayments.ru with test-mode keys. Test cards in the docs trigger specific outcomes (success, decline, 3-D Secure required, expired). Webhook testing: use a tunneling tool (ngrok / cloudflared) to expose local handlers, or test against staging server with public hostname. Always test the Check webhook returning non-zero — easy to forget the rejection path.
How to use: open only the topic file relevant to the current task. Webhook work → webhooks.md + security-pci.md. Subscription work → recurring-subscriptions.md. New integration → api-overview.md + payments-flow.md.
