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-денний тріал.