/
Узбекистан ◾️ YUZ PAY

Публичное пространство

Узбекистан ◾️ YUZ PAY

https://crystals.atlassian.net/browse/SRTG-527

https://crystals.atlassian.net/browse/CR-14943

10.4.26.0

Описание

Плагин оплаты YUZ PAY предназначен для приема оплаты чека продажи через сервис биометрической оплаты YUZ PAY в SetRetail10. Функциональность реализована для касс POS, SetTouch и SCO и позволяет покупателю оплатить покупку с использованием биометрической идентификации на терминале YuzPay Validator App.

YUZ PAY является платежной организацией. Биометрия в данном сценарии используется как способ аутентификации покупателя при выполнении безналичной оплаты. После успешной идентификации клиента банк подтверждает оплату, касса добавляет оплату в чек и регистрирует чек по стандартной логике SetRetail10.

Плагин выполняет следующие операции:

  • создание ордера оплаты в контуре YUZ PAY;

  • передачу суммы чека, состава товаров и идентификатора терминала;

  • цикличный опрос статуса платежа;

  • добавление оплаты в чек при успешном статусе;

  • отмену неоплаченного ордера до добавления оплаты в чек;

  • обработку ошибок связи и отказов процессинга.

Оплата доступна через тип оплаты YUZ PAY. Название кнопки в конфигурации кассы также указывается как YUZ PAY.

Ценность

Оплата через YUZ PAY расширяет набор безналичных способов оплаты на кассе и позволяет ритейлеру использовать актуальный для рынка Узбекистана сценарий оплаты по биометрии.

Функциональность дает следующие преимущества:

  • ускоряет обслуживание покупателей за счет оплаты без наличных и без предъявления банковской карты;

  • позволяет использовать биометрическую идентификацию покупателя как способ подтверждения платежа;

  • поддерживает оплату на POS, SetTouch и SCO;

  • поддерживает частичную оплату на POS и SetTouch в рамках смешанной оплаты;

  • позволяет принимать оплату через внешний банковский контур YUZ PAY;

  • сохраняет возможность закрыть остаток чека другим типом оплаты при частичной оплате;

  • дает ритейлеру дополнительный платежный инструмент для покупателей, использующих сервис YUZ PAY.

Примеры работы

Общий алгоритм оплаты

При выборе типа оплаты YUZ PAY касса выполняет общий алгоритм:

  1. Кассир или покупатель выбирает тип оплаты YUZ PAY.

  2. Касса проверяет настройки процессинга и наличие идентификатора терминала terminalId.

  3. Касса отправляет запрос создания ордера POST /api/v1/merchant/order/create.

  4. YUZ PAY возвращает внутренний идентификатор ордера orderId.

  5. Касса переходит в режим ожидания оплаты на терминале.

  6. Покупатель выбирает оплату по биометрии на терминале YuzPay Validator App.

  7. Покупатель проходит биометрическую идентификацию.

  8. Касса циклично запрашивает статус ордера через POST /api/v1/merchant/order/status.

  9. При статусе SUCCESS касса добавляет оплату в чек.

  10. Если чек оплачен полностью, касса регистрирует чек.

  11. Если чек оплачен частично, кассир выбирает другой тип оплаты для оплаты остатка.

Оплата YUZ PAY на POS или SetTouch

  1. Добавьте товары в чек.

  2. Перейдите к оплате.

  3. Выберите тип оплаты YUZ PAY.

  4. Если требуется частичная оплата, измените сумму к оплате.

  5. Нажмите кнопку Оплатить.

  6. Дождитесь проверки настроек плагина и создания ордера в YUZ PAY.

  7. Попросите покупателя выбрать оплату по биометрии на терминале YuzPay Validator App.

  8. Попросите покупателя поднести лицо к камере терминала.

  9. Дождитесь завершения биометрической идентификации и подтверждения платежа банком.

  10. Дождитесь добавления оплаты YUZ PAY в чек.

  11. Если чек оплачен полностью, зарегистрируйте чек.

  12. Если чек оплачен частично, выберите другой доступный тип оплаты и оплатите остаток суммы.

