VibeFox DPO for OpenCart — Допомога

Вимоги

OpenCart: 3.0.x (перевірено на 3.0.5.0) або 4.0.2 і новіші (перевірено на 4.1.0.3).

PHP: 8.0 або новіша версія з розширенням SimpleXML.

Обліковий запис DPO Pay: вам потрібні Company Token і Service Type ID вашого торгового облікового запису DPO. DPO видає їх під час відкриття облікового запису; отримайте їх у свого менеджера DPO або на dpogroup.com. DPO також може надати тестовий обліковий запис із власним токеном і типом сервісу. Окремого тестового сервера немає: DPO використовує одну й ту саму адресу API для тестових і робочих облікових записів, а обліковий запис визначається за токеном.

Валюта: валюта замовлення має підтримуватися вашим обліковим записом DPO. DPO приймає не більше 2 десяткових знаків, тому суми замовлень із 3 десятковими знаками (наприклад, KWD 12.345) оплатити не можна.

Cron на сервері: завдання cron, яке кожні 15 хвилин викликає URL повторної перевірки розширення (див. Налаштування).

Ліцензійний ключ VibeFox: купується на vibefox.net. Один ключ працює на одному домені.

Встановлення

Завантаження — це один zip-файл із пакетами для обох версій OpenCart. Розпакуйте його на своєму комп'ютері. Він містить README.txt, пакет OpenCart 3 wcp_dpo_pay-oc3-(version).ocmod.zip і пакет OpenCart 4 wcp_dpo_pay.ocmod.zip. Встановлюйте лише пакет для вашої версії OpenCart. Ліцензійний ключ однаковий для обох версій.

OpenCart 3

1. В адмін-панелі перейдіть до Extensions > Installer, натисніть Upload і виберіть файл wcp_dpo_pay-oc3-(version).ocmod.zip. Розширення не має модифікацій OCMOD, тож оновлювати Extensions > Modifications не потрібно. Замість інсталятора ви можете скопіювати вміст папки upload цього пакета в кореневу папку вашого магазину.

2. Перейдіть до Extensions > Extensions і виберіть тип Payments. Знайдіть VibeFox DPO Pay Gateway і натисніть Install (зелена кнопка +). Вашому адміністратору потрібне право змінювати список платіжних розширень.

3. Натисніть Edit (кнопка з олівцем), щоб відкрити сторінку налаштувань. Вставте ваш ліцензійний ключ VibeFox у поле License key у блоці ліцензії у верхній частині сторінки та натисніть Activate (див. Ліцензійний ключ).

4. Введіть Company Token і Service Type для тестового та/або робочого режиму (див. Налаштування).

5. Надішліть до служби підтримки DPO URL push-сповіщень, показаний у розділі Payment notifications, і попросіть налаштувати його для вашого облікового запису. Додайте URL cron до завдань cron вашого сервера.

6. Увімкніть Enable/Disable і натисніть Save. Оформіть тестове замовлення в тестовому режимі, а потім вимкніть Test mode, щоб приймати реальні платежі.

OpenCart 4

1. В адмін-панелі перейдіть до Extensions > Installer, натисніть Upload і виберіть файл wcp_dpo_pay.ocmod.zip. Не перейменовуйте файл: OpenCart 4 бере код розширення з назви файлу, і перейменований пакет не працює.

2. Пакет з'являється у списку встановлених розширень на тій самій сторінці. Натисніть Install (зелена кнопка +) поруч із ним.

3. Перейдіть до Extensions > Extensions і виберіть тип Payments. Знайдіть VibeFox DPO Pay Gateway, натисніть Install (зелена кнопка +), а потім Edit (кнопка з олівцем).

4. Введіть ліцензійний ключ і облікові дані DPO, налаштуйте URL push-сповіщень і cron та протестуйте платіж так само, як у кроках 3–6 для OpenCart 3. Сторінка налаштувань і її поля однакові в обох версіях. Відрізняються лише URL push-сповіщень і URL cron (див. Сповіщення про платежі).

Нова інсталяція починає роботу з вимкненим способом оплати та увімкненим тестовим режимом. Під час встановлення розширення створює власну таблицю транзакцій і секретний токен URL cron.

Налаштування

