Tochka Bank Acquiring

Instructions for Tochka Bank Acquiring

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 hold cancellation without capture, full and partial refunds of captured funds, payment events in the native CS-Cart event log, and order item data sent to Tochka Bank for receipts.

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.

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: current payment status and explanation, capture, hold cancellation, 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, hold cancellation, 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 amount, operationId, paymentLinkId, customerCode, and merchantId against the stored payment attempt and order. If a signed webhook contains incomplete or mismatched data, the add-on rechecks the operation through GET using the stored payment ID. The identifiers, amount, and status reported in the notification must be confirmed.

If the API is unavailable, the data does not match, or GET still returns an earlier status, the add-on responds with HTTP 503 and leaves the notification unprocessed. An order status update failure also leaves the notification available for retry. The native CS-Cart log records the verification source and names of mismatched fields without exposing secrets.

A duplicate of a successfully processed notification must not update the order, create a receipt, or start capture again. Repeated payment confirmation does not reset an already shipped order to an earlier fulfillment status. A previously rejected notification that an older version incorrectly marked as processed with an error can be processed again with a valid signature.

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 verified APPROVED or WAIT_FULL_PAYMENT with received prepayment covering the full order amount.
• 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, the standard On hold status with an inventory decrease is recommended so that the held order is accounted for in product availability. Check the inventory setting of the selected status in your store. The redirect to the Thank you page after a verified hold or payment is handled separately: a status without an inventory decrease does not by itself return the customer to checkout. Routing does not replace the stored order status.

To start capture by changing the order status, configure different Authorized and Successful statuses. Only an explicit manual transition between these statuses in two-stage mode acts as a capture command; changing to any other status does not start capture.

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 VAT rate is determined for each order item. If exactly one valid rate supported by Tochka Bank is determined for the product, the add-on sends that rate. If the rate is missing, multiple taxes are assigned, or the fiscal rate is invalid or unsupported by Tochka Bank, the add-on uses the default VAT rate configured for the current payment method.

For Russian VAT, assign only one tax to a product. CS-Cart can calculate multiple selected taxes together; they are not alternative rates from which the store automatically selects one.

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.

The product measurement unit is read from Products → Product → Price per unit → Unit name. Tochka Bank accepts only these exact values: г., кг., т., см., дм., м., см2., дм2., м2., мл., л., м3, кВт.ч., Гкал., дн., ч., мин., сек., Кб., Мб., Гб., Тб., and шт.

The value must match the list, including letter case and punctuation. If the field is empty or contains an unsupported value, the add-on sends шт. so that an invalid product setting does not interrupt payment creation.

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.

Received 100% prepayment

The bank status WAIT_FULL_PAYMENT, with verified identifiers and an amount equal to the full order total, means received 100% prepayment, not an unpaid order or an authorization hold. The configured successful status is applied, the native CS-Cart order placement cycle completes, and the customer returns to the Thank you page, not checkout.

The customer does not need to pay again, and no hold capture is required for this state. The order details page shows the current prepayment status and its explanation. If the amount is missing, zero, or mismatched, or the identifiers are not verified, the status name alone is insufficient: the add-on does not treat the prepayment as confirmed.

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 the bank status AUTHORIZED, amount, and identifiers are verified, 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. Start capture in either of two ways: click Capture payment in the Tochka Bank block, or manually change the order from the configured authorization status to the configured successful status.
4. In both cases, the add-on sends the capture command to Tochka Bank only once. Clicking the button or selecting a status does not by itself mean that the funds have been captured.
5. The order keeps the configured authorization status until the bank confirms the operation. After the add-on receives APPROVED, it applies the configured successful status.
6. If the bank rejects the command or the request fails, the successful status is not applied. Check the administrator notification and the operation event in the native CS-Cart log.

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.

Acceptance of a capture command does not confirm payment. The states CAPTURE_PROCESSING and CAPTURE_ACCEPTED mean that the bank result is pending. Repeated clicks, repeated status transitions, webhooks, and synchronization do not send another Capture request. A late response to the command does not replace an already received APPROVED with an earlier hold or pending capture state.

After a timeout or an ambiguous response, do not manually unlock the operation or submit capture again: wait for a verified state through a webhook or synchronization. A retry is appropriate only after a confirmed rejection when the operation becomes available for capture again.

Full hold cancellation without capture

The Cancel hold button is available on the order details page for the current payment attempt with status AUTHORIZED. Order management permission is required. Cancellation always covers the original full hold amount; partial hold cancellation is not supported. Do not use the regular partial refund instructions to cancel part of a hold.

