Development of Bitrix24 integration with banking systems

Developing Bitrix24 Integration with Banking Systems

Integrating a CRM with a bank is not just "viewing a bank statement directly in a deal." It means synchronising payment status, automatically processing invoices, monitoring receivables, and triggering sales funnel stages. The implementation depends on the specific bank and the API it provides. Let's walk through the architecture from general to specific.

What Businesses Typically Need

Before designing an integration, it is important to define concrete scenarios. In practice, requests fall into three groups:

Outgoing payments. Exporting payment orders from Bitrix24 to the bank — bypassing manual entry in the bank client. A manager creates a vendor payment invoice in the CRM, the CFO approves it, and the system automatically generates the payment and sends it to the bank via API.

Incoming payments. Webhook or statement polling: as soon as the bank registers an incoming payment, the deal in the CRM changes stage, the manager receives a notification, and an act is generated. Without integration, the manager learns about the payment by chance or at the end of the day.

Reference operations. Balance checks, currency rate lookups, and counterparty details verification (via the FTS API or directly through the bank's verification service).

Technical Integration Paths

Bank OpenAPI. Most major banks provide REST APIs for business. Authentication uses OAuth 2.0 with the Client Credentials flow. The bank issues a client_id and client_secret, and in return you get an access_token with a limited lifetime (typically 30 minutes). The token is refreshed via refresh_token or by re-authenticating. Tokens must be stored in a secure storage — encrypted in the database or using environment variables.

1C DirectBank interface. Some banks support the DirectBank protocol (direct exchange without a bank client). Technically it is an XML protocol over HTTPS, with documents compatible with 1C. If the company already has 1C:Accounting set up with DirectBank, it is easier to build the Bitrix24 integration through 1C as an intermediary rather than directly with the bank.

File exchange. The classic approach — exporting in the 1C:Enterprise format (.txt with the 1CClientBankExchange header) and importing into the bank client manually or via automatic folder monitoring. Requires no API access and works with any bank.

Application Architecture in Bitrix24

The integration is implemented as a local application or a built-in REST handler. The scheme:

Bitrix24 CRM
   ↓ Webhook / Robot
Handler (PHP, own server, or server-side of the app)
   ↓ OAuth2 token
Bank API
   ↓ Response
Update CRM entities via crm.deal.update / crm.invoice.update

For incoming payments — the reverse scheme: the bank sends a webhook to our endpoint, which updates the deal state via crm.deal.update or crm.timeline.comment.add.

Payment state storage: we add UF_BANK_PAYMENT_ID (a custom field) to the deal and invoice — the external payment identifier in the bank. This enables idempotent processing of repeated webhook notifications and checking the status of a specific payment.

Working with Bank Statements

A bank statement arrives in JSON format (via API) or as SWIFT MT940/camt.053 (for international banks). We parse the transactions: amount, date, payment reference, and payer's tax ID. Using the tax ID or account number, we search for the counterparty in the CRM via crm.company.list with a filter on details. If the counterparty is found, we look for an open invoice for the matching amount.

The difficulty lies in the payment reference. "Payment for invoice No. 145 dated 12.03.2025" — easy, extracting the invoice number is straightforward. "Payment for services" — problematic, requiring manual matching. For the latter case we build a manual matching interface: a list of unrecognised receipts with the ability to link them to a deal manually.

Security and Key Storage

The banking API is a critical integration circuit. Requirements:

• Tokens are stored encrypted (AES-256); the encryption key is in environment variables, not in code
• API requests go only over HTTPS, with SSL certificate verification mandatory
• Logs of all API calls with masking of sensitive data (account number and amount are logged; CVV and tokens never are)
• IP whitelist on the bank's side — only our servers' IPs are allowed
• For the webhook endpoint — request signature validation (the bank signs the payload with HMAC-SHA256 using a secret key)

Error Handling and Retries

Banking APIs are unstable. Typical scenarios: timeout when creating a payment (unknown whether it went through), temporary service unavailability, request limits (rate limiting). Each scenario requires its own logic.

For critical operations (sending a payment order) we use a queue with idempotency keys: before sending, generate an idempotency_key (UUID) and pass it in the request header. When retrying with the same key, the bank does not duplicate the payment.

Development Stages

Actual timelines shift depending on the quality of the bank's documentation and the availability of a sandbox environment. Tinkoff and Alfa-Bank have good sandboxes. Some regional banks do not, so debugging must be done carefully in the production environment with test amounts.