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.