Instructions for Tochka Bank Acquiring

What the add-on does

The add-on connects a CS-Cart store to Tochka Bank internet acquiring. A customer places an order, selects the payment method that uses the “Tochka Bank Acquiring” processor, and is redirected to the bank payment page. After payment, the add-on receives the payment result, updates the order status according to your mapping, and stores operation details in the admin panel.

The add-on also supports payment operation management: operation history, payment status checks, cancellation, capture for held payments, and refunds. Receipt fiscalization can be enabled through DigitalKassa.

Where to find the add-on

• Add-ons → Manage add-ons → Tochka Bank Acquiring — general add-on settings and order status mapping.
• Administration → Payment methods — create or configure a payment method with the “Tochka Bank Acquiring” processor.
• Orders → View orders → order details — payment data, fiscal data, and operation actions: capture, cancel, refund.
• Administration → Tochka Bank → Operations — operation log with filters by order, payment ID, status, operation type, and dates, if the menu item is available in your build.

Preparation in the bank account

Before configuring the payment method in CS-Cart, obtain the acquiring credentials from Tochka Bank:

• customerCode — customer code. It can be entered manually or filled with the From list (Business) button after the API token is saved.
• merchantId — store identifier. It can be entered manually or filled with the From list (REG, active) button. customerCode must be specified before selecting merchantId from the API.
• Client ID — client identifier for the bank API. It is recommended for correct API operation.
• API token — authorization token for API requests.
• Webhook secret — secret key used to verify webhook signatures from the bank.

If fiscalization through DigitalKassa is required, also prepare the actor, token, group ID, and, if needed, the DigitalKassa webhook signature secret.

Payment method setup

1. Open Administration → Payment methods and create or edit a payment method for Tochka Bank.
2. Select Tochka Bank Acquiring as the processor.
3. Open the processor parameters and fill in the required fields.

Main processor parameters

• Test mode — enables the bank sandbox environment. Use it to verify the integration without real charges.
• Customer code (customerCode) — Tochka Bank customer code.
• Store ID (merchantId) — store identifier in the bank system. Usually it is a numeric identifier issued by the bank.
• Client ID — client identifier for the bank API.
• API token — authorization token for creating payments, checking statuses, and running payment operations.
• Webhook secret — used to verify incoming bank notifications.
• Currency — payment currency. RUB is normally used for Russian payments.
• Payment mode — one-stage payment or a two-stage flow with payment holding. Important: holding is controlled by merchant settings on the bank side; the add-on can capture a held payment with a separate capture operation.
• Payment methods — available payment-side methods: bank card, SBP, Tinkoff, Dolyame. If nothing is selected, card payment is used by default.

Bank webhook

The payment method settings show a ready Webhook URL. Copy this URL and add it in the Tochka Bank account for payment notifications.

The webhook lets the add-on receive the final payment status automatically, verify the notification signature, update the order, and store the event in the log. If the webhook secret is empty, signature verification cannot protect incoming notifications.

Order status mapping

In the add-on settings, map bank payment results to CS-Cart order statuses:

• Success — status for paid orders. By default, the open order status is used.
• Failed — status for declined or cancelled payments. By default, the failed order status is used.

In a multi-storefront installation, select a storefront first; otherwise the mapping may be unavailable for editing.

Fiscalization and DigitalKassa

To send receipts, enable Send receipt for 54-FZ and fill in fiscal parameters:

• Tax system — general taxation, simplified taxation, patent, and other supported options.
• Default VAT rate — applied to products without a separate tax rate.
• Payment method attribute — for example full payment, 100% prepayment, advance payment, or credit.
• Payment object attribute — product or service.

To send receipts to DigitalKassa, enable Send receipts to DigitalKassa and fill in:

• Actor (DigitalKassa) — actor identifier.
• Token (DigitalKassa) — authorization token.
• DigitalKassa group ID — cash register group identifier.
• DigitalKassa tax system — used when building the receipt.

After a successful payment, the add-on can send a receipt to DigitalKassa and save fiscal data in the order. If DigitalKassa settings are enabled, the payment method settings also provide a test receipt submission button.

Payment flow

1. The customer places an order and selects Tochka Bank payment.
2. The add-on checks the required parameters: customerCode, merchantId, and API token.
3. The add-on creates a payment through the bank API and sends the amount, currency, order number, return URL, and selected payment methods.
4. If receipt transmission is enabled, fiscal data is added to the request.
5. The customer is redirected to the bank payment page.
6. After payment, the add-on receives a redirect or webhook, checks the payment status through the API, and updates the order.

Operations in order details

After a payment is created, the payment ID is saved in the order. The order details page shows payment and fiscal data as well as available actions:

• Capture payment — confirms a held payment.
• Cancel payment — cancels the payment if the bank supports cancellation for the current status.
• Full or partial refund — creates a refund by payment ID.
• All operations — opens the operation log related to the payment.

Available actions depend on the payment status, bank-side settings, and the API response.

How to check the result

1. Enable test mode in the processor settings if the check should run without a real charge.
2. Make sure customerCode, merchantId, API token, and webhook secret are filled in.
3. Save the payment method and copy the webhook URL to the bank account.
4. Create a test order on the storefront and select Tochka Bank payment.
5. Check that the customer is redirected to the bank payment page.
6. Complete the test payment and make sure the order receives the mapped status.
7. Open the order details and check the payment ID, operation status, and fiscal data.
8. Check the operation log and, if available, the webhook notification log.
9. If holding is used, capture the payment and verify the result.
10. If refunds are used, run a test full or partial refund.
11. If DigitalKassa is enabled, check test receipt sending and the receipt data saved in the order.

If payment does not work

• Check that customerCode, merchantId, and API token are filled in without extra spaces.
• Make sure the correct environment is selected: test or production.
• Verify that internet acquiring is active in the bank account for the required merchantId.
• Compare the webhook URL and webhook secret in the bank account and in CS-Cart.
• Check the operation log: it stores requests, responses, statuses, and API errors.
• If receipts are not sent, separately check the DigitalKassa settings: actor, token, group ID, and tax system.