Integrating Tinkoff Kassa Payment System into a Website

When integrating the payment gateway from Tinkoff, we often encounter token generation errors, webhook failures, or non-working refunds. Let's break down how to avoid these issues and set up stable payment acceptance. The system processes transactions on average 1.5 times faster than aggregators with outdated TCP protocols, and API response time does not exceed 200 ms at the 95th percentile. Stack: PHP 8.3, Laravel 11, PostgreSQL. Our experience — over 5 years, more than 50 successful projects, handling over 10,000 transactions daily. We guarantee correct operation even under peak loads. Savings on transaction costs can reach 40% due to optimized payment routing. For example, an online store processing 1000 payments of $50 each per month can save up to $1,000 per month in fees. The Tinkoff Kassa API requires signing each request — otherwise error 401 is returned.

Connecting Tinkoff Kassa to a Website

Obtaining Credentials

For operation, two keys are needed: TerminalKey and Password. They can be obtained in the Tinkoff Business personal account — section 'Payment Acceptance' → 'Terminals'. There you also set up the webhook URL and the list of allowed IPs for notifications. Be sure to specify the NotificationURL — without it, Tinkoff cannot notify your server about changes in payment status, and orders will remain unprocessed.

Switching between them is only through the TerminalKey: test keys start with TinkoffBankTest.

Payment Initialization

Payment is initiated via the Init method. Basic request:

$params = [
    'TerminalKey' => env('TINKOFF_TERMINAL_KEY'),
    'Amount'      => 150000, // in kopecks
    'OrderId'     => 'order-12345',
    'Description' => 'Order #12345',
    // Set NotificationURL to your server endpoint
    // Set SuccessURL and FailURL for redirects
];

// Adding 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 point with the token: it is calculated by concatenating the sorted alphabetically values (not keys) plus the password. Errors in token generation are the most common problem during integration. After receiving the PaymentURL, the buyer is redirected to the Tinkoff page. The entire payment UI is on their side.

If you want to set up a payment gateway from scratch or modernize an existing one, contact us for a consultation.

Step-by-Step Instructions

1. Get TerminalKey and Password in the Tinkoff personal account.
2. Specify the NotificationURL and the list of IPs for webhook.
3. Implement payment initialization via Init with a correct token.
4. Set up a webhook handler to receive notifications.
5. Test all scenarios in the sandbox.
6. Switch to production keys and start monitoring.

How We Process Notifications?

After payment, Tinkoff sends a POST to the 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, trigger delivery logic
    }

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

Statuses to handle: AUTHORIZED, CONFIRMED, REJECTED, REFUNDED, PARTIAL_REFUNDED, CANCELED. Additional protection — checking the sender's IP: Tinkoff publishes its IP list in the documentation, can be filtered at the nginx or middleware level.

Fiscalization via FFD 1.2

If the business is required to print receipts (54-FZ), a Receipt object is passed in the 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 is performed by Tinkoff automatically — no need to connect your own online cash register. The receipt is sent to the buyer's email or phone. The format used is FFD 1.2.

Why Choose This Stack?

The payment gateway processes transactions 1.5 times faster than competitors, and API response time does not exceed 200 ms. This is critical for high-load projects. We configure monitoring and alerts for failures — you will learn about problems before they affect sales. The integration cost is fixed at the agreement stage and does not change during the process. Integration cost starts from €500. Order integration — get a stable payment gateway.

Refunds

Refund via the Cancel method:

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

Full refund — pass Amount equal to the order total or do not pass it at all. We implement both scenarios taking into account business logic.

Deliverables and Scope

Timeline and Cost

Integration takes from 3 to 7 working days depending on complexity and the need for fiscalization. Cost is calculated individually after assessing the scope of work, starting from €500. Get a consultation — contact us. We also assist with obtaining TerminalKey and testing in the sandbox.

Contact us — we will discuss the details of your project.

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.