Оплата YUZ PAY на SCO

  1. Добавьте товары в чек на кассе самообслуживания.

  2. Перейдите к выбору способа оплаты.

  3. Выберите тип оплаты YUZ PAY.

  4. Дождитесь создания ордера оплаты в YUZ PAY.

  5. Выберите оплату по биометрии на терминале YuzPay Validator App.

  6. Поднесите лицо к камере терминала.

  7. Дождитесь успешной идентификации и подтверждения платежа.

  8. Дождитесь регистрации чека.

На SCO оплата выполняется на полную сумму чека. Редактирование суммы оплаты недоступно.

Смешанная оплата на POS и SetTouch

На POS и SetTouch покупатель может оплатить через YUZ PAY часть суммы чека, если сценарий смешанной оплаты разрешен настройками кассы и процессинга.

  1. Добавьте товары в чек.

  2. Перейдите к оплате.

  3. Выберите тип оплаты YUZ PAY.

  4. Укажите сумму частичной оплаты.

  5. Нажмите кнопку Оплатить.

  6. Проведите оплату через YUZ PAY.

  7. Дождитесь добавления оплаты в чек.

  8. Выберите другой тип оплаты для оплаты остатка суммы.

  9. Зарегистрируйте чек после полной оплаты.

Статусы оплаты

Касса обрабатывает статусы, полученные через метод POST /api/v1/merchant/order/status.

Статус

Тип статуса

Описание

Действие кассы

Статус

Тип статуса

Описание

Действие кассы

CREATED

Промежуточный

Ордер создан, ожидаются действия клиента или терминала.

Касса продолжает опрос статуса.

TERMINAL_RECEIVED

Промежуточный

Терминал получил заказ или запрос на оплату.

Касса продолжает опрос статуса.

IDENT

Промежуточный

Выполняется идентификация клиента или терминала.

Касса продолжает опрос статуса.

PENDING

Промежуточный

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

Касса продолжает опрос статуса.

SUCCESS

Успешный конечный

Банк успешно идентифицировал клиента, авторизовал платеж и подтвердил успех.

Касса добавляет оплату в чек.

ERROR

Ошибочный конечный

Платеж не выполнен: отказ банка, ошибка идентификации или другая ошибка.

Касса показывает ошибку и возвращает пользователя к списку оплат.

CANCEL

Ошибочный конечный

Ордер отменен.

Касса не добавляет оплату и возвращает пользователя к списку оплат.

EXPIRED

Ошибочный конечный

Время, отведенное на биометрическую оплату, истекло.

Касса не добавляет оплату и возвращает пользователя к списку оплат.

Примеры сценариев возврата

Возврат через плагин YUZ PAY не поддерживается. Если требуется вернуть денежные средства по чеку, оплаченному через YUZ PAY, используйте дополнительные способы возврата, согласованные с ритейлером, банком и финансовой службой.

Полный возврат чека, оплаченного через YUZ PAY

  1. Найдите исходный чек продажи.

  2. Оформите возврат товаров по стандартному сценарию SetRetail10.

  3. Убедитесь, что для типа оплаты YUZ PAY включена настройка возврата дополнительными способами вместо плагина.

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

  5. Зарегистрируйте чек возврата.

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

Отмена частично оплаченной покупки

Если покупатель частично оплатил чек через YUZ PAY, а затем отказался от покупки, отмена уже выполненной оплаты через плагин недоступна.

  1. Дождитесь сообщения кассы о невозможности отмены выполненной оплаты.

  2. Если у покупателя списаны денежные средства, передайте запрос в бухгалтерию или финансовую службу.

  3. Выполните дальнейшую обработку ситуации по регламенту ритейлера и банка.

Рекомендуемый текст сообщения: Отмена не выполнена. Если у покупателя списаны денежные средства, подайте запрос в бухгалтерию.

Примеры отрицательных сценариев

Не настроен идентификатор терминала

