Инструкция к модулю Интернет-эквайринг OneVision V2

Что делает модуль

Модуль добавляет в CS-Cart платежный процессор OneVision V2. Он создает платеж в OneVision по данным заказа, перенаправляет покупателя на платежную страницу, принимает результат оплаты и обновляет платежную информацию заказа.

Модуль поддерживает тестовый и рабочий режимы, разные методы оплаты OneVision, сопоставление статусов платежей со статусами заказов и операции с уже созданным платежом: списание захолдированной суммы, отмена холда и возврат.

Где находится модуль

Основные параметры платежа настраиваются в способе оплаты CS-Cart с процессором One Vision V2: Администрирование → Способы оплаты, затем откройте нужный способ оплаты и выберите процессор OneVision V2.

Сопоставление статусов находится в настройках модуля: Модули → Управление модулями → Интернет-эквайринг OneVision V2 → Статусы. В мультивитринной установке сначала выберите витрину, иначе поля сопоставления могут быть недоступны.

Настройка способа оплаты

В способе оплаты заполните общие параметры:

Режим работы — выберите тестовый или рабочий режим. От режима зависит, какие API-ключ и пароль магазина будут использоваться при запросах к OneVision.

API хост — адрес API OneVision. По умолчанию используется https://api.onevisionpay.com. Если ввести адрес без протокола, модуль добавит https://.

ID мерчанта — merchant_id, полученный в OneVision. Он передается в позициях заказа и доставки.

ID сервиса — service_id категории или сервиса в платежной системе OneVision.

Наименование мерчанта — название мерчанта, которому принадлежит товар или услуга.

Валюта — валюта платежа: KZT, RUR, EUR или USD.

Время жизни платежа — срок доступности платежа на стороне OneVision. В интерфейсе доступны варианты от 15 минут до 7 дней; в текущей платежной логике запрос отправляется со значением 3600 секунд.

Методы оплаты — выберите сценарий OneVision: эквайринг, мобильная коммерция, электронные кошельки, переводы между картой и мобильным балансом, Google Pay или Apple Pay.

API-ключи и пароль магазина

В блоках Настройки тестового режима и Настройки рабочего режима укажите:

API-ключ — ключ доступа к API OneVision для выбранного режима.

Пароль магазина — secret key, которым подписывается запрос. Модуль формирует подпись HMAC-SHA512 от base64-кодированного JSON-запроса.

Для тестовой оплаты выберите тестовый режим и заполните тестовые credentials. Для реальных оплат выберите рабочий режим и заполните рабочие credentials.

Webhook и callback

Модуль передает в OneVision callback URL вида payment_notification.callback?payment=ms_one_vision_v2&order_id=<ID заказа>. Также используются URL успешного и неуспешного возврата покупателя: payment_notification.success и payment_notification.fail.

После callback или возврата покупателя модуль запрашивает актуальный статус платежа через метод payment/status, разбирает ответ OneVision и сохраняет данные в платежной информации заказа.

Статусы заказов

На вкладке Статусы настройте соответствие статусов OneVision статусам заказа в CS-Cart. В модуле есть два базовых статуса результата платежа:

Успех — платеж проведен успешно; по умолчанию соответствует статусу заказа O.

Отклонен — платеж отклонен; по умолчанию соответствует статусу заказа F.

Если для статуса OneVision выбрано соответствие, модуль использует его. Если соответствие не задано, используется стандартное значение из схемы модуля.

Операции capture, cancel и refund

В блоке Статусы для действий с платежом можно выбрать статусы заказа, при переходе в которые модуль отправит действие в OneVision:

Запрос на клиринг — отправляет payment/capture, когда платеж находится в hold и заказ переведен в выбранный статус.

Отмена платежа — отправляет payment/cancel для отмены платежа, если деньги еще не списаны, а заблокированы.

Возврат платежа — отправляет payment/refund для возврата уже списанного платежа.

Для этих операций модуль берет ID платежа и сумму из платежной информации заказа. После успешного ответа OneVision платежная информация заказа обновляется.

Чеки и 54-ФЗ

Модуль передает в OneVision состав заказа и доставку как позиции платежа, но в коде модуля нет отдельной настройки фискализации, признаков 54-ФЗ или интеграции с DigitalKassa. Если для магазина обязательна отправка фискальных чеков, проверьте, как это настраивается на стороне OneVision или отдельного кассового решения.

Логирование

Модуль пишет технический лог callback-обмена и ответов платежной системы в каталог var/ms_data/logs/ms_one_vision_v2/<company_id>/ внутри установки CS-Cart. Основные файлы — payment_1.log и payment_2.log; модуль переключается между ними при достижении лимита размера.

Как проверить работу

1. Создайте способ оплаты с процессором OneVision V2 и выберите тестовый режим.

2. Укажите тестовый API-ключ, пароль магазина, API-хост, merchant_id, service_id, наименование мерчанта, валюту и метод оплаты.

3. Оформите тестовый заказ на витрине и выберите этот способ оплаты.

4. Убедитесь, что покупатель перенаправляется на платежную страницу OneVision.

5. Завершите тестовый платеж или смоделируйте отказ и проверьте, что заказ получил ожидаемый статус.

6. Откройте заказ в админке и проверьте платежную информацию: статус платежа, сумму, ID платежа, данные карты или текст ошибки.

7. Если используются hold-операции, переведите заказ в статусы, настроенные для capture, cancel или refund, и проверьте ответ OneVision и обновление платежной информации.

8. При ошибках проверьте корректность credentials, доступность API-хоста, callback URL снаружи и технический лог модуля.