CloudPayments Integration: Widget to API with 54-FZ

Payment integration is a bottleneck where up to 15% of orders are lost. Buyers abandon their cart if the form redirects to an external site or loads slowly. CloudPayments solves this with an inline widget: the user never leaves the page. In one project — an electronics e‑commerce store with monthly turnover of 1.5 million RUB — switching from redirect to widget boosted conversion by 12%. The typical loss from abandoned carts before integration was 500,000 RUB per month. CloudPayments helps retain customers, and we have experience from 20+ projects. We guarantee stable operation and full fiscalization per 54-FZ.

How CloudPayments Increases Conversion

The CloudPayments widget is a popup form overlaid on your site. The script is ~180 KB and loads lazily. In our projects conversion increased by an average of 10% after switching from a redirect page. Comparing with Checkout (iframe), the widget delivers 5–7% more completed transactions because of fewer steps. This translates to an additional 200,000 RUB monthly revenue for a store with an average check of 3,000 RUB and 1,000 orders.

What Problems We Solve

• Conversion – the payment form stays on the site, eliminating redirects, which boosts LTV and reduces churn. Every extra step cuts off a portion of buyers. The widget minimizes these losses.
• Security – 3D Secure 2.0, PCI DSS Level 1 certification, card tokenization. CloudPayments undergoes annual security audits — you don't need to worry about storing sensitive data.
• Compliance – built-in online cash register with automatic receipt transmission to the OFD. All transactions comply with 54-FZ, eliminating fines for missing receipts.
• Flexibility – recurring payments for subscriptions, full/partial refunds, multi‑currency support. CloudPayments supports RUB, USD, EUR — you can accept payments from abroad.

How We Integrate CloudPayments

We use the widget as the fastest method (1–2 days) with higher conversion than iframe. For full UI customization we use the API (5–10 days, requires PCI DSS SAQ A‑EP). For typical tasks the widget is sufficient.

Widget vs API Customization

Widget Integration

<script src="https://widget.cloudpayments.ru/bundles/cloudpayments.js"></script> 

const pay = () => { const widget = new cp.CloudPayments({ language: 'ru-RU' }); widget.charge( { publicId: 'pk_xxxxxxxxxxxxxxxxxxxx', description: 'Order #12345', amount: 1500, currency: 'RUB', accountId: '[email protected]', invoiceId: 'order-12345', skin: 'mini', data: { orderId: 12345, }, }, (options) => { console.log('payment success', options); }, (reason, options) => { console.error('payment failed:', reason); }, ); }; 

publicId — the public key from your account dashboard. The secret key (apiSecret) must remain server‑side only, never exposed in the frontend.

How to Verify Webhook HMAC Signature

1. Receive the POST body from CloudPayments.
2. Compute HMAC SHA256 of the body using your secret key (apiSecret).
3. Compare the resulting signature with the Content-HMAC header.
4. If they don't match — return HTTP 403.
5. On match, process the payment status.

After payment, CloudPayments sends a POST to the URL specified in your account (section "Notifications"). The notification type is payment. Verification uses HMAC SHA256. For details see the official CloudPayments documentation.

public function handleWebhook(Request $request): Response { $hmac = base64_encode( hash_hmac('sha256', $request->getContent(), env('CP_API_SECRET'), true) ); if ($hmac !== $request->header('Content-HMAC')) { return response('Invalid signature', 403); } $data = $request->all(); if ($data['Status'] === 'Completed') { $orderId = $data['InvoiceId']; $amount = $data['Amount']; Order::where('id', $orderId) ->where('total', $amount) ->update(['status' => 'paid', 'transaction_id' => $data['TransactionId']]); } return response()->json(['code' => 0]); } 

If you return {"code": 13}, CloudPayments will retry the notification up to 10 times according to its schedule. This is useful for temporary database errors.

How to Configure Fiscalization per 54-FZ

CloudPayments has a built‑in online cash register. Receipt data is passed in the cloudPayments.customerReceipt parameter inside the widget's data object:

data: { cloudPayments: { customerReceipt: { Items: [ { label: 'Product 1', price: 1500.00, quantity: 1.0, amount: 1500.00, vat: null, method: 0, object: 1, }, ], taxationSystem: 1, email: '[email protected]', amounts: { electronic: 1500.00, advancePayment: 0.00, credit: 0.00, provision: 0.00, }, }, }, } 

For recurring payments without re‑entering card details, CloudPayments returns a Token in the first successful payment. You store it in your database and use it for subsequent charges:

$response = Http::withBasicAuth(env('CP_PUBLIC_ID'), env('CP_API_SECRET')) ->post('https://api.cloudpayments.ru/payments/tokens/charge', [ 'Amount' => 1500, 'Currency' => 'RUB', 'AccountId' => '[email protected]', 'Token' => $savedToken, 'InvoiceId' => 'order-12346', 'Description' => 'Automatic charge', ]); 

Refunds are performed via the API: provide the TransactionId and the partial refund amount. CloudPayments supports both full and partial refunds.

Work Stages

What’s Included in the Deliverable

• CloudPayments account configuration: domain, webhook, public/secret keys.
• Widget embedding with support for recurrences and fiscalization.
• Server‑side webhook with HMAC signature validation.
• Refund and tokenization integration.
• Documentation and staff training for the payment module.

Why Choose Us

• 5+ years of experience developing and integrating payment systems.
• 20+ successful projects with CloudPayments.
• Certified specialists.
• Post‑delivery support: debugging, enhancements, monitoring.

Contact us for a project assessment — we’ll choose the best integration option for your stack and budget. Get a consultation.