Если для кассы не задан terminalId, плагин не может создать ордер оплаты.

  1. Выберите тип оплаты YUZ PAY.

  2. Дождитесь проверки настроек плагина.

  3. Если terminalId не настроен, закройте сообщение Ошибка связи с банком.

  4. Вернитесь к списку оплат.

  5. Настройте идентификатор терминала и повторите оплату.

Нет связи с сервером или процессингом

Если касса не может обратиться к серверу или банковскому контуру YUZ PAY, оплата не начинается.

  1. Выберите тип оплаты YUZ PAY.

  2. Дождитесь отправки запроса создания ордера.

  3. Если истек таймаут соединения или ожидания ответа, закройте сообщение Ошибка связи с банком.

  4. Выберите другой тип оплаты или повторите оплату позже.

Ошибка при создании ордера

Если на запрос POST /api/v1/merchant/order/create касса получает ошибку или не получает ответ, касса показывает сообщение Ошибка связи с банком и возвращается к списку оплат.

Оплата отклонена процессингом

Если при опросе статуса YUZ PAY возвращает ERROR, CANCEL, EXPIRED или другую терминальную ошибку, касса не добавляет оплату в чек.

  1. Дождитесь сообщения Оплата отклонена процессингом. Повторите или выберите другой тип оплаты.

  2. Закройте сообщение.

  3. Выберите другой тип оплаты или повторите оплату YUZ PAY.

Обрыв связи при опросе статуса

Если после успешного создания ордера касса не получает ответ на запрос статуса, она повторяет запросы по настройкам таймаутов и количества попыток.

  1. Дождитесь завершения установленного количества попыток.

  2. Если ответ не получен, выберите действие в диалоговом окне Оплата не завершена, нет связи с процессингом. Прервать оплату или ждать завершения?.

  3. Нажмите Ждать, чтобы запустить новый цикл запросов статуса.

  4. Нажмите Прервать, чтобы перейти к проверке статуса и отмене неоплаченного ордера.

Отмена неоплаченного ордера при выходе из оплаты

Отмену можно выполнить до добавления оплаты в чек, если ордер находится в статусе CREATED или PENDING.

  1. Нажмите кнопку Отмена на экране ожидания оплаты.

  2. Дождитесь однократного запроса статуса через POST /api/v1/merchant/order/status.

  3. Если получен статус SUCCESS, дождитесь добавления оплаты в чек.

  4. Если получен статус ERROR, CANCEL или EXPIRED, вернитесь к списку оплат без дополнительной отмены.

  5. Если получен статус CREATED или PENDING, дождитесь отправки запроса отмены POST /api/v1/merchant/order/cancel.

  6. Если отмена прошла успешно, вернитесь к списку оплат.

  7. Если отмена завершилась ошибкой или ответ не получен после повторов, закройте сообщение Операция прервана и вернитесь к списку оплат.

Коды ошибок YUZ PAY

Error Type

HTTP Status

WebSocket Event

Описание

Error Type

HTTP Status

WebSocket Event

Описание

Authentication Failed

401

Connection Closed

Некорректные учетные данные.

Invalid API Key

403

Connection Refused

Некорректный API Key.

Order Not Found

404

-

Не найден ордер с указанным идентификатором.

Duplicate Order

409

-

Ордер с таким `externalId` уже существует.

Rate Limit

429

-

Превышено допустимое количество запросов.

Internal Error

500

ERROR status

Внутренняя ошибка сервиса.

Service Unavailable

503

Connection Lost

Сервис временно недоступен.

Ограничения

  • Функциональность доступна начиная с версии 10.4.26.0.

  • Поддерживаются кассы POS, SetTouch и SCO.

  • На SCO оплата выполняется только на полную сумму чека.

  • Возврат через тип оплаты YUZ PAY не поддерживается.

  • Частичный возврат при отмене частично оплаченного чека не поддерживается.

  • Отмена неоплаченного ордера доступна только до добавления оплаты в чек.

  • Отмена неоплаченного ордера выполняется только для статусов CREATED и PENDING.

  • Работа с WebHook не поддерживается.

  • Для работы оплаты требуется настроенный terminalId, выданный YUZ PAY.

  • Для авторизации запросов требуются HTTP Basic Authentication и API Key.

  • Сообщения, полученные от банковского контура, отображаются на языке, на котором они получены от YUZ PAY.

  • Среднее время ответа на order/create по документации составляет до 2 секунд.

  • Для обмена с YUZ PAY используется HTTPS/WSS-подключение.

