Payme и Click для сайта: как устроена интеграция в Узбекистане

Интеграция Payme и Click для сайта в Узбекистане строится по общей схеме: сайт создаёт заказ и отправляет покупателя на оплату, а платёжная система обращается к вашему серверу с запросами «проверить заказ» и «подтвердить оплату». Ваш сервер должен отвечать в строго заданном формате, проверять подлинность запросов и корректно менять статус заказа. Точные методы, поля и коды ошибок у каждой системы свои, и их нужно брать из актуальной документации провайдера.

Ниже общая архитектура и принципы, которые одинаково полезны и для Payme, и для Click, и для похожих сервисов. Конкретные параметры я намеренно не привожу: они меняются, а ошибка в одном поле останавливает приём платежей.

Как работает оплата: модель «система обращается к вам»

В привычной многим схеме сайт сам спрашивает у банка, прошла ли оплата. В Узбекистане для Payme и Click чаще встречается другая модель: платёжная система сама вызывает ваш сервер. Это называют обратными вызовами (callbacks) или merchant API.

Упрощённый ход событий:

1. Покупатель оформляет заказ, сайт сохраняет его с уникальным номером и статусом «ожидает оплаты».
2. Сайт формирует ссылку или форму для перехода на страницу оплаты провайдера, передавая идентификатор заказа и сумму.
3. Покупатель оплачивает на стороне провайдера.
4. Провайдер отправляет на ваш адрес запрос: сначала проверку, возможна ли оплата этого заказа на эту сумму, затем подтверждение.
5. Ваш сервер отвечает, провайдер завершает операцию, сайт меняет статус заказа на «оплачен».
6. Покупателя возвращают на страницу результата.

Важное следствие: страница «спасибо» не доказывает оплату. Покупатель может закрыть вкладку или не вернуться, и только запрос от провайдера на сервер подтверждает факт платежа. Статус нужно менять по серверному уведомлению, а не по переходу пользователя.

Что нужно подготовить на стороне сайта

До начала работы с любым провайдером убедитесь, что у вас есть:

• уникальный идентификатор заказа, который не повторяется и не угадывается;
• точная сумма заказа в виде, согласованном с провайдером (например, в минимальных единицах валюты, если так требует документация; уточняйте);
• публично доступный адрес обработчика с https и корректным сертификатом;
• таблица платежей в базе, отдельная от таблицы заказов;
• механизм журналирования всех входящих запросов;
• договорённость, какие товары или услуги можно оплачивать онлайн и как оформляются возвраты.

Подключение как продавца идёт через оформление мерчанта у провайдера: заявка, документы, согласование, получение идентификаторов и ключей. Требования к юридическому лицу или предпринимателю и сроки проверки зависят от провайдера, их нужно уточнять у него напрямую.

Проверка заказа и подтверждение: два шага, которые нельзя смешивать

На первом шаге провайдер спрашивает: можно ли принять оплату по заказу номер такой-то на такую-то сумму. Ваш обработчик должен проверить:

• существует ли заказ;
• не оплачен ли он уже и не отменён ли;
• совпадает ли сумма с суммой заказа;
• не истёк ли срок оплаты, если он у вас есть.

Если проверка не пройдена, нужно ответить ошибкой в формате, который описывает провайдер. Не придумывайте собственные коды: система ожидает определённый набор.

На втором шаге приходит подтверждение, и здесь обработчик создаёт запись о платеже, меняет статус заказа и запускает действия (письмо, передача в склад, начисление баланса). Тонкость в том, что подтверждения могут приходить повторно, а запросы бывают дублированными, поэтому логика должна быть идемпотентной. Подробно об этом написано в статье про повторные уведомления от платёжных систем.

Схема для базы, которую я использую как основу (условная):

payments:
  id
  order_id
  provider          -- 'payme' | 'click' | ...
  provider_txn_id   -- идентификатор транзакции у провайдера (уникальный в паре с provider)
  amount
  state             -- created | confirmed | cancelled
  created_at, updated_at
  raw_request       -- сырое тело запроса для разбора споров

Уникальный индекс по паре provider и provider_txn_id защитит от создания дублей при повторных запросах.

Подпись и аутентификация запросов

Любой адрес, на который приходят уведомления об оплате, находится в открытом интернете, и злоумышленник может попытаться отправить «поддельное подтверждение». Поэтому провайдеры предусматривают способы убедиться, что запрос пришёл от них: подпись, секретный ключ, заголовок авторизации. Конкретный механизм у Payme и Click отличается, и его нужно реализовать строго по документации.

