Tochka Bank Acquiring add-on instructions

What the add-on does

The add-on connects a CS-Cart online store to Tochka Bank internet acquiring. A customer selects the payment method at checkout and proceeds to the bank's secure payment page. The add-on verifies the operation result, updates the order status, and stores payment details in the admin panel.

The add-on supports one-stage and two-stage payments, full and partial refunds, payment events in the native CS-Cart event log, receipt data sent to Tochka Bank, and a separate DigitalKassa integration.

What to prepare before setup

• Active internet acquiring at Tochka Bank.
• An API token with permissions to create payment operations, read acquiring data, and read customer data.
• A Client ID and the ManageWebhookData permission when automatic bank notification registration is required.
• A valid HTTPS certificate on the storefront.
• DigitalKassa credentials when receipts will be sent through that service.

Where to find the add-on

• Add-ons → Manage add-ons → Tochka Bank Acquiring: file logging and reliability settings.
• Settings → Logging → Tochka Bank: payment event and API diagnostic logging controls.
• Administration → Payment methods: Tochka Bank connection, payment options, order statuses, and fiscalization.
• Orders → View orders → order details: payment details, capture, refunds, and receipts.

General add-on settings

1. Open Add-ons → Manage add-ons.
2. Find Tochka Bank Acquiring and open its settings.
3. In a multi-store installation, select the storefront that you want to configure.
4. When required, enable additional logging to ms_tochka_api.log.
5. Select the number of retries for safe informational requests after a network error.
6. Save the settings and reopen the page to confirm that the values were stored.

Payment creation, capture, and refund requests are not retried automatically. This protects the store from duplicate financial operations after an uncertain network response.

Event logging

1. Open Settings → Logging.
2. Find the Tochka Bank group.
3. Select All operations to record payment operations, status changes, webhooks, and successful and failed API requests and responses.
4. Select Failed operations to record API and network errors only.
5. Save the settings and reload the page to confirm the selected values.

All entries are stored under Settings → Logging. The order details page links to events for the current order and to all Tochka Bank events. The add-on does not create separate log pages.

When both options are selected, successful operations are recorded as regular events and errors as failed events. A single error does not create duplicate entries.

The ms_tochka_api.log file switch remains in the add-on settings and follows the level selected in the Tochka Bank group. If both group options are disabled, neither the system nor file API log is populated. Tokens and personal data are masked before logging.

Creating a payment method

1. Open Administration → Payment methods.
2. Create a payment method or open an existing one.
3. Select the MS: Tochka Bank Acquiring processor.
4. Open the processor settings tab.
5. Enter the connection settings and save the payment method.
6. Make sure that the payment method is enabled and available to the required storefront and user group.

Connection settings

• API token: authorization token used to create and check operations.
• Client ID: identifier required for automatic bank notification registration. It can be left empty when notifications are disabled.
• Test mode: switches the add-on to the Tochka Bank sandbox. The sandbox is intended for checking requests and responses; availability of a complete payment page depends on the bank's test environment.
• Payment mode: one-stage capture or a two-stage payment with a funds hold.
• Customer code (customerCode): the business customer code at Tochka Bank.
• Merchant ID (merchantId): the identifier of an active merchant outlet.
• Register webhook automatically: enables registration of the HTTPS endpoint for bank notifications.
• Payment options: bank card, SBP, Tinkoff, and Dolyami. A bank card is used when no option is selected.

To retrieve the customer code and merchant outlet through the API, enter the token, click Connect, and select the required values from the list. If the customer has a single merchant outlet, the add-on fills it in automatically.

Bank notifications and synchronization

When webhook processing is enabled, the add-on registers the notification address while saving the payment method. This requires a Client ID, the ManageWebhookData permission, and a storefront available over HTTPS.

The add-on verifies the notification signature and matches the payment with the order. A duplicate notification for the same operation must not update the order or create a receipt again.

As an additional fallback, you can schedule synchronization of incomplete operations. Add a server cron job that requests an address such as https://store.example/index.php?dispatch=ms_tochka.sync&cron_password=YOUR_CRON_PASSWORD. Use the cron password from the CS-Cart security settings and do not share it with third parties. The recommended interval is 5 minutes.

Order status mapping

Statuses are configured separately for every payment method that uses the MS: Tochka Bank Acquiring processor:

• Successful: applied after a confirmed payment.
• Failed: applied after a declined, cancelled, or expired operation.
• Authorized: applied when funds are held before capture.

All three fields are required. Payment methods with empty values use safe defaults: Processed (P), Failed (F), and On hold (A), respectively.

For an authorization hold, select a status that decreases inventory. The standard On hold status is recommended. If you select Open, Returned, or another status that does not decrease inventory, CS-Cart treats checkout as incomplete and returns the customer to checkout instead of the Thank you page.

After saving, reload the page and make sure that the selected statuses were not reset.

Fiscalization through Tochka Bank

To send order items with the payment, enable Send receipt for 54-FZ and configure:

• taxation system;
• default VAT rate for products without an individual rate;
• payment method attribute;
• fallback payment object attribute.

The add-on uses products, discounts, shipping, and tax data from the order. Before enabling fiscalization, confirm the values with your accountant or online cash register specialist.

Fiscalization through DigitalKassa

To send receipts through DigitalKassa, enable the corresponding option and enter:

• Actor;
• Token;
• DigitalKassa group ID;
• DigitalKassa taxation system.

After a successful payment, the add-on sends a sale receipt. A separate sale refund receipt is created for the actual amount of every full or partial refund.

Fiscalization through Tochka Bank and DigitalKassa is enabled independently. Do not enable both options at the same time unless sending two receipts is part of your cash register setup.

One-stage payment flow

1. The customer places an order and selects Tochka Bank Acquiring.
2. The add-on creates a new payment attempt with a unique identifier.
3. The customer proceeds to Tochka Bank and completes the payment.
4. The add-on receives a bank notification or checks the operation through the API.
5. The amount, merchant outlet, customer, and operation identifiers are matched with the order.
6. After successful validation, the configured order status is applied.

Returning to the storefront does not confirm payment by itself.

Two-stage payment flow

Two-stage payments must be enabled for the merchant outlet by the bank. The add-on uses bank cards only in this mode because SBP does not support a funds hold.

1. After funds are authorized, the order receives the status selected for a funds hold and the customer returns to the Thank you page.
2. Open the order details page and find the Tochka Bank block.
3. Click Capture payment.
4. Wait for the bank confirmation and check the final operation and order statuses.

The message “Order funds are held until the store administrator captures the payment” indicates a successful authorization hold, not a payment error. The funds are reserved on the customer's card and are captured only after an administrator confirms the operation.

The Tochka Bank API does not provide the add-on with a separate operation for cancelling a hold. A refund is available after the funds have been captured.

Full and partial refunds

1. Open a paid order.
2. In the Tochka Bank block, check the amount available for refund.
3. For a partial refund, enter an amount and click Partial refund.
4. To return the entire remaining amount, click Full refund.
5. Check the result on the order details page and in the native CS-Cart event log.

A refund changes the payment operation state but does not change the CS-Cart order status by itself. If your workflow requires a separate order status, assign it manually.

Do not retry a refund immediately after a network error until you check the operation log and the operation state at Tochka Bank.

Acquiring commission

On the order details page, click Get commission. The add-on requests the Tochka Bank registry and, once the original payment has been processed by the bank, displays the commission and settlement amount. This is a read-only request and does not change the payment or order.

Card payments made on the current date may be absent from the registry until processing is complete. After a refund, registry rows may reuse the original operation ID; the add-on verifies the amount and time and does not treat a refund row as the original payment. If the original row is not found, retry after the bank finishes processing it.

Payment details and logs

The order details page shows the payment identifier and state, paid and refundable amounts, refund details, and DigitalKassa receipts. The available actions depend on the current operation state.

The Order events link opens the native CS-Cart event log filtered by order ID. The All Tochka Bank events link shows all add-on entries. Advanced search provides separate order ID and payment ID filters.

An event includes the operation type and status, amount, currency, and webhook processing result. Raw tokens and personal data are not written to the log.

For a DigitalKassa receipt that is still processing, use Check status. Retry submission checks the previous attempt first and creates a new one only when the previous receipt cannot be found.

Verification after setup

1. Save the add-on settings, reload the page, and check file logging and network retry values.
2. Under Settings → Logging → Tochka Bank, select the required level and confirm that it persists.
3. Save the payment method and make sure that the token, customerCode, merchantId, payment options, and order statuses were not reset.
4. Check webhook registration or configure fallback synchronization.
5. Create a test order with an amount that includes rubles and kopecks.
6. Complete successful and failed payments and check the order statuses.
7. Create a second payment attempt for the same order and make sure that each attempt is tracked separately.
8. For a two-stage payment, verify the redirect to the Thank you page after authorization and then capture the payment.
9. Make a partial refund with kopecks and then refund the remaining amount.
10. If DigitalKassa is enabled, check the sale receipt, refund receipt, status update, and safe retry action.
11. Review payment and webhook events in the native CS-Cart event log. A duplicate notification must not repeat processing.

Before going live, disable the sandbox, use a production token, and complete an approved minimum-value payment.

If payment does not work

• Check the API token, its expiration date, and the required permissions.
• Make sure that customerCode and merchantId belong to the same customer and an active merchant outlet.
• Confirm that the correct environment is selected: sandbox or production.
• If webhook registration fails, check Client ID, the ManageWebhookData permission, the HTTPS certificate, and public storefront availability.
• If the order status is not updated, check status mapping, the operation amount, and the Tochka Bank events in the CS-Cart log.
• If a receipt is not created, check fiscal settings, the customer contact details, tax rates, and DigitalKassa credentials.
• After an uncertain financial operation result, check its state in the log and at Tochka Bank before retrying the action.