Настройки

Настройка процессинга на сервере

  1. На сервере SetCentrum или SetRetail10 откройте раздел Интеграция → Внешние процессинги.

  2. Добавьте процессинг оплаты YUZ PAY.

  3. Откройте настройки процессинга YUZ PAY.

  4. Заполните параметры подключения, полученные от YUZ PAY или банка.

  5. Сохраните настройки.

  6. Перейдите в Кассовый модуль → Шаблоны касс.

  7. Откройте требуемый шаблон кассы.

  8. Перейдите на вкладку ПРОЦЕСС ТОРГОВЛИ → НАСТРОЙКИ.

  9. В секции Типы оплат разрешите тип оплаты YUZ PAY.

  10. Сохраните шаблон кассы.

  11. Перезагрузите кассовый модуль или дождитесь применения конфигурации по стандартному регламенту обновления касс.

Параметры процессинга

Параметр

Обязательный

Описание

Пример или значение по умолчанию

Параметр

Обязательный

Описание

Пример или значение по умолчанию

Адрес подключения

Да

URL API YUZ PAY.

https://apimerchant-dev.yuzpay.uz для тестового контура.

username

Да

Имя пользователя, предоставляется банком.

TSN0000100 для тестирования.

password

Да

Пароль, предоставляется банком.

TBT12345 для тестирования.

API Key

Да

Ключ API. Передается в заголовке X-External-API-Key.

ece4da17-2ab9-4969-81df-93df74c41262 для тестирования.

Таймаут соединения, секунды

Нет

Время ожидания установки соединения с процессингом.

3

Таймаут ожидания ответа, секунды

Нет

Время ожидания ответа от процессинга.

10

Количество попыток для запроса

Нет

Количество повторных запросов при ожидании ответа или статуса.

5

Настройка идентификатора терминала YuzPay

На каждой кассе задайте идентификатор терминала YuzPay terminalId. Значение выдает YUZ PAY. Терминал должен быть предварительно заведен сервисным инженером.

Сохраните значение в таблице `sales_management_properties`:

Поле

Значение

Поле

Значение

property_key

terminal_id

property_value

UUID терминала YuzPay

Пример значения terminalId`: `0033a6bd-66a7-40ca-8e43-f9ddade091bf.

Перед включением оплаты на кассе проверьте, что `terminalId` соответствует реальному терминалу YuzPay, закрепленному за рабочим местом кассира или кассой самообслуживания.

Авторизация запросов

Для авторизации запросов плагина в YUZ PAY используется комбинация:

  1. HTTP Basic Authentication.

  2. API Key в заголовке X-External-API-Key.

Авторизационные параметры задайте в настройках процессинга.

Параметр

Описание

Параметр

Описание

Authorization

Basic <base64(username:password)>

X-External-API-Key

API Key, выданный YUZ PAY.

Content-Type

application/json

Описание запросов

Создание ордера оплаты

Метод: POST /api/v1/merchant/order/create.

В запросе касса передает сумму оплаты, список товаров, идентификатор терминала и уникальный идентификатор ордера на стороне кассы.

{ "amount": 100000, "goods": [ { "name": "Мишени для контроля работы системы наведения", "mxikCode": "04911001032000000", "packageCode": "1342828" } ], "terminalId": "0033a6bd-66a7-40ca-8e43-f9ddade091bf", "externalId": "a2b9ada3-0f8b-4e8d-a74a-bd047aeb79b7" }

Поле

Тип

Обязательное

Описание

Чем заполнять в SetRetail10

Поле

Тип

Обязательное

Описание

Чем заполнять в SetRetail10