Как подключить Click, Payme и Uzum к сайту или приложению: приём онлайн-оплаты в Узбекистане

Чтобы подключить Payme, Click или Uzum к сайту, интернет-магазину или мобильному приложению, компании в Узбекистане не нужно выходить на карточный процессинг напрямую. Нужны договор с платёжным провайдером — Payme Business, Click или Uzum Bank — и интеграция, которая свяжет его с вашей системой заказов. От интеграции зависит, не останется ли заказ «неоплаченным», когда деньги уже списаны, не пробьётся ли чек дважды и получится ли вернуть деньги без звонков в поддержку. Разбираем, как устроен приём платежей на сайте в Узбекистане, что подготовить заранее, как проходят оплата и возврат, как настроить фискализацию чеков с ИКПУ и что проверить перед запуском.

Как устроена онлайн-оплата на сайте в Узбекистане

Схема у всех трёх провайдеров одна: компания заключает договор с провайдером, покупатель платит на странице провайдера или в его приложении, а деньги поступают на расчётный счёт компании. Данные карты покупатель вводит на стороне провайдера, поэтому задача вашего сайта — не хранить карты, а надёжно связать каждый платёж с конкретным заказом.

Какие карты принимаются, каждый провайдер указывает в своей документации:

• Payme Business — карты UZCARD Online и HUMO любых банков, а также Payme CARD.
• Click — в документации к платёжной кнопке указаны карты Uzcard и Humo.
• Uzum Checkout — Visa, Mastercard, Uzcard и Humo.

Если вам нужны Visa и Mastercard, уточните условия у провайдеров заранее.

Что подготовить до начала интеграции

Большая часть задержек в таких проектах связана не с кодом, а с документами и доступами. Пройдите этот список до того, как ставить задачу разработчику:

• Юрлицо или ИП. Click требует, чтобы поставщик был юридическим лицом или индивидуальным предпринимателем, а Payme Business — чтобы платежи поступали на расчётный счёт организации.
• Расчётный счёт в банке, на который будут зачисляться деньги.
• Договор с провайдером. С Click — договор на приём платежей с одним из подключённых к системе банков. С Payme Business — онлайн через Didox с электронной цифровой подписью или при личной встрече. С Uzum — через Uzum Bank: для работы с API банк выдаёт ключ и идентификатор терминала.
• Пакет документов провайдера. Например, в списке Click — свидетельство о регистрации, лицензия (если деятельность лицензируется), документ о назначении директора, устав и договор на домен. Требования могут меняться, поэтому запросите актуальный список заранее.
• Работающий сайт с публичной офертой, условиями доставки и возврата и контактами компании.
• ИКПУ, код упаковки и ставка НДС для каждого товара или услуги, согласованные с бухгалтером. Без них фискальные чеки не настроить.
• Доступы на компанию. Кабинет мерчанта, ключи, ЭЦП и почта для уведомлений оформляются на компанию, а не на разработчика.

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

Как подключить Payme, Click и Uzum к сайту: схема интеграции

Протоколы разные, но логика оплаты одна:

1. Заказ создан. Ваша система сохраняет заказ со статусом «ожидает оплаты» и фиксирует сумму.
2. Покупатель переходит на страницу провайдера. У Click это платёжная ссылка с идентификаторами мерчанта и сервиса, номером заказа, суммой и адресом возврата на сайт. У Payme — форма оплаты на checkout.paycom.uz с ID мерчанта, номером заказа и суммой в тийинах. У Uzum ваш сервер сначала регистрирует платёж через API и получает в ответ ссылку на платёжную страницу.
3. Провайдер сообщает о платеже. Payme по протоколу Merchant API сам обращается к вашему серверу запросами JSON-RPC 2.0 по HTTPS: CheckPerformTransaction (можно ли провести платёж), CreateTransaction, PerformTransaction, при необходимости CancelTransaction, а для проверки и сверки — CheckTransaction и GetStatement. Click в рамках SHOP API отправляет два POST-запроса — Prepare и Complete, каждый с подписью MD5, собранной с вашим секретным ключом. Uzum Checkout устроен наоборот: вы вызываете его REST API, а он присылает колбэк с результатом; статус можно в любой момент запросить методом getOrderStatus.
4. Сервер проверяет уведомление. У Click — подпись, у Payme — заголовок авторизации, колбэк Uzum стоит сверить со статусом из API. Затем сервер проверяет, существует ли заказ, актуален ли он и совпадает ли сумма.
5. Заказ получает статус «оплачен», и запускается выполнение: сборка заказа, подтверждение брони, открытие доступа к услуге.
6. Покупатель возвращается на сайт и видит статус, который сервер к этому моменту уже знает.

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

Второе: повторные уведомления — норма. Uzum, например, по текущей документации повторяет колбэк до пяти раз, если не получил от вашего сервера ответ 200 OK. Обработка должна быть идемпотентной: повторное уведомление о том же платеже получает тот же ответ и не создаёт второй оплаты, второго списания со склада или второго чека.

Статусы заказа, таймауты и возвраты

Пока платёж не завершён, заказ нужно зарезервировать и закрыть для изменений. По текущей документации Payme отменяет неоплаченную транзакцию через 12 часов после создания и просит мерчанта держать заказ в резерве до оплаты или таймаута, не давая покупателю его менять. Click в документации требует от интернет-магазинов резервировать товар на этапе Prepare. Если в корзину можно добавить позицию после начала оплаты, сумма заказа и сумма платежа разойдутся.