Усі налаштування розміщені на сторінці розширення: Extensions > Extensions > Payments > VibeFox DPO Pay Gateway > Edit. Розділи перелічено ліворуч; кнопка Save під списком зберігає всю сторінку. Якщо спосіб оплати увімкнено, але Company Token або Service Type обраного режиму порожні, сторінка попереджає, що спосіб оплати приховано на оформленні замовлення, а при збереженні показується те саме попередження. Поки увімкнено тестовий режим, сторінка показує Тестовий режим увімкнено: платежі створюються з обліковими даними тестового облікового запису. Без права змінювати розширення сторінка показує налаштування, але не може їх зберегти.

При збереженні Title не може бути порожнім (не більше 128 символів), Sort Order має бути цілим числом, а Total — числом 0 або більше; інакше нічого не зберігається.

DPO Pay

Enable/Disable: Enable DPO Pay вмикає або вимикає спосіб оплати. За замовчуванням: вимкнено.

Title: назва способу оплати, яку бачить покупець на оформленні замовлення. Вона також зберігається в замовленні як назва способу оплати. За замовчуванням: DPO Pay. Обов'язкове поле.

Description: текст, який покупець бачить на кроці Confirm Order над кнопкою підтвердження. За замовчуванням: Безпечно сплатіть карткою або мобільними грошима на сторінці оплати DPO Pay.

Sort Order: місце DPO Pay серед способів оплати на оформленні замовлення. Залиште поле порожнім або введіть ціле число.

Geo Zone: пропонувати DPO Pay лише для платіжних адрес у вибраній географічній зоні. За замовчуванням: All zones. Географічні зони налаштовуються в System > Localisation > Geo Zones.

Total: сума кошика в валюті магазину за замовчуванням, якої має досягти замовлення, щоб пропонувався DPO Pay. Залиште поле порожнім, щоб пропонувати DPO Pay за будь-якої суми.

Облікові дані API

DPO видає Company Token і Service Type ID для вашого торгового облікового запису, а окремі — для тестового. Отримайте їх у свого менеджера DPO або на dpogroup.com (розділ містить посилання на сайт).

Test mode: коли ввімкнено, нові платежі створюються з тестовими Company Token і Service Type. За замовчуванням: увімкнено. Вимкніть, щоб приймати реальні платежі з обліковими даними робочого середовища. Поки опція увімкнена, покупці бачать на кроці Confirm Order повідомлення Тестовий режим: платежі створюються з тестовим обліковим записом. Перевірки статусу та скасування наявних платежів завжди використовують той обліковий запис, з яким було створено платіж.

Test Company Token: Company Token вашого тестового облікового запису DPO.

Test Service Type: числовий Service Type ID вашого тестового облікового запису DPO.

Live Company Token: Company Token вашого торгового облікового запису DPO для робочого середовища.

Live Service Type: числовий Service Type ID вашого торгового облікового запису DPO для робочого середовища.

Збережені Company Token більше не відображаються. Поле залишається порожнім і показує Збережено: залиште порожнім, щоб зберегти. Вводьте нове значення, лише якщо хочете його змінити. Щоб видалити збережений токен, позначте під полем Clear the saved Company Token on save і натисніть Save. Service Type має бути числом. Будь-яке інше значення не зберігається: сторінка показує попередження й залишає попереднє значення, а решта налаштувань зберігається.

Сповіщення про платежі

Push notification URL: push-сповіщення одразу повідомляє вашому магазину, що платіж здійснено, навіть якщо покупець закрив браузер після оплати. URL не задається в панелі: попросіть службу підтримки DPO встановити його для вашого облікового запису. На OpenCart 3 він має вигляд https://your-store/index.php?route=extension/payment/wcp_dpo_pay/notify, на OpenCart 4 — https://your-store/index.php?route=extension/wcp_dpo_pay/payment/wcp_dpo_pay.notify. Він формується з адреси вітрини вашої інсталяції OpenCart. Скопіюйте його точно так, як його показує сторінка. Він має бути доступний з інтернету, без брандмауера чи базової автентифікації перед ним.

Push-сповіщення DPO не мають підпису, тому їхньому вмісту ніколи не довіряють. Розширення використовує їх лише для того, щоб знайти платіж за його токеном транзакції, а потім перевіряє результат безпосередньо в DPO. Токен, який створив не ваш магазин, відхиляється без жодного запиту до DPO.

