Что нужно до начала
Договор с платёжной системой заключает бизнес, и деньги приходят на его расчётный счёт. В документации Payme прямо сказано: с кассами могут работать только юридические лица — в перечне ИП, ЧП, ООО, АО, ГУП, СП и НОУ. Разработчик подключает протокол, но не стоит между вами и деньгами.
- Юрлицо и расчётный счёт. Без них кассу не откроют.
- Касса в кабинете платёжной системы. У Payme Business их три вида: с биллингом, без биллинга и для оплаты на месте. Для сайта и бота с заказами нужна касса с биллингом — тогда платёжная система сверяет каждый платёж с вашим сервером.
- Сервер с HTTPS. Payme и Click обращаются к нему сами, поэтому он должен быть доступен из интернета постоянно, а не только когда открыт сайт.
- Коды ИКПУ на все товары и услуги. Без них не сформировать фискальный чек — об этом ниже.
Payme: сервер отвечает на вызовы платёжной системы
У Payme Business два протокола. В Merchant API запросы отправляет Payme, а ваше приложение отвечает — это стандартный путь при оплате через платёжную форму Payme. В Subscribe API наоборот: ваше приложение вызывает Payme, что нужно для привязки карты, оплаты в один клик, регулярных платежей и собственной платёжной формы.
В Merchant API обмен идёт по JSON-RPC 2.0 поверх HTTPS, методом POST. Payme представляется через базовую HTTP-аутентификацию, паролем служит ключ кассы, который выдаёт технический специалист Payme Business. Запрос с неверными данными сервер обязан отклонить с ошибкой -32504. Сервер обязан отвечать с HTTP-статусом 200; любой другой статус Payme считает системной ошибкой. Суммы передаются в тийинах.
Две детали протокола определяют всю надёжность интеграции. Первая: если транзакция не завершена за 12 часов, Payme отменяет её по таймауту с причиной 4. Вторая: если ответ на CreateTransaction или PerformTransaction потерялся, Payme повторяет запрос с теми же параметрами. Значит, сервер обязан узнать повтор и вернуть тот же результат, а не создать вторую транзакцию. Если ответа нет долго, платёж уходит на ручной разбор к сотруднику Payme.
Click: два подписанных шага
В Shop API Click взаимодействие разделено на два этапа, и оба запроса Click отправляет на ваш сервер в формате form-urlencoded; отвечать нужно в JSON.
- 01Prepare (action = 0). Проверить, что заказ существует и актуален, сумма верна, товар можно отпустить. Интернет-магазин на этом шаге резервирует товар, чтобы его не продали дважды. В ответе вы возвращаете свой номер платежа — merchant_prepare_id.
- 02Complete (action = 1). Click сообщает результат списания и присылает тот же merchant_prepare_id. Вы фиксируете оплату и возвращаете merchant_confirm_id.
Каждый запрос подписан. Подпись — md5 от идентификаторов платежа, секретного ключа, суммы, действия и времени. Сервер обязан пересчитать её сам и при расхождении вернуть ошибку -1. Без этой проверки любой, кто знает адрес вашего обработчика, может «оплатить» заказ поддельным запросом.
Prepare: md5(click_trans_id + service_id + SECRET_KEY + merchant_trans_id + amount + action + sign_time)
Complete: md5(click_trans_id + service_id + SECRET_KEY + merchant_trans_id + merchant_prepare_id + amount + action + sign_time)По правилам Click, если Prepare прошёл успешно и деньги списаны, ответ на Complete не может быть ошибкой — кроме двух случаев: платёж уже подтверждён (-4) или ранее отменён (-9). Если товар отпустить не получилось уже после списания, сервер отвечает «успешно» и сам инициирует отмену платежа через Merchant API Click. Повторяющиеся ошибочные ответы переводят платёж на ручное разбирательство в поддержке Click.
Uzum Bank
У Uzum Bank для онлайн-оплаты два продукта. Checkout — платёжная форма для сайта, приложения или бота: оплата картами, привязка карт, возвраты, статусы и фискализация. Merchant API — приём оплаты из приложения Uzum Bank: клиент выбирает ваш сервис в приложении банка, а ваш сервер обрабатывает уведомления о платеже. Подключение идёт через партнёрскую заявку банка.
Архитектурно это тот же принцип: сервер проверяет заказ, фиксирует результат и отвечает. Поэтому третью платёжную систему разумно закладывать сразу: общая логика заказа и сверки одна, отличается только адаптер под протокол.
Фискальный чек и коды ИКПУ
Покупатель должен получить фискальный чек, и для этого платёжной системе нужно знать состав покупки. В Payme это объект detail в ответе на CheckPerformTransaction: по каждой позиции название, цена за единицу в тийинах, количество, код ИКПУ, код упаковки и ставка НДС — все эти поля обязательны. Код упаковки берётся из карточки ИКПУ в государственном классификаторе tasnif.soliq.uz. Отдельный метод SetFiscalData позволяет получить от Payme данные готового чека, включая ссылку на QR-код; для отмены формируется второй, отдельный чек.
В Click фискализация — отдельный API: после оплаты сервер отправляет состав покупки с кодом ИКПУ (поле SPIC), кодом упаковки, суммой и процентом НДС, а затем может получить ссылку на чек. Запросы подписываются заголовком Auth с хэшем sha1 от времени и секретного ключа.
- Код ИКПУ и код упаковки для каждого товара и услуги, включая доставку.
- Ставку НДС по каждой позиции.
- Правило для скидок и промокодов: сумма позиций в чеке должна совпадать с суммой оплаты.
- Порядок возврата: при отмене платежа нужен отдельный чек возврата.
Типичные ошибки, из-за которых теряются деньги
Как проходит подключение
- 01
Договор и касса
Вы подаёте заявку в Payme, Click или Uzum, получаете кассу, идентификаторы и ключи. Ключи передаются только на сервер, не в код сайта или бота.
- 02
Модель заказа
Описываем, когда создаётся заказ, что бронируется, какие статусы бывают и что считается оплатой. Это одна логика для всех платёжных систем.
- 03
Протоколы и тесты в песочнице
Реализуем методы Payme и шаги Click, проверяем в песочнице все сценарии: успех, отказ, повтор, таймаут, отмена после оплаты. У Payme есть песочница, у Click — тестовая среда и коллекция запросов.
- 04
Чеки, сверка и оповещения
Подключаем фискализацию, ежедневную сверку с кабинетом и оповещение в Telegram при любом расхождении.
- 05
Перенос на рабочий сервер
Переключаем кассу на боевой режим и проводим контрольную покупку на минимальную сумму с возвратом.
Подключение платёжных систем к готовому сайту или боту попадает в уровень «Связка» на странице подключения Payme, Click и Uzum: $2 500–6 000, от двух недель. Если магазина ещё нет, оплата закладывается в проект интернет-магазина с самого начала. Договор фиксирует цену и срок, за просрочку — 2% в день, но не больше 10%; рабочую версию вы видите каждые две недели.
Чек-лист перед запуском
- Статус «оплачено» ставит только сервер по запросу платёжной системы.
- Повторный запрос с тем же идентификатором возвращает прежний результат и ничего не создаёт.
- Сервер проверяет подпись Click и авторизацию Payme.
- Сумма проверяется при каждом запросе; единицы — сумы или тийины — не перепутаны.
- Каждый входящий запрос и ответ пишется в журнал.
- Есть ежедневная сверка с кабинетом и оповещение о расхождениях.
- Фискальный чек формируется с правильными ИКПУ, кодами упаковки и НДС.
- Проверены отмена и возврат, включая чек возврата.
Частые вопросы
Что выбрать: Payme, Click или Uzum?
Обычно все сразу: покупатели пользуются разными приложениями, и отсутствие привычного способа оплаты стоит продаж. Логика заказа и сверки общая, поэтому каждая следующая система добавляется заметно дешевле первой.
Можно ли принимать оплату в Telegram-боте без сайта?
Да. Боту всё равно нужен сервер, который принимает запросы платёжной системы и меняет статус заказа, но отдельный сайт для этого не обязателен. Бот выдаёт кнопку оплаты, сервер подтверждает платёж, бот присылает клиенту чек и статус заказа.
Почему нельзя ставить «оплачено» на странице «спасибо за оплату»?
Потому что эту страницу можно открыть без оплаты, а после оплаты можно до неё не дойти. Единственный надёжный источник — запрос платёжной системы на ваш сервер: PerformTransaction у Payme и Complete у Click.
Что будет, если наш сервер был недоступен во время оплаты?
Payme повторяет запросы с теми же параметрами, а при долгом отсутствии ответа передаёт платёж на ручной разбор. Click после нескольких неудачных попыток тоже переводит платёж в ручное разбирательство. Поэтому сервер должен корректно обрабатывать повторы, а ежедневная сверка — ловить всё, что прошло мимо.
Нужен ли фискальный чек при оплате через Payme и Click?
Покупатель должен получить фискальный чек. Платёжные системы формируют его по данным, которые передаёт ваш сервер: для каждой позиции нужны код ИКПУ, код упаковки и ставка НДС. Без них чек не сформируется.
Сколько стоит подключение и сколько занимает?
Подключение к готовому сайту или боту — уровень «Связка», $2 500–6 000, от двух недель. Точная сумма зависит от числа платёжных систем, фискализации и того, куда передаются статусы: в CRM, 1С или только в админку. Остальные вилки — на странице цен.
Источники
Утверждения из статьи можно проверить: ниже первоисточники, а не пересказ.
- 01Payme Business: настройка взаимодействия, Merchant API и Subscribe API
- 02Payme Business: схема взаимодействия, авторизация и повторы запросов
- 03Payme Business: протокол Merchant API (JSON-RPC 2.0, HTTP 200)
- 04Payme Business: методы Merchant API и объект detail для фискализации
- 05Payme Business: CreateTransaction и таймаут 12 часов
- 06Payme Business: типы данных и состояния транзакции
- 07Click: Shop API, запросы Prepare и Complete
- 08Click: Shop API, коды ошибок
- 09Click: фискализация товаров и услуг
- 10Uzum Bank: документация для партнёров (Checkout, Merchant API)
Материалы пишут инженеры, работающие на проектах, и выходят от имени редакции. За каждый текст отвечает студия и опубликованные правила редакции, а не один автор; материалы о собственном открытом коде подписаны автором.
Как мы пишем и что проверяем