Сопоставьте состояния провайдера с состояниями заказа заранее:

• Ожидает оплаты — транзакция создана в Payme, Click прислал Prepare, платёж в Uzum зарегистрирован.
• Оплачен — PerformTransaction у Payme, успешный Complete у Click, статус COMPLETED у Uzum.
• Отменён — таймаут, отмена до оплаты или отказ банка.
• Возвращён полностью или частично — после отмены проведённой транзакции или возврата.

Возвраты у провайдеров устроены по-разному:

• Payme. CancelTransaction отменяет и созданные, и проведённые транзакции. Вернуть деньги покупателю можно из кабинета мерчанта — и только если этот метод реализован на вашей стороне.
• Click. Платёж отменяется целиком через Merchant API. По текущей документации отмена возможна для успешного платежа онлайн-картой в текущем отчётном месяце (платёж прошлого месяца — только в первый день текущего), а UZCARD может её отклонить.
• Uzum Checkout. Поддерживает полный и частичный возврат через API; при включённой автофискализации в запросе передаются возвращаемые позиции.

Если после оплаты выясняется, что заказ выполнить нельзя, возвращайте деньги через провайдера, а не переводом с карты сотрудника. У Click порядок для этого случая описан прямо: ответить на Complete успешно, а затем отменить платёж через Merchant API. Кроме того, ежедневно сверяйте оплаченные заказы с данными провайдера. У Payme для сверки предусмотрен метод GetStatement, но вызывает его сам Payme: ваш сервер возвращает через него список своих транзакций за период, и документация требует его реализовать.

Фискализация чеков в Payme, Click и Uzum: коды ИКПУ

С 1 января 2022 года чеки онлайн-ККМ и виртуальных касс не должны выдаваться без ИКПУ. Это 17-значный код товара или услуги из национального каталога tasnif.soliq.uz; там же указаны коды упаковки. Каждый провайдер позволяет передать данные позиций для чека:

• Payme. В ответе на CheckPerformTransaction мерчант может вернуть объект detail: для каждой позиции название, цена в тийинах, количество, код ИКПУ, код упаковки и ставка НДС. После оплаты или отмены Payme вызывает SetFiscalData и передаёт данные чека от оператора фискальных данных, включая ссылку на QR-код. Сохраните её вместе с заказом.
• Click. API фискализации принимает позиции платежа: название, ИКПУ, код упаковки, стоимость, количество, сумму и ставку НДС, а также данные комиссионного чека с ИНН или ПИНФЛ. Если вы пробили чек сами, можно передать ссылку на его QR-код.
• Uzum Checkout. Для одностадийных платежей есть автофискализация. По умолчанию она выключена и включается через менеджера Uzum Bank; при регистрации платежа передаётся корзина с ИКПУ, кодом упаковки и ставкой НДС. Без автофискализации данные в сервис фискализации нужно передавать самостоятельно, например через отдельный API Uzum.

Чек может формировать провайдер, а может ваша собственная виртуальная касса, через которую интернет-магазин передаёт данные оператору фискальных данных. Какой вариант выбрать, в том числе для чеков на возврат, решите вместе с бухгалтером. Налоговые органы разъясняли, что оплата через Click или Payme не освобождает от обязанности выдать чек, а деньги должны поступать на расчётный счёт, а не на личную карту. Даже если чек формирует провайдер, это не снимает с компании всех фискальных обязанностей, поэтому актуальные правила уточняйте у бухгалтера.

Сравнение Payme, Click и Uzum: один провайдер или несколько

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

Тестирование перед запуском

У Payme есть песочница test.paycom.uz: для неё выдаётся отдельный TEST_KEY, а для боевой работы используется ключ из кабинета. У Uzum Checkout есть тестовая среда и тестовые карты. В документации Click есть тестовая площадка, которая отправляет на ваш сервер запросы Prepare и Complete, и генератор Postman-коллекции со сценариями проверки SHOP API. Они проверяют ваш обработчик, но не весь путь оплаты, поэтому сквозной сценарий стоит подтвердить небольшим контролируемым боевым платежом с последующей отменой.

Прогоните как минимум эти сценарии:

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

Частые ошибки

• Доверие странице успеха. Заказ помечается оплаченным по редиректу, а не по уведомлению провайдера.
• Подпись и авторизация не проверяются. Любой, кто знает адрес обработчика, может «оплатить» заказ.
• Секретный ключ в коде сайта или мобильного приложения. Ключи хранят, а подписи проверяют только на сервере.
• Путаница с единицами суммы. Payme и Uzum Checkout работают с суммами в тийинах, SHOP API Click — в сумах, а API фискализации Click принимает тийины.
• Товар не резервируется, а заказ можно изменить после начала оплаты.
• ИКПУ нет или он указан неверно, и чек не проходит фискализацию или оформляется с ошибкой.
• Кабинет мерчанта и ключи оформлены на фрилансера. Уходит он — уходят и доступы.
• Нет ежедневной сверки, и расхождения находят только в конце месяца.
• Платежи не доходят до бухгалтерии и 1С. Сайт знает об оплате, а учёт — нет. Как это связать, мы разбирали в статье об интеграции 1С с сайтом и CRM.

Чем может помочь BITS Technology

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

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