Заплановна перевірка статусу (cron): викликайте цей URL кожні 15 хвилин із завдання cron на сервері, наприклад за допомогою curl. Непідтверджені платежі перевіряються в DPO через 15 хвилин після переспрямування і знову після закінчення терміну оплати. URL містить секретний токен, тож тримайте його в таємниці. На OpenCart 4 він має вигляд https://your-store/index.php?route=extension/wcp_dpo_pay/payment/wcp_dpo_pay.cron&token= і токен. Без push-URL і cron замовлення отримує статус лише тоді, коли покупець повертається до магазину після оплати.

Замовлення

OpenCart створює замовлення на кроці Confirm Order без статусу (відсутнє замовлення). Замовлення отримує статус лише після того, як DPO підтвердив платіж. Кожне поле нижче перелічує ваші статуси замовлень OpenCart.

Successful payment status: статус замовлення після перевіреного успішного платежу. За замовчуванням: Обробляється. Виберіть Виконано, якщо кожне оплачене замовлення має завершуватися, або власний статус перевірки для ручного підтвердження кожного замовлення.

DPO payment on hold status: статус для платежу, що потребує вашої перевірки: невідповідність суми або валюти, платіж лише з авторизацією, переплата чи недоплата за транзакцією або платіж, який надійшов після скасування замовлення покупцем. Примітка в історії замовлення пояснює причину. За замовчуванням: Очікування, оскільки в OpenCart немає статусу On hold. Ви можете створити власний статус у System > Localisation > Order Statuses і вибрати його тут.

Cancelled order status: якщо неоплачене замовлення DPO Pay переводиться в цей статус, його відкритий платіж DPO також скасовується в DPO. За замовчуванням: Скасовано.

Додатково

Logging: записує виклики API та сповіщення у файл dpo_p_debug.log.php у папці журналів OpenCart (storage/logs). Файл не можна відкрити з веб-браузера, а при досягненні 5 МБ його переміщують у dpo_p_debug.old.log.php. Помилки записуються завжди. Токени маскуються, дані покупців не журналюються. За замовчуванням: вимкнено.

Log: показує розмір і останні записи журналу. Натисніть Clear log, щоб очистити його.

Delete data: якщо увімкнено, видалення розширення прибирає налаштування шлюзу та журнал. Дані DPO, збережені для замовлень, завжди зберігаються. Видалення без цієї опції ніколи не видаляє дані. За замовчуванням: вимкнено.

Імпорт / Експорт

Export: Download JSON зберігає налаштування у файл JSON. Company Token не експортуються.

Import: вставте раніше експортований JSON і натисніть Import, щоб відновити налаштування. Збережені Company Token залишаються.

Оформлення замовлення

На кроці Payment Method покупець вибирає спосіб оплати (за замовчуванням DPO Pay). На кроці Confirm Order покупець бачить ваш опис і примітку Вас буде перенаправлено на захищену сторінку оплати DPO Pay. OpenCart створює замовлення на цьому кроці, ще без статусу. Коли покупець натискає Confirm Order, розширення створює транзакцію DPO на суму замовлення у валюті замовлення з номером замовлення та назвою вашого магазину як описом і надсилає покупця на сторінку оплати DPO. Ім'я, e-mail, телефон і платіжна адреса покупця передаються, щоб заздалегідь заповнити сторінку. Там покупець платить будь-яким способом, увімкненим у вашому обліковому записі DPO. Посилання на оплату дійсне 5 годин. На OpenCart 4 покупець обирає спосіб оплати кнопкою Choose в блоці способу оплати, у вікні Payment method options, і натискає Confirm Order внизу сторінки оформлення замовлення. Якщо магазин не запитує платіжну адресу (типова поведінка OpenCart 4), передається адреса доставки.

Після оплати покупець повертається до вашого магазину. Замовлення позначається оплаченим лише після підтвердження DPO: розширення запитує в DPO результат транзакції, коли покупець повертається, коли надходить push-сповіщення і під час запланованих перевірок. Далі замовлення отримує статус стандартним для OpenCart способом, із звичайними листами про замовлення та оновленням залишків, а покупець бачить сторінку успішного оформлення замовлення OpenCart. На OpenCart 4 браузер не надсилає сесію магазину, коли DPO повертає покупця, тому розширення спочатку показує коротку сторінку, яка знову відкриває ту саму адресу повернення у вашому магазині: покупець зберігає кошик і вхід до облікового запису.

