Типичные ошибки при интеграции платежного API
Интеграция платежного API — задача, которая на первый взгляд кажется простой, но на практике содержит множество подводных камней. Неправильная обработка одного статуса может привести к потере заказов, конфликтам с клиентами и финансовым потерям. В этой статье мы разберем самые частые ошибки, которые допускают разработчики при интеграции P2P-платежных API, и как их избежать.
Ошибка 1: Неправильный формат суммы
Самая распространенная ошибка — передача суммы в неправильном формате. В P2P-API сумма передается в минимальных единицах валюты. Для рублей это копейки, то есть 1000 означает 10 рублей. Для тенге — тиыны, для белорусских рублей — копейки.
Если передать 1000 вместо 100000 (имея в виду 1000 рублей), клиенту будет выставлен счет на 10 рублей. Если передать 100000 вместо 10000000 (имея в виду 1000 рублей, но с учетом precision), счет будет на 1000 рублей, что правильно.
Решение: всегда использовать минимальные единицы валюты. Проверять precision валюты из GET /api/currencies. Использовать целочисленную арифметику для расчета суммы.
Ошибка 2: Игнорирование лимитов платежных методов
Каждый платежный метод имеет минимальный и максимальный лимиты. Если сумма сделки выходит за пределы этих лимитов, API возвращает ошибку 400 с сообщением об отсутствии подходящих реквизитов.
Решение: перед созданием сделки проверять сумму на соответствие лимитам выбранного метода. При превышении лимита предлагать клиенту разбить платеж на части или выбрать другой метод.
Ошибка 3: Необработка всех подстатусов
Многие мерчанты обрабатывают только основные статусы (success, fail, pending) и игнорируют детальные подстатусы. Это приводит к тому, что сделка может зависнуть в промежуточном состоянии, и ни мерчант, ни клиент не знают, что делать дальше.
Решение: обрабатывать все подстатусы из документации. Для каждого подстатуса определить действие: отобразить клиенту реквизиты, ожидать перевода, подтвердить заказ, отменить заказ, приостановить выполнение.
Ошибка 4: Отсутствие дедупликации callback-уведомлений
Платежная система может отправить одно и то же уведомление несколько раз, если не получила подтверждение получения (HTTP 200). Если мерчант не реализовал дедупликацию, это приведет к двойному подтверждению заказа или двойной отправке товара.
Решение: использовать ID уведомления или ID сделки для дедупликации. Хранить обработанные ID в базе данных и проверять перед обработкой.
Ошибка 5: Синхронная обработка callback
Если сервер мерчанта обрабатывает callback синхронно (внутри HTTP-запроса), а обработка занимает много времени (отправка email, обновление БД, интеграция с CRM), клиент (платежная система) может прервать соединение по тайм-ауту.
Решение: возвращать HTTP 200 сразу, а обработку выполнять асинхронно через очередь задач (RabbitMQ, Redis Queue, Sidekiq).
Ошибка 6: Неправильный выбор типа API
Merchant API проще, но не предоставляет полного контроля. H2H API сложнее, но дает возможности для управления спорами. Выбор неправильного типа API приводит к тому, что мерчант не может выполнить необходимые операции.
Решение: для интернет-магазинов с простыми сценариями — Merchant API. Для платформ с полным циклом управления — H2H API.
Ошибка 7: Отсутствие обработки тайм-аутов
При высокой нагрузке API может не уложиться в заданный тайм-аут. Если мерчант не обрабатывает ошибку 504, клиент не получает реквизиты для оплаты и уходит с сайта.
Решение: использовать заголовок X-Max-Wait-Ms для контроля тайм-аута. При ошибке 504 повторять запрос с увеличивающейся задержкой. Отображать клиенту индикатор загрузки.
Ошибка 8: Непроверка IP-адресов отправителя callback
Любой может отправить POST-запрос на callback-эндпоинт мерчанта, имитируя уведомление от платежной системы. Если не проверять источник, мошенники могут подделать статус сделки.
Решение: проверять IP-адреса отправителя. Платежная система отправляет уведомления с определенных IP-адресов. Использовать HMAC-подпись для верификации уведомлений, если она поддерживается.
Ошибка 9: Хранение Access-Token в исходном коде
Хранение токена доступа в коде, который попадает в систему контроля версий (Git), создает риск утечки. Если токен попадет к злоумышленникам, они смогут создавать сделки и управлять балансом.
Решение: хранить Access-Token в переменных окружения (ENV), использовать отдельные токены для разработки и продакшена, регулярно ротировать токены.
Ошибка 10: Отсутствие мониторинга и алертов
Если платежная система недоступна или мерчант перестал получать callback-уведомления, это может остаться незамеченным в течение нескольких часов или дней.
Решение: настроить мониторинг доступности API, настроить алерты при отсутствии callback-уведомлений в течение заданного времени, вести логи всех запросов и ответов API.
Выводы
Интеграция платежного API требует внимания к деталям. Большинство ошибок связано с неправильной обработкой статусов, отсутствием дедупликации и игнорированием лимитов. Следуя рекомендациям из этой статьи, можно избежать типичных проблем и построить надежную платежную систему.
