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.

Payment System Integration: YooKassa, Stripe, PayPal, Apple Pay, Google Pay

Conversion dropped by 12% immediately after the redesign. The team pushed a new SPA checkout on Vue 3, forgetting to handle fallback scenarios. Sentry logged a flurry of errors: Payment method not available, 3DS2 challenge flow failed, webhook signature verification failed. Users abandoned carts at the payment method selection stage. Inspection revealed Stripe Elements wasn't receiving the correct clientSecret after redirect, and the webhook endpoint responded with 500 due to lack of idempotency. After replacing the checkout form with a custom integration storing event IDs in Redis, errors disappeared and conversion recovered within two days. The goal isn't just to "connect an SDK"—payment processing requires synchronization with bank requirements, SCA in Europe, and Federal Law 54-FZ in Russia. Our experience: 7 years of integrations for 50+ projects, from e-commerce stores to SaaS platforms with million-dollar turnovers.

What's Included in Turnkey Work

• Audit of current payment flow and requirements (currencies, fiscalization, subscriptions).
• Provider selection based on geography and business model.
• Backend integration (Laravel/Node.js/Go) with webhook handling, idempotency, and retries.
• Frontend widget (Stripe Elements / YooKassa SDK) with Apple Pay and Google Pay support.
• Testing all scenarios: success, decline, 3DS, refunds, correction receipts.
• Monitoring of first transactions and documentation.

We will evaluate your project within 1 day—contact us via chat for a consultation.

Provider Comparison: Which to Choose

Stripe wins on flexibility: 135+ currencies vs. YooKassa's single currency. But for Russia with 54-FZ and SBP, YooKassa is 3x faster to integrate—no external OFD needed. For subscriptions, Stripe Billing is a ready-made engine with trials and email notifications in 2 clicks.

How to Choose the Right Provider?

Three key points. Where do your clients live? Only Russia → YooKassa; globally → Stripe. Do you need 54-FZ fiscalization? Yes → YooKassa; otherwise Stripe + cloud OFD. Do you plan subscriptions? Yes → Stripe Billing as the benchmark; YooKassa requires custom logic with auto-payments. Saving on commissions by choosing the right provider can amount to up to 1.5% of turnover. For a project with 2 million RUB per month, that's 360,000 RUB per year.

Where the Real Difficulties Lie

Setting up a test mode takes an hour. Properly handling all scenarios takes weeks.

Webhook reliability. A webhook may not arrive—server unavailable, timeout, network issues. The provider retries with exponential backoff (Stripe up to 3 days). The handler must be idempotent: if payment.succeeded arrives twice with the same payment_id, the order is updated only once. This is implemented by storing event IDs in Redis with a TTL.

3DS2 and redirect flow. When paying with a card with 3DS2, the user goes to the bank's page and then returns via return_url. During this time, the session may expire or the cart may be cleared. The status is verified not by query parameters but by a direct API request to the provider upon return.

Partial refunds and receipts. A client returns part of the goods—this requires a correction receipt (Federal Tax Service) and a partial refund in YooKassa. Stripe natively supports partial_refund. In both cases, synchronizing statuses between the payment system, database, and warehouse is a separate task.

Currency limitations. YooKassa only handles rubles. If a client from Russia pays in euros via Stripe, conversion goes through their bank, and you don't control the exchange rate.

Why Do Webhooks Require Idempotency?

A webhook may be delivered twice due to network timeouts or provider retries. Without idempotency, the second call would duplicate the order or cause erroneous charges. The solution is to store a unique event ID (e.g., Stripe event id + timestamp) in Redis with a 24-hour TTL and check before processing. If the ID already exists, return 200 without executing business logic. Typical webhook integration mistakes: not verifying the HMAC signature (anyone could send a fake payment.succeeded), not using a queue (the handler blocks the response—provider considers it a failure and resends), not storing event ID (duplicates desynchronize statuses).

How We Build the Integration

Architecture. We never store card data—only tokens from the provider. Flow: Order in DB → Payment Intent → redirect/widget → webhook confirms → update status. The source of truth is the status in the payment system.

For Laravel we use stripe/stripe-php or yookassa-sdk. Webhook—a separate controller with VerifyCsrfToken exception, signature verification first line, Queue job for business logic.

For Next.js/React—@stripe/stripe-js + @stripe/react-stripe-js. PaymentElement includes Apple/Google Pay automatically. Example:

const stripe = await stripePromise;
const { error } = await stripe.confirmPayment({
  elements,
  confirmParams: { return_url: 'https://example.com/order/thank-you' },
});

Testing. Stripe CLI: stripe listen --forward-to localhost:8000/webhook. Test cards for all scenarios (3DS, decline, insufficient funds). Cypress checkout flow test in CI—mandatory stability guarantee.

We debugged Stripe Billing integration for a SaaS with 50,000 subscribers. The issue was handling invoice.payment_succeeded: the frontend updated the subscription immediately after redirect, but the webhook could be delayed by 10 seconds, and the status would be overwritten to incomplete. Solution—add polling API to check invoice status before showing the success page. This reduced erroneous cancellations by 18%.

Process and Timeline

Audit → provider selection → backend → frontend → tests → deploy → monitoring.

Pricing is custom. Order integration and your checkout won't crash on the next update.

Links:

• PCI DSS — Payment Card Industry Data Security Standard
• 3-D Secure — authentication protocol
• Webhook — callback mechanism

We guarantee: 7 years of experience, 50+ successful integrations. Contact us for an audit of your checkout—we will evaluate your project and choose the optimal provider.