Nominal accounts Tochka Bank

Instructions for Tochka Bank Nominal Accounts

What the add-on does

The add-on connects a CS-Cart Multi-Vendor marketplace to Tochka Bank nominal account settlements. It helps register vendor beneficiaries, receive virtual accounts, distribute incoming payments by orders, create payout deals, and control when funds are available for withdrawal.

Documents are generated through the standard CS-Cart document mechanism. The add-on depends on the PDF Documents add-on.

Where to find the add-on

• Add-ons → Manage add-ons → Tochka Bank Nominal Accounts — connection, keys, beneficiary, distribution, and funds hold settings.
• Orders → Tochka Bank Payments — undistributed orders, incoming payments, outgoing payments, and deals.
• Vendors → Vendors → vendor profile → Tochka Bank — beneficiary data, documents, and vendor virtual account.
• Vendors → Accounting — withdrawal requests and payout deals.
• Administration → Payment methods — payment methods that participate in Tochka Bank settlements.
• Administration → Statuses → Order statuses — order status flags for distribution and payout confirmation.

Prepare Tochka Bank access

1. Request test or production access from Tochka Bank and provide the store server IP address to the bank.
2. Open the add-on settings, the General tab, and the Keys block.
3. Click Generate keys. The add-on will fill in the public and private keys and prepare a certificate for the bank.
4. Send the certificate file var/ms_data/ms_tochka_bank/keys/rsaacert.pem to Tochka Bank.
5. After confirmation from the bank, fill in Platform identifier, Key thumbprint, Marketplace nominal account, and Marketplace bank code.
6. Click Test connection. If the settings are correct, the add-on will show a successful status.

Private key fields are hidden by default. To view or edit them manually, use the Show private keys and Allow key editing settings.

Configure general settings

1. In the Test data block, enable or disable Test mode.
2. Fill in Marketplace nominal account and Marketplace bank code.
3. If test transfers require separate payer details, fill in Payer account and Payer bank code.
4. In Canceled order status, select the status that allows the full order amount to be transferred as marketplace commission.
5. In Who pays acquiring, select Marketplace or Vendor. If Vendor is selected, the acquiring fee reduces the amount paid to the vendor. If Marketplace is selected, the acquiring fee remains in the marketplace share.
6. In the Funds hold block, set the number of hold days. The value 0 disables time-based holding.
7. In Refundable order statuses, select order statuses that should keep funds blocked regardless of the hold period.
8. Enable logging and set the maximum log file size if operation logs are needed.

Configure vendor data

1. Open Administration → Profile fields → Vendor information.
2. Create or check fields for legal type, tax ID, company name, KPP, full name, birth date and place, passport data, passport subdivision code, registration address, registration country code, tax residency flag, bank code, and settlement account.
3. For the legal type field, use J for a legal entity, I for a sole proprietor, and F for an individual or self-employed vendor.
4. Open the add-on settings, the Beneficiary information tab, and map every vendor field to the corresponding add-on setting.
5. If Profile fields in a separate tab is enabled, the mapped fields will appear in the vendor profile on the Tochka Bank tab. If it is disabled, the fields remain in the general vendor profile form.
6. Configure automatic beneficiary activation and deactivation, and select the vendor status used during deactivation when the beneficiary has blocked funds.
7. If needed, configure the default value and lock behavior for the TB: create deal field in accounting.

Configure payment methods and order statuses

1. Open the payment method that should participate in Tochka Bank settlements.
2. Enable the Use with Tochka Bank checkbox.
3. Fill in Bank commission (%) if the acquiring fee should be included in distribution calculations.
4. Open order statuses and enable TB: distribute funds for statuses whose orders should appear in the distribution list.
5. Enable TB: order complete for statuses after which the vendor is allowed to request a withdrawal.

Register a vendor beneficiary

1. Open the vendor profile and the Tochka Bank tab.
2. Fill in the data mapped in the add-on settings.
3. Click Get beneficiary ID or save the vendor profile.
4. After a successful response, the add-on will fill in the beneficiary ID.
5. If the beneficiary document has not been created yet, the add-on will generate and upload an agreement. If needed, you can upload a file manually in the document field.
6. After the document is uploaded, the add-on will create and save the vendor virtual account.
7. Check the links to beneficiary data, the document, and the virtual account. For sole proprietors, self-employed vendors, and individuals, document validation statuses are also displayed.

Distribute payments

1. Go to Orders → Tochka Bank Payments.
2. On the Undistributed orders tab, check orders whose amount has not been fully distributed yet.
3. Click Distribute automatically. The add-on will receive new incoming payments, match them with orders, and distribute amounts to vendor virtual accounts.
4. If the incoming amount is not enough to cover the full order, the order remains partially distributed and will be completed on the next run.
5. Use the Incoming payments, Outgoing payments, and Deals tabs to monitor operations.
6. If a canceled order status is selected in settings, the order page can transfer the full amount of such an order as marketplace commission.

The command for regular automatic distribution is shown on the Additional information tab in the add-on settings: php admin.php --dispatch=ms_tochka_bank.identity_payments. Run it at least once every 96 hours; otherwise unidentified payments may be returned to acquiring.

Withdrawals and deals

1. Move the order to a status marked with TB: order complete.
2. Open the vendor accounting area and create a withdrawal request.
3. Make sure the TB: create deal field is enabled for the request.
4. The root administrator approves the payout in accounting. On approval, the add-on creates a deal, attaches a document, and tries to execute the deal.
5. If the bank returns an error, the payout is declined with the reason text. Fix the vendor, order, or deal data and repeat the action.
6. On the Deals tab, you can open a deal, update data, execute it, or reject it if the current status allows the action.
7. Available funds are shown with the hold rules applied: while the deal is not executed, the order has a refundable status, or the hold period has not ended, the amount remains unavailable.

Deactivate a beneficiary

1. If automatic deactivation is enabled, the add-on checks the beneficiary virtual account when a vendor is disabled.
2. If there are no available funds, the add-on deactivates the beneficiary.
3. If there is an available balance, the add-on tries to transfer funds to the vendor settlement account.
4. If there are blocked funds, the vendor is moved to the status selected in deactivation settings and the administrator receives a notification.

How to check the result

1. Enable test mode, fill in test requisites, and run Test connection.
2. Run a test transfer in the add-on settings.
3. Create a test vendor, fill in the Tochka Bank tab, and get the beneficiary ID.
4. Check that the beneficiary document and virtual account appear for the vendor.
5. Create a test order with a payment method marked for Tochka Bank and move it to a distribution status.
6. Open Orders → Tochka Bank Payments, click Distribute automatically, and check the vendor, marketplace, shipping, and acquiring amounts.
7. Move the order to a completed status, create a withdrawal request, and check that a deal is created.
8. Check that funds are shown as blocked or available according to the hold settings.

Troubleshooting

• Connection test fails. Check keys, key thumbprint, platform identifier, nominal accounts, bank codes, and the IP address agreed with the bank.
• Beneficiary is not created. Check the vendor legal type, required fields, and profile field mapping in the add-on settings.
• Virtual account does not appear. Check that the beneficiary is created, the beneficiary document is uploaded, and the vendor profile contains a tax ID.
• Order does not appear in distribution. Check the payment method, the Use with Tochka Bank checkbox, and the order status marked with TB: distribute funds.
• Payout deal is not created. Check the vendor virtual account, beneficiary ID, bank code, settlement account, and the TB: create deal field in the payout.
• Funds are not available for withdrawal. Check the deal status, refundable order status, and hold period in the add-on settings.
• Documents are not generated. Check that the PDF Documents add-on is active and document templates are available in admin.