Integrating 1C-Bitrix with Tinkoff Credit

Integration of 1C-Bitrix with Tinkoff Credit

Customer added an 80,000 ruble item to cart but isn't ready to pay immediately. If there's a "Buy on Credit" button at checkout — conversion on expensive goods increases 15–25%. Tinkoff Credit is one of the most common online lending services in Russian e-commerce. Integration with 1C-Bitrix is technically simple but contains nuances affecting functionality.

How Tinkoff Credit Works

Process from buyer's perspective:

1. Selects item → clicks "Buy on Credit"
2. Redirects to Tinkoff form, fills application
3. Tinkoff makes decision (1–15 minutes)
4. If approved — money transfers to store, buyer gets item

From store perspective it's a payment system with deferred confirmation. Tinkoff provides API (api-msk.tinkoff.ru/api/partners/v2/orders/create) through which store creates credit application, passes item data and sum, gets redirect link for buyer.

Connection: Contract and Settings

Before technical integration you need a partner agreement with Tinkoff. After signing you receive:

• shopId — store identifier
• showcaseId — showcase identifier (can be multiple for different credit/installment types)
• API-key — for request authorization
• Access to partner cabinet — for monitoring applications

Technical Integration

In 1C-Bitrix Tinkoff Credit is connected as a payment system of sale module. Two paths:

Path 1: Ready module from Marketplace. On marketplace.1c-bitrix.ru there are several modules for Tinkoff Credit. Install module, enter shopId, showcaseId, API-key in payment system settings (Store → Settings → Payment Systems). Module creates handler \Sale\Handlers\PaySystem\TinkoffCredit and registers callback-URL for notifications.

Path 2: Custom payment system handler. If ready modules don't suit (outdated, missing features, conflicts), write handler from scratch.

Handler structure in /local/php_interface/include/sale_payment/tinkoff_credit/:

handler.php        — handler class
.description.php   — metadata for admin
.settings.php      — list of settings (shopId, showcaseId, apiKey)
template/          — payment button template

Handler class inherits from \Bitrix\Sale\PaySystem\ServiceHandler and implements methods:

• initiatePay — forms request to Tinkoff API, creates application, returns redirect URL
• processRequest — handling callback from Tinkoff on application status change
• getPaymentIdFromRequest — extracting payment ID from incoming notification

Forming an Application

Request to Tinkoff API contains:

{
  "shopId": "your_shop_id",
  "showcaseId": "your_showcase_id",
  "orderNumber": "BX_ORDER_123",
  "customerInfo": {
    "email": "[email protected]",
    "mobilePhone": "+79001234567"
  },
  "items": [
    {
      "name": "Lenovo ThinkPad Laptop",
      "quantity": 1,
      "price": 80000,
      "category": "electronics"
    }
  ],
  "sum": 80000,
  "returnUrl": "https://shop.ru/personal/order/detail/{ORDER_ID}/",
  "failUrl": "https://shop.ru/personal/order/detail/{ORDER_ID}/?fail=1",
  "postLink": "https://shop.ru/bitrix/tools/sale_ps_result.php"
}

Product items are required. Tinkoff uses them for scoring — application without items will be rejected. Data taken from basket: \Bitrix\Sale\Order::loadByAccountNumber($orderNumber)->getBasket().

postLink — URL where Tinkoff sends POST-notifications on application status change. Must be externally accessible (not localhost, not behind basic auth).

Handling Callback Notifications

Tinkoff sends POST to postLink on each application status change:

Critical: confirm payment only on signed status, not approved. Approved application can still be canceled by client.

Checking notification signature — mandatory. Tinkoff passes signature in header computed as HMAC from request body and your API-key. Without signature check, attacker can confirm payment by sending fake POST.

Button on Product Page

Besides payment at checkout, Tinkoff provides widget for product card — shows approximate monthly payment. JS-widget connected by script:

<script src="https://forma.tinkoff.ru/static/onlineScript.js"></script>

And called with parameters: tinkoff.online({shopId, showcaseId, items, sum}). Integrating widget into template of component bitrix:catalog.element — in file template.php or via result_modifier.php.

Testing

Tinkoff provides test environment with separate shopId and showcaseId. In test mode applications are approved automatically. Must test full cycle: application creation → redirect → callback with each status → payment update in Bitrix. Special attention — handling rejected and canceled: ensure order doesn't hang in "Awaiting Payment" status forever.