1. Open the order details page and check the current payment status and payment ID.
2. Click Cancel hold and confirm full cancellation. The add-on uses GET to verify the current bank operation, its identifiers, original amount, and AUTHORIZED status. Editing the order total or entering a refund amount does not change the hold cancellation amount.
3. After verification, the add-on sends one Refund Payment Operation request with the full amount in Data.amount. It does not perform a preliminary Capture or issue a DigitalKassa refund receipt for hold cancellation.
4. Acknowledgement by the bank, including an isRefund: true response, does not mean that the hold has ended. Until final confirmation, the page shows Hold cancellation pending and the Check hold cancellation button.
5. Click Check hold cancellation to retrieve the bank state. This check calls the bank through GET only and does not repeat the financial request. Background synchronization also checks the state without resending the request.
6. After verifying a final REFUNDED, CANCELLED/CANCELED, or EXPIRED state for a pending cancellation, the add-on records REVERSE_CONFIRMED and displays Hold cancelled. Cancellation confirmation changes the payment state but does not itself change the order fulfillment status.

While cancellation is pending (REVERSE_PROCESSING or REVERSE_ACCEPTED), repeated clicks do not send another cancellation request; state checks remain available. Concurrent capture through the button or an order status change is blocked. A stale form cannot perform an action for an old payment attempt, and late events do not reopen a completed hold for another capture.

A timeout, bank server error, or ambiguous response keeps the operation pending. Do not manually release the lock or repeat the financial request. A confirmed rejection without execution allows a retry after checking the cause; there is no automatic unlock timer.

The bank checks the allowed cancellation period against the operation state. The add-on does not count 144 hours from order creation: the order date does not establish when the funds were authorized. If GET shows that funds have already been captured, no hold cancellation request is sent; use a regular refund for a captured payment.

Verification limit: hold cancellation has been checked in local tests with mocked API responses. Actual release of held funds, the final bank response, and notifications for a real bank operation still require an agreed verification. Local tests do not prove that a real funds hold was released.

Full and partial refunds

This flow applies only to captured funds: APPROVED or REFUNDED_PARTIALLY with a positive refundable balance. It does not apply to AUTHORIZED or cancellation of part of a hold.

1. Open a paid order and check the current payment attempt ID.
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 ID, current Payment status and explanation, operation amount, and refund details. The available actions depend on the current operation state. Payment status is separate from order fulfillment status: an earlier successful hold response must not remain the current explanation after payment or hold cancellation.

The displayed states distinguish pending payment, received prepayment, held funds, pending capture, paid funds, failure, cancellation, expiry, pending and completed hold cancellation, pending refund, partial refund, and full refund. Payment event history remains in the native CS-Cart log, not in old response fields on the order details page.

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.

A payment operation event includes the order ID, payment and payment-link IDs, operation type and status, amount, currency, and order items. Product entries contain the product ID, SKU, name, quantity, price, VAT, and unit; shipping and surcharges contain their type, name, and amount without fake SKUs.

A hold cancellation request is logged as operation type reverse, separately from a regular refund. A record of request submission or acknowledgement does not replace confirmation of the final bank state.

Product names and SKUs are not masked because they are required for reconciliation. Tokens, authorization headers, and customer personal data are masked before logging.

How to check the result

Perform the checks below in a test environment. Operations involving real funds require separate agreement; this is a checklist of required checks, not a report of completed bank testing.

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 received 100% prepayment, verify confirmed WAIT_FULL_PAYMENT, the successful status, the Thank you page, no duplicate order, and no remaining cart items. Unverified identifiers or amounts must not complete payment.
9. On separate two-stage orders, check capture through the button and through a manual transition from the configured authorized status to the successful status. The successful status must not be applied before bank confirmation, and repeated actions must not send a second Capture. The old hold explanation must disappear after payment.
10. On a separate hold, check full cancellation: one request for the original amount, without Capture or a DigitalKassa refund receipt. Pending status and Check hold cancellation must remain visible until final confirmation; repeated checks use GET only.
11. In isolated tests, check double-clicks, concurrent capture and cancellation, an uncertain response, expiry reported by the bank, and late notifications. They must not result in another capture or cancellation request.
12. Only for a captured payment, make a partial refund with kopecks and then refund the remaining amount.
13. Review payment and webhook events in the native CS-Cart event log. Incomplete or mismatched data must be rechecked through GET, an unverified notification must remain available for retry, and repeated confirmation must not reset a shipped order to its previous status.

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.
• An old webhook mismatch message without field names does not prove the exact cause of the error. Diagnosis requires a GET check of the stored operation and new log entries; where needed, use an agreed replay of the notification with a valid signature.
• If a receipt is not created, check fiscal settings, customer contact details, tax rates, and product measurement units.
• After an uncertain financial operation result, check its state in the log and at the bank. For a pending cancellation, use Check hold cancellation. Do not repeat the financial command or release the lock until the result is known.