Как принимать оплату через Payme и Click на сайте и в Telegram-боте

Коротко: и Payme, и Click работают одинаково по сути — платёжная система сама обращается к вашему серверу, а сервер проверяет заказ, фиксирует оплату и отвечает. Сайт и Telegram-бот используют один и тот же серверный модуль. Деньги теряются не в платёжной системе, а в вашей логике: повторные запросы, потерянные уведомления и заказы, созданные не в тот момент.

10 мин чтения

Коротко

  • Payme по протоколу Merchant API сам вызывает шесть основных методов на вашем сервере; у транзакции четыре состояния, неподтверждённая отменяется через 12 часов.
  • Click в Shop API делает два подписанных запроса — Prepare и Complete; подпись — md5 от параметров и секретного ключа.
  • Uzum Bank даёт платёжную форму Checkout для сайта и бота и Merchant API для оплаты из своего приложения.
  • Для фискального чека каждой позиции нужен код ИКПУ, код упаковки и ставка НДС.
  • Главные ошибки: нет идемпотентности, потерянное уведомление и заказ, который создаётся после оплаты в браузере.

Что нужно до начала

Договор с платёжной системой заключает бизнес, и деньги приходят на его расчётный счёт. В документации 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 считает системной ошибкой. Суммы передаются в тийинах.

Метод
Что должен сделать ваш сервер
CheckPerformTransaction
Проверить, что заказ существует, сумма верна и оплата возможна. Здесь же передаются данные для фискального чека
CreateTransaction
Сохранить транзакцию в постоянное хранилище, забронировать заказ, запретить его менять, поставить статус «ожидание оплаты»
PerformTransaction
Зачесть оплату и перевести заказ в «оплачен»
CancelTransaction
Отменить созданную или проведённую транзакцию; если услуга уже оказана полностью — вернуть ошибку -31007
CheckTransaction
Вернуть текущее состояние транзакции и время каждого перехода
GetStatement
Отдать список транзакций за период — для сверки
Состояние
Значение
1
Транзакция создана, ждёт подтверждения
2
Транзакция завершена — деньги списаны
-1
Отменена до завершения, в том числе по таймауту
-2
Отменена после завершения — возврат

Две детали протокола определяют всю надёжность интеграции. Первая: если транзакция не завершена за 12 часов, Payme отменяет её по таймауту с причиной 4. Вторая: если ответ на CreateTransaction или PerformTransaction потерялся, Payme повторяет запрос с теми же параметрами. Значит, сервер обязан узнать повтор и вернуть тот же результат, а не создать вторую транзакцию. Если ответа нет долго, платёж уходит на ручной разбор к сотруднику Payme.

Click: два подписанных шага

В Shop API Click взаимодействие разделено на два этапа, и оба запроса Click отправляет на ваш сервер в формате form-urlencoded; отвечать нужно в JSON.

  1. 01Prepare (action = 0). Проверить, что заказ существует и актуален, сумма верна, товар можно отпустить. Интернет-магазин на этом шаге резервирует товар, чтобы его не продали дважды. В ответе вы возвращаете свой номер платежа — merchant_prepare_id.
  2. 02Complete (action = 1). Click сообщает результат списания и присылает тот же merchant_prepare_id. Вы фиксируете оплату и возвращаете merchant_confirm_id.

Каждый запрос подписан. Подпись — md5 от идентификаторов платежа, секретного ключа, суммы, действия и времени. Сервер обязан пересчитать её сам и при расхождении вернуть ошибку -1. Без этой проверки любой, кто знает адрес вашего обработчика, может «оплатить» заказ поддельным запросом.

text
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 Shop API

По правилам 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 от времени и секретного ключа.

Что подготовить для чеков
  • Код ИКПУ и код упаковки для каждого товара и услуги, включая доставку.
  • Ставку НДС по каждой позиции.
  • Правило для скидок и промокодов: сумма позиций в чеке должна совпадать с суммой оплаты.
  • Порядок возврата: при отмене платежа нужен отдельный чек возврата.

Типичные ошибки, из-за которых теряются деньги