Якщо платіж не підтверджено, покупець повертається до оформлення замовлення з одним із цих повідомлень (на OpenCart 4 вони показуються над сторінкою оформлення). Кошик зберігається.

Якщо покупець натискає на сторінці DPO кнопку повернення до магазину, спочатку перевіряється транзакція. Якщо її оплачено, покупець бачить сторінку успіху. Інакше транзакція скасовується в DPO, і покупець повертається до оформлення замовлення з кошиком.

OpenCart 3 створює нове замовлення щоразу, коли показується крок Confirm Order; OpenCart 4 зберігає одне замовлення для оформлення і оновлює його, а нова спроба є новою транзакцією DPO того самого замовлення. Перед новим платежем перевіряються відкриті транзакції DPO цього замовлення та попередніх замовлень того самого кошика. Якщо одну з них оплачено, цей платіж підтверджується, і покупець переходить на сторінку успіху без другого списання. Якщо одна ще обробляється, покупець бачить Ваш попередній платіж за це замовлення ще обробляється DPO. Будь ласка, зачекайте кілька хвилин, перш ніж повторити спробу. Інакше старі транзакції скасовуються в DPO і створюється нова.

OpenCart 4 зберігає замовлення в оформленні, доки не буде показано сторінку успіху. Якщо це замовлення тим часом закрили (наприклад, скасували або повернули), Confirm Order або повернення з DPO повертає покупця до оформлення: з повідомленням The payment was declined or cancelled. Please try again or choose another payment method., якщо для замовлення не було платежу, або з повідомленням Your previous order was closed by the store. Please confirm the order again: the cart will be paid with a new order., якщо платіж був. Якщо замовлення вже оплачене, а кошик відтоді змінився (інші товари або кількості), повідомлення таке: Your previous order is already paid. Please confirm the order again: the cart will be paid with a new order. В усіх цих випадках наступне натискання Confirm Order оплачує нове замовлення кошика.

Якщо DPO не може розпочати платіж, покупець залишається на кроці Confirm Order з коротким повідомленням над кнопкою, вибраним за кодом помилки DPO, наприклад DPO Pay не підтримує валюту цього замовлення. Будь ласка, оберіть інший спосіб оплати. або Сума перевищує ліміт, дозволений DPO Pay. Будь ласка, оберіть інший спосіб оплати або зв'яжіться з нами. Інші помилки показують DPO Pay тимчасово недоступний. Будь ласка, спробуйте ще раз або оберіть інший спосіб оплати. Технічна причина записується в журнал.

Push-сповіщення та URL cron також працюють, коли магазин перебуває в режимі обслуговування: OpenCart 3 пропускає запити платіжних розширень, а на OpenCart 4 розширення додає стартову дію, яка пропускає ці запити та повернення покупця. Платежі, які вже розпочато, підтверджуються, навіть якщо ви вимкнете спосіб оплати.

Розширення приймає лише разові платежі на сторінці DPO. Воно не має повернень із магазину, збережених карток, підписок і регулярних платежів, полів картки на вашому сайті та захоплення платежів, які лише авторизовано.

Замовлення

Статуси замовлень

Без статусу (відсутнє замовлення): покупця було відправлено до DPO, і він не сплатив, платіж відхилено або скасовано, або DPO ще не підтвердив платіж. У Sales > Orders такі замовлення показуються лише з фільтром Order Status, встановленим на Missing Orders.

Successful payment status (за замовчуванням Обробляється): платіж перевірено. Примітка в історії замовлення показує суму, валюту, код схвалення та початок токена транзакції DPO.

DPO payment on hold status (за замовчуванням Очікування): DPO підтвердив платіж, але сума або валюта відрізняються від замовлення, платіж лише авторизований і не списаний, транзакція переплачена або недоплачена, або покупець скасував платіж чи замовлення вже було скасовано. Примітка пояснює причину. Перевірте транзакцію в порталі DPO. Спишіть або анулюйте платіж, що лише авторизований, у порталі DPO, а потім оновіть статус замовлення.

