Payroc Payments для OpenCart — оплата картой на странице Payroc

Payroc Payments для OpenCart 4.x, 3.x и 2.3 принимает оплату картой через страницу оплаты Payroc (Hosted Payment Page). Покупатель выбирает «Pay by card» на чекауте, вводит карту на странице Payroc и возвращается в магазин; заказ становится оплаченным только тогда, когда подпись ответа совпала, а сумма, валюта и номер заказа соответствуют корзине. Поддерживаются терминалы в USD и CAD.

Что нужно от Payroc. Мерчант-аккаунт Payroc с терминалом в USD или CAD. Из Self-Care Portal берутся ID терминала и секрет терминала, ключ API — из Payroc Developer Portal. Условия, лимиты и комиссии устанавливает Payroc в договоре с вами.

Что видит покупатель

На чекауте он выбирает «Pay by card» и нажимает кнопку. Магазин открывает страницу оплаты Payroc, где покупатель вводит данные карты: они никогда не попадают в ваш магазин. После оплаты Payroc возвращает его в магазин, и он видит страницу «заказ принят». Если банк отказал, покупатель видит причину и возвращается на чекаут с той же корзиной, чтобы попробовать другую карту. Если покупатель закрыл вкладку до возврата, заказ всё равно подтвердится: Payroc сообщает магазину в фоне.

Что получает админ

Extensions → Extensions → Payments → Payroc Payments (CatCode): вкладки «Connection», «Checkout», «Order statuses» и «Pro». На «Connection» выбираете тестовую или боевую среду, вписываете ID терминала, секрет терминала, ключ API и валюту терминала (USD или CAD). Секрет и ключ API хранятся зашифрованными и больше не показываются. Кнопка «Check connection» спрашивает Payroc, знает ли он терминал и активен ли тот. Здесь же модуль показывает два адреса для Payroc Self-Care Portal: Receipt Page URL, куда Payroc возвращает покупателя, и Validation URL, куда Payroc отправляет подтверждение в фоне. Клик по адресу копирует его.

Вкладка «Checkout» задаёт название и описание метода для каждого языка, минимальную сумму заказа, геозону и порядок сортировки, а «Order statuses» — статусы для оплаченного, отклонённого и возвращённого заказа. Заказ остаётся без статуса, пока платёж не подтверждён, поэтому пустые попытки не засоряют список заказов. Для каждой попытки оплаты создаётся новый номер в Payroc, и повторная попытка после отказа не путается с предыдущей.

Ответ Payroc принимается только после сверки подписи секретом терминала. Одобренная оплата ставит статус «оплачен»; если сумма, валюта или состав корзины изменились, либо одобрена лишь часть суммы, заказ получает статус «на рассмотрение» с примечанием. Повторные и запоздавшие ответы ничего не меняют, а вторая одобренная оплата того же заказа оставляет примечание о двойной оплате. На вкладке заказа видны платёж, карта (маскированная), номер платежа в Payroc и попытки; здесь же делаются возвраты средств, полные или частичные, с причиной, и кнопка «Check payment status».

Pro: авторизация со списанием позже. Сумма блокируется на карте через страницу предварительной авторизации Payroc, заказ получает статус «удержано», а кнопки «Capture» и «Release» в заказе списывают деньги или снимают блокировку (частично — через поле суммы). Ежечасная проверка списывает удержанное для заказов, дошедших до выбранного статуса, и снимает блокировку с отменённых.

Ссылки на оплату (Pro) для любого неоплаченного заказа, например принятого по телефону: одноразовая, с заданной суммой и сроком от 1 до 60 дней; Payroc отправляет её покупателю письмом с вашим сообщением, а оплаченный или отменённый заказ отключает ссылку сам. Ежечасная фоновая проверка подхватывает платежи, по которым Payroc не прислал ответа. Журнал платежей и отчёт показывают платежи терминала за период и сверяют их с заказами (совпадает, сумма другая, одобрено, но не оплачено, заказа нет в магазине) с выгрузкой в CSV. Журнал запросов к Payroc хранится 30 дней. До трёх дополнительных терминалов для других валют, каждый со своим секретом.

Как это работает, шаг за шагом

1. Устанавливаете архив для своей версии OpenCart и включаете модуль.
2. В Payroc Self-Care Portal берёте ID терминала и секрет терминала, в Developer Portal создаёте ключ API.
3. В настройках модуля вписываете их, выбираете валюту терминала и нажимаете «Check connection».
4. Копируете Receipt Page URL и Validation URL из настроек в портал Payroc (терминал → Settings) и включаете Validation.
5. Покупатель выбирает «Pay by card», вводит карту на странице Payroc и возвращается в магазин.
6. Модуль сверяет подпись и сумму и переводит заказ в оплаченный; возврат средств делаете с вкладки заказа.

Что под капотом

• Payroc Hosted Payment Page: запрос подписывается SHA-512, ответ принимается по подписи, сумме, валюте и номеру заказа, который выдал магазин.
• Страница возврата не зависит от сессии покупателя: в OpenCart 4 она статическая и сама переводит покупателя на страницу результата магазина, так что корзина и вход в аккаунт не теряются.
• Фоновое подтверждение Payroc (Validation URL) обрабатывается вместе с возвратом покупателя: заказ проводится один раз даже при одновременных ответах.
• Возвраты идут с ключом идемпотентности, ошибки Payroc (RFC 7807) показываются словами.
• Секрет терминала и ключ API хранятся зашифрованными; модуль не меняет ядро и работает через события OpenCart; обновление сохраняет настройки.
• Не входят: сохранённые карты, встроенные поля Hosted Fields (оплата идёт на странице Payroc), массовые действия в списке заказов; OpenCart 4.0.0–4.0.1 не поддерживается.
• Интерфейс на английском (en-gb).

Как установить

1. Extensions → Installer: загрузите архив для своей версии, не переименовывая (OpenCart 4: cc_payroc.ocmod.zip, 3.x: cc_payroc-oc3.ocmod.zip, 2.3: cc_payroc-oc2.ocmod.zip).
2. Для 3.x и 2.3: Extensions → Modifications → Refresh.
3. Extensions → Payments → Payroc Payments (CatCode): установите и откройте настройки.
4. Впишите ID терминала, секрет, ключ API, выберите валюту и нажмите «Check connection».
5. Добавьте Receipt Page URL и Validation URL в Payroc Self-Care Portal.
6. Для Pro: вставьте ключ или запустите триал на вкладке Pro.