Integration of T-Bank with amoCRM: automatic processing of payments and returns
amoCRM · T-Bank · Laravel · Webhook ·
Developed a server integration that accepts T-Bank notifications, finds the desired transaction in amoCRM and updates it after payment or return.
This is no longer a simple transfer of the form from the landing page to CRM. The system verifies the authenticity of the notification, protects against reprocessing, distinguishes between full payment and installments, saves the transaction history and processes returns separately.
Project task
After payment, the manager does not need to manually search for an order, change the stage of the transaction and transfer data from the bank account to CRM. Integration connects the payment with the order ID and conducts the transaction according to the desired scenario.
The bank must quickly receive confirmation of receipt of the notification, and all work with amoCRM — is performed reliably in the background, even if API CRM is temporarily unavailable.
Therefore, receiving webhook and updating the transaction are separated. The public point accepts and checks the event, stores it in the database and puts the task in the queue. A separate worker addresses the amoCRM and records the result.
How the confirmed payment goes
T-Bank sends notice
Laravel accepts webhook, limits the query size and checks the required fields.
HTTP webhook · rate limit · validationThe system checks the signature.
The signature is recalculated using the bank’s algorithm with the terminal secret. TerminalKey or Token is rejected.
SHA-256 · hash_equalsPayment retained
The event is recorded locally using a unique PaymentId. Re-delivery of the same notification does not create a second processing.
MySQL · idempotenceTask goes in line
Webhook immediately responds to the bank, and integration with CRM is performed by a background task with repeats for temporary errors.
Laravel Queue · retry · lockTransaction updated in amoCRM
The system finds a single transaction with the exact OrderId, checks PaymentId, changes the step and adds a note with the parameters of the operation.
amoCRM API · OrderId · PaymentId
What's automated
Accurate transaction comparison
The search is performed by OrderId. The match must be unique and accurate; PaymentId is used as an additional check, not as an excuse to link the payment to a similar application.
Full payment or installment
The amount of the notification is compared to the full cost of the transaction in whole pennies. An equal amount translates the transaction into a paid, smaller — to the installment stage. Overpayment or incorrect cost requires a manual check.
Note on the card
PaymentId, OrderId, amount, status and confirmation time remain in the transaction. Before adding, the system checks that such a note has not yet been created.
Related unpaid applications
Integration can find other user requests without a validated payment. The match is accepted only when the normalized phone and email are identical.
Return of payment
For REFUNDED status, a separate task is started. It re-verifies OrderId and PaymentId, transfers the transaction to the return stage and adds a separate note.
Secure magazines
Secrets, map data and personal fields are masked before saving the technical payload and writing to the log. Errors remain suitable for diagnosis without disclosing sensitive data.
Reliability in case of repeated notifications and failures: questions and answers
What happens if T-Bank sends one webhook multiple times?
PaymentId is unique in the local table. The re-notification is confirmed to the bank, but does not create a second assignment, note or transition.
What happens if amoCRM is temporarily unavailable?
The payment is already saved locally, so the event is not lost. The background task will repeat the call to amoCRM on a predetermined schedule; frequency limitation errors and 5xx server responses are considered temporary.
What to do if the transaction has not yet appeared in amoCRM?
This is possible when the site creates a transaction almost simultaneously with the payment. Integration considers no deal a temporary situation and repeats the search through the queue.
How does the payment compare to the transaction?
— OrderId main key from the bank notification. Integration requires a single exact match, and PaymentId uses as an additional verification of the identity of the operation.
Can I use the prefix in OrderId?
Yeah. The configured prefix is removed only from the value to search for a trade. The original OrderId is stored unchanged in the local notation and the amoCRM note.
How does the system distinguish between full payment and installments?
The amount of the confirmed payment is compared with the full value of the transaction. An equal amount means full payment, a smaller one transfers the transaction to the configured installment stage.
What happens if the full price of the transaction is not filled?
In the absence of cost, the task will be repeated: the field may not yet have time to fill. An incorrect value is considered a permanent error and does not automatically change the trade.
What happens if the amount of payment is more than the value of the transaction?
Integration does not change the stage automatically. The overpayment is recorded as a situation for manual verification so that an erroneous matching or incorrect cost does not distort the CRM data.
How are the amounts with pennies handled?
Comparison is performed in whole pennies without float. If the amoCRM budget cannot be transferred without rounding, the system terminates the transaction with a clear error instead of changing the amount.
How is a full refund processed?
For a confirmed REFUNDED, a separate task is run. It checks OrderId and PaymentId, transfers the transaction to the return stage and adds a separate note with the transaction parameters.
Will a partial refund close the deal?
Nope. PARTIAL_REFUNDED status does not intentionally move the transaction to the full return stage: it requires a separate business rule.
Can a later payment notice cancel an already accepted refund?
Nope. After a refund is accepted, an outdated payment confirmation does not return the record and the transaction to its previous state.
What happens in a OrderId conflict or return amount?
The transaction does not close automatically. The event is saved with the status of manual verification, and the already confirmed payment history remains unchanged.
Can two workers process one payment at the same time?
For one payment, a task lock and conditional state changes are used. Parallel or late worker shall not renew the transaction.
Do secrets and map data get into technical logs?
Nope. Token, terminal password, card data and contact fields are masked before saving payload and recording diagnostic information.
Project technologies
- Backend
- Laravel / PHP webhook, business rules and API integration
- MySQL status of payments and protection against doubles
- Background processing
- Laravel Queue charge-back
- Queue worker Repetitions and recovery after failures
- External systems
- T-Bank API signed notices
- amoCRM API / OAuth search and update
- Operation
- Docker isolation
- Tests webhook, doubles, installments, crashes and returns
The result
Payment goes from a bank notification to an updated amoCRM card without manual data transfer. The manager sees the current stage of the transaction and the history of the transaction, and technical failures do not result in the loss of the event or re-conducting the payment.
The architecture can be adapted to a different site, a set of stages amoCRM and payment rules: full amount, installment, refund or additional verification of related applications.
Need payment integration with CRM?
I will help link the site, the payment service and amoCRM: design scripts, implement webhook and queue, take into account repeated notifications, errors API and returns.