Cancelled order status (за замовчуванням Скасовано): коли неоплачене замовлення розширення переводиться в цей статус (наприклад, призупинене через платіж лише з авторизацією), його відкрита транзакція DPO також скасовується в DPO.

Пізніший результат відмови ніколи не змінює замовлення, а результати старих транзакцій ніколи не провалюють поточну спробу. Якщо DPO підтверджує другий успішний платіж за вже оплачене замовлення, замовлення не змінюється і отримує примітку про можливе подвійне списання, щоб ви могли повернути кошти в порталі DPO. Такий самий тип примітки додається до оплаченого замовлення, коли той самий кошик (та сама сесія покупця і той самий вміст) був оплачений ще раз з іншим замовленням, наприклад у другій вкладці браузера; те інше замовлення статусу не отримує. Замовлення, яке ви перевели в інший статус (наприклад, повернено), ніколи не відкривається знову; пізній платіж лише додає примітку.

Примітки — це записи в History замовлення, які покупець не бачить. Розширення не має вкладки на сторінці замовлення.

Повернення коштів

Повернення коштів із магазину в цій версії недоступні. Поверніть платіж у торговому порталі DPO, а потім змініть статус замовлення в OpenCart.

Ліцензійний ключ

Розширення працює з ліцензійним ключем VibeFox з vibefox.net. Блок ліцензії License — VibeFox DPO Pay Gateway — це перший блок у Extensions > Extensions > Payments > VibeFox DPO Pay Gateway > Edit, над налаштуваннями. Вставте ключ у License key і натисніть Activate. Після цього блок показує ключ у замаскованому вигляді, статус (наприклад, дату, до якої діє ліцензія, і ваш домен) та кнопки Check now, щоб перевірити статус знову, Change key, щоб ввести інший ключ, і Remove key, щоб видалити ключ із цього магазину. Нижче є рядок Product: opencart-payment-dpo і посилання Manage licenses and domains in your account, яке відкриває ваш обліковий запис vibefox.net. Змінювати ключ можуть лише адміністратори з правом Modify на розширення. Тексти блоку відповідають мові адмін-панелі (включено англійську та російську).

Якщо ключ не прийнято, блок пояснює причину, наприклад Key not found, This key belongs to another product, Domain limit reached або License expired on і дату. Після зміни адреси магазину або після звільнення місця для домену у вашому обліковому записі натисніть Check now. Якщо сервер ліцензій недоступний, розширення продовжує працювати за останнім відомим статусом.

Один ключ працює на одному домені: адреса магазину з налаштувань OpenCart. Видалення ключа з магазину не звільняє місце для домену. Звільніть місце у своєму обліковому записі vibefox.net.

Без активного ключа DPO Pay не показується покупцям на оформленні замовлення. Якщо платіж все ж розпочато, покупець бачить Цей спосіб оплати недоступний. Будь ласка, оберіть інший. Адміністратор, який увійшов в адмін-панель у тому самому браузері, все ще бачить спосіб оплати в магазині, позначений як (unlicensed — visible to admins only), тож ви можете налаштувати та протестувати розширення перед покупкою ключа. На OpenCart 4 цей попередній перегляд недоступний: магазин не бачить входу адміністратора, тому без активного ключа спосіб оплати приховано для всіх. Після одного відкриття сторінки Edit на Dashboard адмін-панелі з'являється нагадування. Закрийте його кнопкою ×, щоб приховати на 7 днів. Існуючі замовлення не зачіпаються: платежі, які вже розпочато, все одно підтверджуються.

Коли ліцензія спливає, розширення продовжує працювати, але оновлення та підтримка потребують продовження. Статус автоматично перевіряється знову, коли ви відкриваєте Dashboard або сторінку Edit адмін-панелі: раз на день упродовж перших 14 днів після введення ключа, потім раз на тиждень. Cron-завдання не потрібне. Видалення розширення завжди прибирає ліцензійний ключ і статус ліцензії.

Усунення несправностей

