🎯 Version Requirements (May 2026)
Primary pins:
- Node.js:
24.x (Active LTS)
- TypeScript:
6.0.x
Source of truth: STACK_VERSIONS.md — verified 2026-05-16
Usage
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
- Implementing server-to-server charge:
/payments/cards/charge, /payments/tokens/charge, two-step auth (/payments/cards/auth + /payments/confirm)
- Setting up the four merchant webhooks: Check / Pay / Confirm / Fail / Refund / Recurrent
- Verifying
Content-HMAC (or X-Content-HMAC) header on webhook requests — HMAC-SHA256 with API Secret over raw body, base64-encoded
- Building recurrent payments: subscription plans (
/subscriptions/create, /subscriptions/update, /subscriptions/cancel) or manual rebill via saved token
- Generating 54-ФЗ fiscal receipts (
CustomerReceipt object — Items, taxationSystem, email/phone, Vat, method, object)
- Handling Russian payment methods: bank card, СБП (Система быстрых платежей), Tinkoff Pay, SberPay, MIR Pay
- Working with refund flow (
/payments/refund, /payments/void) and partial refunds
- Integrating CloudPayments with a Telegram bot (Telegram Stars is separate — this is the merchant Mini App / WebApp flow)
- Resolving 3-D Secure flows — handling
Need3ds responses and ACS redirect
- 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.
Full reference: references/api-overview.md, references/payments-flow.md
REST API — direct charges
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".
Full reference: references/api-overview.md
Webhooks — six gates
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.
Full reference: references/webhooks.md
HMAC signature verification
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).
Full reference: references/webhooks.md, references/security-pci.md
Recurrent payments & tokenization
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.
Full reference: references/recurring-subscriptions.md
54-ФЗ fiscalization (CustomerReceipt)
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.
Full reference: references/fiscalization-54fz.md
Refunds and voids
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.
Full reference: references/refunds.md
Security & PCI scope
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).
Full reference: references/security-pci.md
Testing
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.
Full reference: references/testing.md
Behavioral Traits
- Reads the raw request body BEFORE JSON parsing on webhook routes — uses Fastify's
addContentTypeParser or Express raw body middleware
- Verifies
Content-HMAC with crypto.timingSafeEqual against the computed base64 digest, treats X-Content-HMAC as legacy fallback
- Stores
TransactionId (CloudPayments unique txn ID) AND merchant InvoiceId — uses TransactionId as the idempotency key
- Treats Check webhook as a gate: validates internal order state, returns
{code: 0} only when order is in pending_payment AND amount/currency match
- Never trusts client-supplied amount on the
Pay webhook — recomputes from the order in the DB and verifies the match
- Stores
Token securely keyed to a user, NEVER to a single order — same token re-used for future rebills
- Sends
CustomerReceipt.email or CustomerReceipt.phone (one is required) per 54-ФЗ
- Logs
Reason AND ReasonCode on Fail webhook for support escalation
- Uses one publicId per environment (test vs prod) and rotates API Secret if exposed
- Validates webhook payload shape with Zod schema before downstream business logic
Important Constraints
- NEVER skip HMAC verification on webhook handlers — public endpoint without auth lets anyone forge
Pay calls
- NEVER parse JSON body before computing HMAC — middleware that buffers/transforms the stream invalidates the signature
- NEVER store raw PAN, CVV, or card cryptogram — keep PCI scope at SAQ A-EP via widget
- NEVER trust amount/currency from the webhook payload alone — cross-check against the order record by
InvoiceId
- NEVER hardcode API Secret in source; load from env, rotate on leak
- NEVER use the same
InvoiceId twice — CloudPayments doesn't enforce uniqueness server-side but you must enforce it client-side for reconciliation
- ALWAYS implement Check webhook idempotently — CloudPayments may retry on timeout (>30s)
- ALWAYS return HTTP 200 with
{code: 0} from successful Pay webhook — non-200 triggers retries
- ALWAYS attach
CustomerReceipt on refunds if the original payment had one (54-ФЗ requirement)
- ALWAYS test the decline path AND the 3-D Secure interrupted path before production
Related Skills
90%-filter applied — mainstream 2026 choices used in >30% of Russian e-commerce / SaaS projects.
Runtime
- ✓
nodejs — Node 24 (primary runtime for webhook receiver and API caller)
- ✓
typescript — TS 5.9 (default for new projects; types for SDK + payload schemas)
Web frameworks (own the request lifecycle)
- ✓
nextjs — Next.js 16 (App Router route handler for widget + webhook receiver; React widget mount)
- ✓
react — React 19 (widget embedded into a React form)
- ✓
fastify — Fastify 5 (raw-body parser pattern is canonical)
- ✓
hono — Hono 4 (raw body via c.req.raw.text() for HMAC)
Validation
- ✓
zod — Zod 4 (validate webhook payloads, widget options, CustomerReceipt shape)
Deploy & ops
- ✓
linux-sysadmin — Ubuntu 24.04 + Angie/Nginx (TLS termination, IP allowlist for webhook source)
Domain app
- ✓
telegram-bot — Telegram bots accepting Russian-card payments via CloudPayments Widget (Mini App)
Persistence & queues
- ✓
prisma — Prisma 7 (order/transaction persistence; idempotency tracking)
- ✓
redis — Redis 8 (idempotency cache for TransactionId, dedupe webhook retries)
- ✓
bullmq — BullMQ 5 (retry queue for failed downstream actions after Pay)
API Reference
Domain-specific references (Pattern 2) — load only what's relevant:
| Topic | File |
|---|
| API overview — base URL, auth, endpoints, response shape, error codes | references/api-overview.md |
| Payment flow — widget vs REST, one-step vs two-step, 3-D Secure, СБП, Tinkoff Pay | references/payments-flow.md |
| Webhooks — Check / Pay / Confirm / Fail / Refund / Recurrent, payload shape, response codes | references/webhooks.md |
| 54-ФЗ fiscalization — CustomerReceipt, taxationSystem, Vat/Method/Object enums, OFD flow | references/fiscalization-54fz.md |
Recurring & subscriptions — tokenization, /subscriptions/*, manual rebill, Recurrent webhook | references/recurring-subscriptions.md |
| Refunds — void vs refund, partial refund, 54-ФЗ on refund | references/refunds.md |
| Security & PCI scope — HMAC verification, IP allowlist, key rotation, test cards | references/security-pci.md |
| Testing — sandbox keys, test cards, tunneling, fixture payloads | references/testing.md |
| Recommended defaults — HMAC timing-safe, idempotency window, HTTP retry, 3DS timeout, 54-ФЗ enums | references/recommended-defaults.md |
| Troubleshooting — symptom-indexed: HMAC fails, Check rejected, Pay missing, duplicates, 3DS stuck, recurring fails, 54-ФЗ rejected, sandbox/prod confusion, IP drift | references/troubleshooting.md |
| Eval cases — routing tests (positive + negative + edge) | references/eval-cases.md |
Templates
Examples
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.
