Portmone для OpenCart — оплата картой, Apple Pay и Google Pay

CatCode Portmone — модуль оплаты через Portmone.com для OpenCart 2.3, 3.x и 4.x. Покупатель платит картой, Apple Pay или Google Pay на странице Portmone, а заказ в магазине сам переходит в оплаченный статус. Главное отличие от обычного «редирект и поверили на слово»: модуль не верит ни возврату покупателя, ни уведомлению — прежде чем отметить заказ оплаченным, он сам спрашивает у Portmone статус и сверяет сумму.

Как это выглядит для покупателя

В чекауте это обычный способ оплаты «Оплата картой, Apple Pay, Google Pay (Portmone)». Покупатель подтверждает заказ и жмёт «Перейти к оплате» — модуль создаёт счёт в Portmone и открывает страницу оплаты.

После оплаты Portmone возвращает покупателя в магазин. Модуль игнорирует то, что пришло в адресе или в POST, и запрашивает статус у Portmone логином и паролем магазина. Если оплата прошла — «Ваш заказ принят», если нет — заказ получает статус неудачной оплаты, товары возвращаются в корзину, а сверху появляется подсказка попробовать ещё раз.

Повторная попытка уходит в Portmone под новым номером, а предыдущий счёт модуль закрывает запросом closeInvoice, чтобы один заказ не оплатили дважды. Если покупатель уже оплатил и нажал «Назад», он попадает на страницу успеха, а не на вторую оплату.

Способ оплаты показывается только для валют, которые принимает Portmone: UAH, USD, EUR, GBP, PLN и KZT. Переключил покупатель магазин на другую валюту — Portmone прячется сам.

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

• «Проверить соединение» — модуль делает запрос статуса вашими данными, а если указан ключ подписи, ещё и создаёт тестовый счёт на 1 грн и сразу его закрывает. Ошибку в пароле или ключе вы увидите в админке, а не от покупателя.
• Шесть статусов заказа на отдельной вкладке: «ожидает оплаты», «оплачено», «средства заблокированы», «блокировка снята», «неудачная оплата» и «возврат».
• История заказа с номером счёта Portmone, маской карты, кодом авторизации и результатом каждой сверки. Недоплату видно сразу, и такой заказ в оплаченные не переходит.
• Время на оплату — сколько минут ссылка остаётся действительной, и гео-зона, если Portmone нужен не для всех стран.
• Журнал платежей (Pro) — все платежи одним списком: сумма заказа, оплачено, возвращено, состояние в Portmone рядом со статусом заказа, номер счёта и карта, кнопки «Сверить» и «Вернуть».

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

1. Покупатель в чекауте выбирает Portmone и подтверждает заказ. Модуль создаёт счёт в Portmone с уникальным номером попытки, суммой и валютой заказа. Если Portmone выдал вам ключ подписи, запрос подписывается HMAC-SHA256. Заказ получает статус «ожидает оплаты».
2. Покупатель платит на странице Portmone — картой, Apple Pay, Google Pay или другими способами, включёнными для вашего магазина.
3. Покупатель возвращается в магазин (Portmone делает это POST-запросом с другого домена). Модуль запрашивает статус у Portmone через result и только по этому ответу решает, что случилось с деньгами.
4. Сверка суммы и принадлежности: номер должен быть выдан именно этому заказу, Payee ID — вашим, сумма — не меньше суммы заказа. Если оплачено меньше, заказ остаётся на проверке с заметкой для менеджера.
5. Заказ переходит в выбранный статус, а в историю попадают номер счёта, маска карты и код авторизации.
6. Если покупатель закрыл вкладку и не вернулся, сработает уведомление Portmone на адрес из настроек — JSON или XML. Уведомлению модуль тоже не верит на слово: статус перезапрашивается через API, а повторное уведомление не дублирует запись в истории.
7. Повторная попытка закрывает предыдущий счёт, так что два платежа за один заказ не пройдут.
8. В режиме двухстадийной оплаты (Pro) средства только блокируются на карте. Списываете их из журнала, когда заказ готов к отгрузке, или снимаете блокировку. Платёжные системы держат блокировку до 7 дней.

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

• Статус — только из API Portmone. Возврат покупателя, уведомление и кнопка «Сверить» ведут в одну точку: запрос result с логином и паролем магазина. Подделать оплату запросом на сайт не выйдет.
• Уникальные номера попыток: номер заказа плюс счётчик и случайный суффикс. Отклонённая старая попытка не тронет уже оплаченный заказ, а оплаченная старая попытка засчитается, даже если покупатель открыл новую.
• Сессия покупателя не теряется: Portmone возвращает покупателя POST-запросом с другого домена, и OpenCart на таком запросе открывал новую сессию — корзина и авторизация исчезали. Модуль на таком возврате не даёт перезаписать сессионную куку.
• OpenCart 4.1: если ядро аннулировало ещё не оформленный заказ, пока покупатель перезагружал чекаут, модуль пересобирает его из текущей корзины, а не отказывает в оплате.
• Тексты модуля не перетираются языковыми файлами других расширений, которые грузятся событиями на смену статуса заказа.
• Пароль и ключ подписи шифруются в базе (AES-256-CBC с проверкой целостности), в журнале запросов пароль маскируется.
• Свой код расширения cc_portmone: официальный модуль Portmone может стоять рядом — настройки и таблицы разные.
• Ядро OpenCart не патчится: в 4.x модуль ставится как обычное расширение, в 3.x и 2.3 — без ocmod-правок ядра. Таблица платежей при удалении модуля остаётся, чтобы возвраты и блокировки не потерялись.
• Pro-гейт без «кирпича»: когда триал закончился, останавливаются только Pro-функции, а списать или разблокировать уже заблокированные средства можно и дальше.

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

1. OpenCart 4.x: Расширения → Установка расширений → загрузите cc_portmone.ocmod.zip и нажмите «Установить». Далее Расширения → Оплата → «Portmone — оплата картой, Apple Pay, Google Pay» → «Установить» → «Редактировать».
2. OpenCart 3.x: Расширения → Установка расширений → загрузите cc_portmone-oc3.ocmod.zip, обновите модификации, затем Расширения → Оплата → Portmone → «Установить».
3. OpenCart 2.3: штатный установщик 2.3 копирует файлы только по FTP, поэтому проще распаковать содержимое папки upload/ из архива cc_portmone-oc2.ocmod.zip в корень магазина. Затем Расширения → Оплата → Portmone → «Установить».
4. Впишите Payee ID, логин и пароль магазина (и ключ подписи, если Portmone его выдал), нажмите «Проверить соединение» и сохраните.
5. Отправьте менеджеру Portmone адрес для уведомлений — он показан в настройках модуля.
6. Для Pro: вставьте лицензионный ключ из письма после оплаты или запустите 7-дневный триал.