Ошибка
К чему приводит
Нет идемпотентности
Payme повторяет CreateTransaction и PerformTransaction при потере ответа. Сервер, который не узнаёт повтор, создаёт второй заказ, начисляет бонусы дважды или отправляет товар повторно. Подробный разбор — в статье про идемпотентность платежей.
Потерянное уведомление
Сервер был перезапущен, упал или ответил не тем HTTP-статусом. Деньги списаны, а заказ «не оплачен». Лечится журналом каждого входящего запроса, ответом строго по протоколу и ежедневной сверкой через GetStatement.
«Оплачено», а заказа нет
Заказ создаётся в браузере после возврата со страницы оплаты. Покупатель закрыл вкладку — деньги есть, заказа нет. Правильно наоборот: заказ создаётся до оплаты, а статус меняет только сервер по запросу платёжной системы.
Нет проверки подписи и источника
Обработчик принимает любой запрос. Поддельный Complete или PerformTransaction переводит заказ в оплаченный без денег.
Заказ меняется во время оплаты
Покупатель добавил товар во второй вкладке, сумма разошлась. Протоколы требуют бронировать заказ на время оплаты.
Деньги в дробных числах
Сумы и тийины в типе с плавающей точкой дают копеечные расхождения в сверке. Хранить нужно целым числом в тийинах.

Как проходит подключение

От договора до первой оплаты
  1. 01

    Договор и касса

    Вы подаёте заявку в Payme, Click или Uzum, получаете кассу, идентификаторы и ключи. Ключи передаются только на сервер, не в код сайта или бота.

  2. 02

    Модель заказа

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

  3. 03

    Протоколы и тесты в песочнице

    Реализуем методы Payme и шаги Click, проверяем в песочнице все сценарии: успех, отказ, повтор, таймаут, отмена после оплаты. У Payme есть песочница, у Click — тестовая среда и коллекция запросов.

  4. 04

    Чеки, сверка и оповещения

    Подключаем фискализацию, ежедневную сверку с кабинетом и оповещение в Telegram при любом расхождении.

  5. 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С или только в админку. Остальные вилки — на странице цен.

Источники

Утверждения из статьи можно проверить: ниже первоисточники, а не пересказ.

  1. 01Payme Business: настройка взаимодействия, Merchant API и Subscribe API
  2. 02Payme Business: схема взаимодействия, авторизация и повторы запросов
  3. 03Payme Business: протокол Merchant API (JSON-RPC 2.0, HTTP 200)
  4. 04Payme Business: методы Merchant API и объект detail для фискализации
  5. 05Payme Business: CreateTransaction и таймаут 12 часов
  6. 06Payme Business: типы данных и состояния транзакции
  7. 07Click: Shop API, запросы Prepare и Complete
  8. 08Click: Shop API, коды ошибок
  9. 09Click: фискализация товаров и услуг
  10. 10Uzum Bank: документация для партнёров (Checkout, Merchant API)
Инженерная редакция dbit.one
Инженеры, которые строят эти системы

Материалы пишут инженеры, работающие на проектах, и выходят от имени редакции. За каждый текст отвечает студия и опубликованные правила редакции, а не один автор; материалы о собственном открытом коде подписаны автором.

Как мы пишем и что проверяем

Услуги по теме

Читать дальше

Инженерия6 мин чтения

Повтор запроса не должен списывать деньги дважды

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

Цены и сроки5 мин чтения

Сколько стоит разработка интернет-магазина

Коротко: магазин с каталогом до 500 товаров, оплатой, доставкой и панелью управления стоит $6 000–12 000 и запускается примерно за 5 недель. Магазин с обменом с 1С, личным кабинетом и бонусами — $15 000–30 000, сеть со складами, оптом и приложением — $40 000–80 000. Ниже — из чего складывается сумма, что раздувает её незаметно и на чём точно не стоит экономить.

Выбор и процесс11 мин чтения

Техническое задание на разработку сайта и приложения: образец

Коротко: техническое задание (ТЗ) — документ, по которому подрядчик считает цену и срок, а вы принимаете работу. Для сайта, бота или приложения не нужен том на сто страниц. Достаточно нескольких страниц, где описаны цель, пользователи и их роли, сценарии с критериями приёмки, функции к запуску, интеграции, требования к скорости и безопасности и то, на кого оформляются домен, аккаунты и код. Ниже — образец ТЗ из 12 разделов, который можно скопировать и заполнить, примеры размытых и проверяемых формулировок, частые пропуски и то, как ТЗ влияет на смету. Если писать документ сейчас некогда, начните с брифа на нашем сайте: 25 вопросов на языке бизнеса и предварительная вилка цены в конце.

Остались вопросы по вашему проекту?

Опишите задачу — в течение 24 часов вернёмся с оценкой, сроками и планом.

hello@dbit.one