Общие правила, которые не зависят от провайдера:

1. Секретные ключи хранятся вне репозитория, в переменных окружения или защищённой конфигурации.
2. Сравнение подписей выполняется функцией безопасного сравнения, а не обычным оператором равенства.
3. Подпись проверяется до любых действий с базой.
4. Запросы с неверной подписью отклоняются и записываются в журнал.
5. Сумма берётся из вашей базы, а не из запроса, и сверяется с суммой в запросе.

Более широкая тема защиты рассмотрена в материале про безопасность платежей на сайте: подпись, журнал и защиту от подделки.

Тестовая среда и подготовка к запуску

У провайдеров обычно есть тестовый режим или песочница, но возможности и порядок доступа различаются. Не рассчитывайте, что всё, что работает в тесте, заработает в боевом режиме без изменений: адреса, ключи и поведение могут отличаться.

Что я проверяю перед запуском:

• успешная оплата, ответ сервера, смена статуса, письмо клиенту;
• отказ в оплате и возврат пользователя на сайт с понятным сообщением;
• повторное подтверждение того же платежа: статус и побочные действия не должны дублироваться;
• неверная сумма и несуществующий заказ: сервер отвечает ошибкой в нужном формате;
• заказ, оплаченный после истечения срока, и отмена заказа до оплаты;
• недоступность вашего сервера на несколько минут: что произойдёт с запросами и как они повторятся;
• возврат или отмена платежа, если провайдер это поддерживает.

Полный перечень сценариев вынесен в отдельную статью: тестирование платёжной интеграции.

Чеки, учёт и сверка

Приём платежа это только часть процесса. Нужно решить, как будет оформляться фискальный чек, если он требуется для вашего вида деятельности, как данные попадут в учётную систему и как вы будете сверять поступления. Требования к кассовой технике и чекам в Узбекистане зависят от законодательства и вида деятельности, поэтому уточняйте их у бухгалтера и в налоговых разъяснениях. На стороне технологии существуют сервисы онлайн-касс, например Regos, и о подходе к ним есть отдельный материал: фискальные чеки при онлайн-оплате.

Для сверки заведите ежедневную процедуру: сравнение списка платежей у провайдера (реестр или выгрузка, если доступно) с вашей таблицей. Расхождения чаще всего возникают из-за недошедших уведомлений и ручных операций.

Статусы заказа: небольшая схема, которая экономит нервы

Практически все проблемы с онлайн-оплатой связаны с тем, что статусы заказа и платежа смешаны в одно поле. Я разделяю их и описываю допустимые переходы заранее.

Для заказа достаточно четырёх состояний: новый, ожидает оплаты, оплачен, отменён. Для платежа: создан, подтверждён, отменён. Переход заказа в «оплачен» происходит только при подтверждённом платеже на полную сумму. Если провайдер поддерживает отмену уже проведённого платежа, нужен отдельный сценарий: что происходит с заказом, товаром и документами.

Такую схему стоит согласовать с бухгалтерией и отделом продаж до начала разработки, потому что от неё зависят отчёты и выгрузки. Если сайт связан с учётной системой, статусы должны однозначно сопоставляться с документами там, иначе при сверке появятся расхождения.

Частые вопросы

Нужно ли подключать обе системы сразу?

Нет, это зависит от вашей аудитории. Многие покупатели пользуются обоими сервисами, поэтому наличие двух вариантов повышает вероятность, что клиент оплатит. Но каждый провайдер добавляет поддержку и отладку. Можно начать с одного и добавить второй позже, если архитектура оплаты общая для провайдеров.

Можно ли подключить через готовый модуль CMS?

Для популярных платформ существуют готовые модули. Их можно использовать, но проверьте актуальность, обновления и безопасность, а также то, как модуль ведёт себя при повторных уведомлениях. Для нестандартной логики заказа чаще нужна собственная реализация.

Как защититься от подмены суммы?

Никогда не доверяйте сумме, пришедшей от браузера. Сумма заказа определяется на сервере, и при проверке и подтверждении платежа сравнивается с суммой в запросе провайдера.

Что делать, если уведомление не пришло?

Предусмотрите процедуру ручной и автоматической сверки: по заказам в статусе «ожидает оплаты» через определённое время запрашивайте статус у провайдера, если такой метод доступен, или сверяйте по выгрузке. Решение зависит от возможностей конкретной системы.

Если вам нужна интеграция Payme, Click или других платёжных сервисов с сайтом, посмотрите страницу об интеграциях платёжных систем или опишите задачу в Telegram.