DPO Pay не з'являється на оформленні замовлення: перевірте, чи активна ліцензія, чи увімкнено Enable/Disable і чи задано Company Token та Service Type обраного режиму: тестові поля в тестовому режимі, робочі — в іншому разі. Сторінка налаштувань показує попередження, якщо їх немає. Також перевірте, чи платіжна адреса входить до вибраної Geo Zone і чи досягає замовлення Total, заданого в налаштуваннях.

Платіж пройшов, але замовлення залишилось без статусу: ймовірно, URL push-сповіщень не налаштовано для вашого облікового запису DPO, а покупець не повернувся до магазину. Попросіть службу підтримки DPO налаштувати URL, показаний у налаштуваннях, і перевірте, чи cron викликає URL перевірки кожні 15 хвилин. Увімкніть Logging і перегляньте поле Log на сторінці розширення.

Push-сповіщення відповідає Unknown transaction: токен транзакції не належить до платежу DPO Pay цього магазину, наприклад push надійшов від іншого магазину на тому самому обліковому записі DPO.

Push-сповіщення відповідає Verification failed: не вдалося звернутися до DPO для перевірки платежу, замовлення в той самий момент оброблялося іншим запитом, або не вдалося встановити статус замовлення. DPO повторює сповіщення, а запланована перевірка також підтверджує замовлення. Причина є в журналі.

Push-URL у браузері показує Method not allowed: це нормально. URL приймає лише запити від DPO.

URL cron відповідає Forbidden: токен в URL невірний. Скопіюйте URL знову зі сторінки налаштувань. Робочий виклик відповідає OK checked= і кількістю перевірених платежів.

Service Type не зберігається: він має бути числовим Service Type ID від DPO.

Покупець бачить This payment method is not available. Please reload the checkout page.: сесія оформлення більше не відповідає замовленню, або спосіб оплати тим часом вимкнули. Покупець перезавантажує сторінку оформлення.

Покупець бачить DPO Pay is temporarily unavailable: DPO відмовився створити транзакцію, наприклад через неправильний Company Token або Service Type, або токен іншого режиму. Код результату DPO є в журналі.

Покупець бачить, що DPO приймає не більше 2 десяткових знаків: сума замовлення має 3 десяткові знаки. DPO не може списати такі суми.

Покупець бачить This order has already been paid with DPO Pay: DPO відхилив другий платіж за те саме замовлення. Перевірте платіж у порталі DPO та замовлення в OpenCart.

Замовлення після оплати в статусі перевірки: прочитайте примітку в History замовлення (див. Статуси замовлень), потім перевірте транзакцію в порталі DPO.

Для розробників: розширення запускає події OpenCart wcp_dpo_pay_customer_data (дані покупця, що надсилаються до DPO) і wcp_dpo_pay_payment_time_limit (термін оплати в годинах).

Видалення

Перейдіть до Extensions > Extensions, виберіть тип Payments і натисніть Uninstall (червона кнопка −) поруч із VibeFox DPO Pay Gateway. Ліцензійний ключ і статус ліцензії цього розширення завжди видаляються. OpenCart завжди видаляє власні налаштування розширення: Enable/Disable, Sort Order, Geo Zone, Total і статуси замовлень розділу Orders, які при повторному встановленні повертаються до значень за замовчуванням. Також видаляється подія OpenCart цього розширення (на OpenCart 4 — його події та стартова дія, яка пропускає DPO і cron у режимі обслуговування). Якщо Delete data увімкнено, видаляються решта налаштувань шлюзу (назва, опис, тестовий режим, Company Token, Service Type, журналювання) та журнал, а повторне встановлення створює новий URL cron. Якщо вимкнено, вони зберігаються для подальшого повторного встановлення. Дані DPO за замовленнями завжди зберігаються, тож пізні сповіщення та повторні перевірки старих платежів продовжують працювати після повторного встановлення. Існуючі замовлення зберігають свої примітки про оплату.

На OpenCart 4, щоб видалити також файли розширення, після видалення перейдіть до Extensions > Installer і натисніть Uninstall (помаранчева кнопка −) поруч із VibeFox DPO Pay Gateway у списку встановлених розширень, а потім Delete (червона кнопка з кошиком), щоб видалити завантажений пакет.

DPO Pay є товарним знаком його відповідного власника. Це розширення не афілійоване з DPO Pay і не схвалене DPO Pay.