YuKassa Payment System Integration

YooKassa Payment System Integration

YooKassa is one of main payment gateways for Russian online stores. Accepts cards, YooMoney, SBP, Apple Pay, Google Pay, cash payments via terminals. Suitable for individuals (self-employed), LLCs, sole proprietors. Integration via REST API or ready SDK.

Integration Variants

Redirect (hosted form) — customer redirected to YooKassa page. Minimum code, maximum security — card data entered on payment system side. Suitable for most stores.

Embedded widget — JavaScript-widget embedded on order completion page. Customer doesn't leave site, but card data still processed by YooKassa. Requires payment_token from backend.

API integration — full control via REST API. Needed for non-standard scenarios: delayed payments, holds, marketplace splits.

Basic Implementation (PHP/Laravel)

// composer require yookassa/yookassa-sdk-php

$client = new Client();
$client->setAuth('shopId', 'secretKey');

$payment = $client->createPayment([
    'amount' => ['value' => '1500.00', 'currency' => 'RUB'],
    'confirmation' => [
        'type' => 'redirect',
        'return_url' => route('payment.success', $order->id)
    ],
    'capture' => true,
    'description' => "Order #{$order->id}",
    'metadata' => ['order_id' => $order->id]
]);

$confirmationUrl = $payment->getConfirmation()->getConfirmationUrl();

Webhook Processing

YooKassa sends notifications to specified URL when payment status changes. Important:

• Check sender IP address (YooKassa publishes IP list in docs)
• Verify request signature
• Respond 200 OK before business logic execution (otherwise resend)
• Handle idempotently — same event can arrive twice

// routes/webhooks.php
Route::post('/webhooks/yookassa', [YookassaWebhookController::class, 'handle'])
     ->withoutMiddleware([VerifyCsrfToken::class]);

Refunds

$refund = $client->createRefund([
    'payment_id' => $payment->getId(),
    'amount' => ['value' => '500.00', 'currency' => 'RUB'],
    'description' => 'Partial refund'
]);

Refund can be full or partial. Funds return via same method as payment was made.

Settings and Timeline

• YooKassa registration, getting shopId and secretKey — 1–3 business days on YooKassa side
• Integration development (redirect form + webhook) — 1 business day
• Sandbox testing + production launch — another 1 day