SberPay Payment System Integration

SberPay Payment System Integration

SberPay is Sberbank's payment solution, existing in several forms: as quick payment method via SberBank Online app (no card data entry), as embedded payment method via Sberbank Acquiring, and as QR-payment via SBP. Usually "SberPay integration" means connecting to Sberbank Acquiring gateway with SberPay button support.

Sberbank Acquiring Connection

Acquiring agreement needed with Sberbank. After signing contract, test and production credentials provided.

Test environment: https://3dsec.sberbank.ru/payment/rest/ Production environment: https://securepayments.sberbank.ru/payment/rest/

Authentication — via userName + password in each request, or via token (recommended since 2022).

Order Registration

$response = Http::get('https://securepayments.sberbank.ru/payment/rest/register.do', [
    'userName'        => env('SBER_USERNAME'),
    'password'        => env('SBER_PASSWORD'),
    'orderNumber'     => 'order-12345',
    'amount'          => 150000, // in kopecks
    'returnUrl'       => 'https://example.com/payment/return',
    'failUrl'         => 'https://example.com/payment/fail',
    'description'     => 'Order #12345',
    'email'           => '[email protected]',
    'language'        => 'ru',
    'pageView'        => 'DESKTOP', // or MOBILE
]);

$orderId    = $response->json('orderId');    // ID in Sberbank system
$formUrl    = $response->json('formUrl');    // Payment page URL

After getting formUrl — redirect there. Sberbank shows payment page with all available methods, including SberPay if customer on device with SberBank Online app.

Order Status Check

Sberbank supports callbacks, but need separate setup in personal account. More reliable to additionally check status on returnUrl:

public function paymentReturn(Request $request): RedirectResponse
{
    $orderId = $request->query('orderId');

    $status = Http::get('https://securepayments.sberbank.ru/payment/rest/getOrderStatusExtended.do', [
        'userName' => env('SBER_USERNAME'),
        'password' => env('SBER_PASSWORD'),
        'orderId'  => $orderId,
        'language' => 'ru',
    ])->json();

    // orderStatus: 0=registered, 1=not paid, 2=paid, 3=authorized,
    // 4=cancelled, 5=refund, 6=AZ declined by customer bank
    if ($status['orderStatus'] === 2) {
        $localOrderId = $status['orderNumber']; // our internal number
        Order::where('id', $localOrderId)->update(['status' => 'paid']);
        return redirect('/orders/' . $localOrderId . '?paid=1');
    }

    return redirect('/cart?payment_failed=1');
}

Never trust only URL parameters — only server check via getOrderStatusExtended.

Two-Stage Payment

For marketplaces or post-payment orders, two-stage scheme fits: first authorization (funds freeze), then debit after shipment.

// Register with two-stage payment flag
Http::get('https://securepayments.sberbank.ru/payment/rest/registerPreAuth.do', [
    // same parameters as register.do
]);

// Confirm debit after shipment
Http::get('https://securepayments.sberbank.ru/payment/rest/deposit.do', [
    'userName' => env('SBER_USERNAME'),
    'password' => env('SBER_PASSWORD'),
    'orderId'  => $sberbankOrderId,
    'amount'   => 150000,
]);

Frozen funds held up to 30 days. If not confirmed within this period — authorization automatically cancelled.

Fiscalization

Sberbank supports fiscalization via own "Atol Online" cash register, integrated into acquiring. Receipt data passed in orderBundle parameter:

'orderBundle' => json_encode([
    'customerDetails' => ['email' => '[email protected]'],
    'cartItems' => [
        'items' => [[
            'positionId'   => 1,
            'name'         => 'Product 1',
            'quantity'     => ['value' => 1, 'measure' => 'pcs'],
            'itemAmount'   => 150000,
            'itemCode'     => 'SKU-001',
            'tax'          => ['taxType' => 0], // 0=no VAT
            'itemPrice'    => 150000,
        ]],
    ],
]),

Refunds

Http::get('https://securepayments.sberbank.ru/payment/rest/refund.do', [
    'userName' => env('SBER_USERNAME'),
    'password' => env('SBER_PASSWORD'),
    'orderId'  => $sberbankOrderId,
    'amount'   => 75000, // partial or full refund
]);

Features and Limitations

Main complexity with Sberbank acquiring — slow support. Response to connection request takes 5 to 14 business days, activation of production after testing — another 3–5 days. Documentation updated irregularly; get actual version from manager. For SberPay as separate method (no card entry), SberBank Online app required on customer device — doesn't work on desktop.