Tinkoff Kassa Payment System Integration

Tinkoff Kassa Payment System Integration

Tinkoff Kassa is one of most widespread payment gateways in Russian market. Supports Visa, Mastercard, MIR, SBP, Apple Pay, Google Pay and installments via Tinkoff Installment. Official SDK exists for PHP, Java, .NET, Python and Node.js, but most integrations done directly via REST API.

Connection and Access

Two keys needed: TerminalKey and Password. Get them in Tinkoff Business personal account — "Payment Acceptance" → "Terminals". There also configure payment notification (webhook URL) and allowed IP list.

Test environment: https://rest-api-test.tinkoff.ru/v2/ Production environment: https://securepay.tinkoff.ru/v2/

Switching between — only via TerminalKey: test keys start with TinkoffBankTest.

Order Creation and Payment Initialization

Payment initiated via Init method. Basic request:

$params = [
    'TerminalKey' => env('TINKOFF_TERMINAL_KEY'),
    'Amount'      => 150000, // in kopecks
    'OrderId'     => 'order-12345',
    'Description' => 'Order #12345',
    'NotificationURL' => 'https://example.com/webhook/tinkoff',
    'SuccessURL'  => 'https://example.com/payment/success',
    'FailURL'     => 'https://example.com/payment/fail',
];

// Add token
ksort($params);
$tokenStr = implode('', array_values($params)) . env('TINKOFF_PASSWORD');
$params['Token'] = hash('sha256', $tokenStr);

$response = Http::post('https://securepay.tinkoff.ru/v2/Init', $params);
$paymentUrl = $response->json('PaymentURL');

Important token detail: calculated by concatenation of values sorted alphabetically (not keys) plus password. Token generation errors — most common integration problem.

After getting PaymentURL customer redirected to Tinkoff page. All payment UI — on their side.

Webhook and Status Check

After payment Tinkoff sends POST to NotificationURL with data in application/x-www-form-urlencoded format:

public function handleWebhook(Request $request): JsonResponse
{
    $data = $request->all();

    // Check token
    $received  = $data['Token'];
    $checkData = $data;
    unset($checkData['Token']);
    ksort($checkData);
    $expected = hash('sha256', implode('', array_values($checkData)) . env('TINKOFF_PASSWORD'));

    if (!hash_equals($expected, $received)) {
        return response()->json(['error' => 'Invalid token'], 403);
    }

    if ($data['Status'] === 'CONFIRMED') {
        Order::where('id', $data['OrderId'])->update(['status' => 'paid']);
        // send receipt, start shipping logic
    }

    return response()->json(['OK' => true]);
}

Statuses to handle: AUTHORIZED (funds frozen), CONFIRMED (money debited), REJECTED, REFUNDED, PARTIAL_REFUNDED, CANCELED.

Additional protection — check sender IP. Tinkoff publishes IP list in docs, can filter at nginx or middleware level.

Fiscalization via FFD 1.2

If business must issue receipts (54-ФЗ), Receipt object passed in Init request:

'Receipt' => [
    'Email'    => '[email protected]',
    'Taxation' => 'usn_income',
    'Items'    => [
        [
            'Name'          => 'Product 1',
            'Price'         => 100000, // in kopecks
            'Quantity'      => 1.0,
            'Amount'        => 100000,
            'Tax'           => 'none',
            'PaymentMethod' => 'full_payment',
            'PaymentObject' => 'commodity',
        ],
    ],
],

Fiscalization performed by Tinkoff automatically — no need to connect own cash register. Receipt sent to customer email or phone.

Refunds

Refund via Cancel method:

$params = [
    'TerminalKey' => env('TINKOFF_TERMINAL_KEY'),
    'PaymentId'   => '12345678',
    'Amount'      => 75000, // partial refund
];
// add Token by same scheme
Http::post('https://securepay.tinkoff.ru/v2/Cancel', $params);

Full refund — pass Amount equal to order sum or don't pass it.

Timeline and Features

Tinkoff integration testing and approval takes about 2–3 business days: need to conduct several test transactions, after which manager activates production terminal. For fiscalization timeline increases: need to agree on cash register settings. In practice full cycle from getting access to first real payment — 5–7 business days.