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

Вимоги

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

PHP: 8.0 або новіша версія.

Валюта: колумбійське песо (COP) або долар США (USD). Якщо покупець платить в іншій валюті, спосіб оплати приховується під час оформлення замовлення.

Обліковий запис ePayco: вам потрібні чотири ключі вашого облікового запису ePayco: P_CUST_ID_CLIENTE, P_KEY, PUBLIC_KEY і PRIVATE_KEY. Їх можна знайти в панелі ePayco у розділі Integrations, API keys. Ті самі ключі працюють у тестовому та робочому режимах. Способи оплати, які може використовувати покупець (картки, PSE, мережі готівкової оплати, гаманці), — це ті, що увімкнені у вашому обліковому записі ePayco.

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

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

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

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

OpenCart 3

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

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

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

4. Введіть чотири ключі ePayco і виберіть тип оформлення замовлення (див. Налаштування).

5. Увімкніть Enable/Disable і натисніть Save. Перевірте оплату з увімкненим Test Mode і тестовими картками ePayco, а потім вимкніть Test Mode.

OpenCart 4

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

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

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

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

Нове встановлення починається з вимкненим способом оплати та вимкненим тестовим режимом. URL підтвердження передається в ePayco з кожним платежем, тож у панелі ePayco нічого налаштовувати не потрібно.

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

Усі параметри розташовані на сторінці розширення: Extensions > Extensions > Payments > VibeFox ePayco Payment > Edit. Розділи перелічено зліва; кнопка Save під списком зберігає всю сторінку. Над налаштуваннями сторінка пояснює, що замовлення отримує статус лише після того, як ePayco підтвердить транзакцію. Вона попереджає, якщо не введено всі чотири ключі (тоді спосіб оплати приховується під час оформлення замовлення), і якщо типова валюта вашого магазину не COP і не USD, а також показує Test mode is on: customers pay with ePayco test cards and no real money is charged., доки ввімкнено тестовий режим. Без права змінювати розширення сторінка показує налаштування, але не може їх зберегти.

Під час збереження Title має містити не більше 128 символів, Sort Order має бути цілим числом, Total має бути числом не менше нуля, а геозона та статуси замовлень мають існувати. Інакше з'являється помилка з назвою поля, і нічого не зберігається.

ePayco

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

Title: назва способу оплати, яку бачить покупець під час оформлення замовлення. Вона також зберігається в замовленні як назва способу оплати. До 128 символів; якщо поле порожнє, покупець бачитиме ePayco. За замовчуванням: ePayco.

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

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

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

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

Ключі облікового запису ePayco

Знайдіть чотири ключі в панелі ePayco у розділі Integrations, API keys (розділ містить посилання на панель). P_CUST_ID_CLIENTE і P_KEY перевіряють підтвердження платежів; PUBLIC_KEY і PRIVATE_KEY створюють сесії оформлення. Ті самі ключі працюють у тестовому та робочому режимах.

Customer ID (P_CUST_ID_CLIENTE): ваш ідентифікатор клієнта ePayco (числовий).

Secret Key (P_KEY): використовується для перевірки підпису підтверджень платежів ePayco. Зберігайте в таємниці.

Public Key (PUBLIC_KEY): ваш публічний ключ API ePayco.

Private Key (PRIVATE_KEY): ваш приватний ключ API ePayco. Зберігайте в таємниці.

Збережені ключі Secret Key (P_KEY) і Private Key (PRIVATE_KEY) більше не відображаються. Поле залишається порожнім і показує Saved — leave empty to keep it. Вводьте нове значення, лише якщо хочете його змінити. Щоб видалити збережений ключ, позначте Clear saved secret on save під полем і натисніть Save.

Test Mode: сесії оформлення створюються як тестові транзакції. Покупці платять тестовими картками ePayco, і реальні кошти не списуються. Тестові транзакції ніколи не оплачують замовлення, створені в робочому режимі. За замовчуванням: вимкнено. Поки режим увімкнено, покупці бачать TEST MODE — use ePayco test cards, no real money is charged. на кроці Confirm Order і на сторінці оплати.

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

Checkout Type: як відкривається форма оплати ePayco.

URL підтвердження

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

Кожне підтвердження має містити дійсний підпис, створений з вашими P_CUST_ID_CLIENTE і P_KEY. Підтвердження без дійсного підпису відхиляються і нічого не змінюють. Без підтвердження замовлення отримує статус лише тоді, коли покупець повертається до магазину після оплати.

Замовлення

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

Order Status After Payment: ePayco схвалив платіж, а сума та валюта збігаються із замовленням. За замовчуванням: В обробці.

Awaiting Payment Status: ePayco повідомив, що платіж очікує або утримується (переказ PSE, мережі готівкової оплати). Замовлення змінюється автоматично, коли ePayco його схвалює або відхиляє. За замовчуванням: Очікує оплати.

On Hold (Review) Status: ePayco схвалив платіж, сума або валюта якого відрізняється від замовлення, або схвалив його після того, як замовленню було присвоєно інший статус (наприклад, Скасовано). Примітка пояснює причину. Не відправляйте товар, доки не перевірите транзакцію в панелі ePayco. За замовчуванням: Очікує оплати, оскільки в OpenCart немає статусу «На утриманні». Ви можете створити власний статус у System > Localisation > Order Statuses і вибрати його тут.

Payment Failed Status: платіж, що очікувався, було відхилено, він не пройшов, завершився за часом або скасований. Новий схвалений платіж усе одно оплачує замовлення. За замовчуванням: Невдалий.

Reversed Status: ePayco повернув платіж за замовленням. За замовчуванням: Повернено.

Додатково

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

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

Delete Data on Uninstall: якщо увімкнено, під час видалення розширення видаляються його налаштування та журнал. Дані ePayco, збережені для замовлень, завжди залишаються. За замовчуванням: вимкнено.

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

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

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

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

На кроці Payment Method покупець вибирає спосіб оплати (за замовчуванням ePayco). На кроці Confirm Order покупець бачить ваш опис і примітку After confirming the order you pay securely in the ePayco checkout (cards, PSE, cash, wallets). OpenCart створює замовлення на цьому кроці, все ще без статусу. На OpenCart 4 покупець обирає спосіб оплати кнопкою Choose в блоці способу оплати, у вікні Payment method options, і натискає Confirm Order внизу сторінки оформлення замовлення. Коли покупець натискає Confirm Order, розширення створює сесію оформлення ePayco на суму замовлення у валюті замовлення, з податками, номером замовлення та ім'ям, адресою, e-mail і телефоном для рахунку. Платіж в ePayco відображається як Order # і номер замовлення. Мова форми оплати — іспанська або англійська, залежно від мови магазину покупця.

Далі покупець бачить сторінку ePayco payment з текстом Thank you for your order. The secure ePayco checkout opens automatically; if it does not, click the button below. Форма оплати ePayco відкривається як спливаюче вікно або як перенаправлення, залежно від Checkout Type. На сторінці також є кнопка Pay with ePayco і посилання Choose another payment method. Кожне нове натискання Confirm Order створює нову сесію ePayco (OpenCart 3 створює нове замовлення щоразу, коли показується крок Confirm Order; OpenCart 4 оновлює замовлення оформлення, тож нова спроба оплачується тим самим замовленням). Якщо попереднє замовлення з того самого кошика вже оплачено або очікує ePayco, покупця переведуть на сторінку успішного оформлення замовлення, і з нього повторно не спишуть кошти.

У формі оплати ePayco покупець платить одним із способів, увімкнених у вашому обліковому записі ePayco. Потім ePayco надсилає підтвердження до вашого магазину й повертає покупця. Замовлення позначається оплаченим лише після того, як ePayco його підтвердить: підписаним підтвердженням або серверним запитом до ePayco, коли покупець повертається. Саме повернення покупця ніколи не оплачує замовлення. Далі замовлення отримує статус стандартним для OpenCart способом, зі звичайними листами про замовлення та оновленням запасів, а покупець бачить сторінку успішного оформлення замовлення OpenCart.

Для платежу, що очікує (наприклад, PSE або готівка), замовлення отримує Awaiting Payment Status, а сторінка успіху показує Your ePayco payment is being confirmed. We will e-mail you as soon as it is approved. Якщо платіж, що очікував, уже відхилено або він завершився за часом, коли покупець повертається, сторінка показує Your ePayco payment was not completed. Please contact us about this order. Якщо ePayco ще не підтвердив платіж, коли покупець повертається, відкривається сторінка Payment confirmation з текстом We are waiting for ePayco to confirm your payment. This page does not need to stay open. і кнопкою Check again.

Якщо платіж відхилено, покупець повертається до оформлення замовлення з повідомленням Your ePayco payment was declined or could not be completed. You can try again or choose another payment method. Якщо покупець повертається без оплати, повідомлення таке: The ePayco payment was not completed. If you already paid, the order will be updated as soon as ePayco confirms it; otherwise you can try again. Кошик зберігається, а замовлення залишається без статусу. На OpenCart 4 ці повідомлення показуються над сторінкою оформлення замовлення.

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

Якщо ePayco не може розпочати оплату, покупець залишається на кроці Confirm Order з коротким повідомленням над кнопкою, наприклад We could not connect to ePayco. Please try again in a moment or choose another payment method. Технічна причина записується в журнал.

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

Замовлення

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

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

Order Status After Payment (default Processing): ePayco схвалив платіж. Примітка показує посилання ePayco, стан, суму, спосіб оплати та код схвалення.

Awaiting Payment Status (default Pending): ePayco повідомив, що платіж очікує або утримується, наприклад переказ PSE або готівкова оплата. Коли ePayco його схвалює, замовлення переходить до Order Status After Payment; коли його відхиляють, він не проходить, завершується за часом або скасовується, замовлення переходить до Payment Failed Status. OpenCart надсилає покупцю e-mail про ці зміни.

On Hold (Review) Status (default Pending): ePayco схвалив платіж, сума або валюта якого відрізняється від замовлення, або схвалив платіж після того, як ви присвоїли замовленню інший статус (наприклад, Скасовано). Примітка це пояснює. Перевірте транзакцію в панелі ePayco перед відправленням.

Payment Failed Status (default Failed): платіж, що очікувався, не пройшов. Примітка показує причину від ePayco. Новий схвалений платіж усе одно оплачує замовлення. Пізня невдача ніколи не змінює оплачене замовлення.

Reversed Status (default Refunded): ePayco повернув платіж, яким було оплачено це замовлення.

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

Вкладка VibeFox ePayco Payment

У розділі Sales > Orders відкрийте замовлення, оплачене через ePayco. Унизу сторінки замовлення, поруч із History і Additional, вкладка VibeFox ePayco Payment показує ePayco reference (ref_payco), Transaction ID, State, Payment method, Approval code, Transaction date, Mode (з міткою Test mode для тестових платежів), Attempt status і ePayco notes замовлення. Для замовлення на перевірці вкладка показує попередження перевірити транзакцію перед відправленням. Вкладка доступна лише для читання і показується користувачам, які мають доступ до розширення.

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

Повернення коштів з магазину не підтримуються. Поверніть платіж у панелі ePayco, а за потреби вручну оновіть замовлення в OpenCart. Скасування платіжної транзакції, про яке повідомляє ePayco, переводить замовлення в Reversed Status. Повернення товарів у розділі Sales > Returns не повертають гроші через ePayco.

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

Розширення працює з ліцензійним ключем VibeFox з vibefox.net. Блок ліцензії License — VibeFox ePayco Payment — це перший блок на сторінці Extensions > Extensions > Payments > VibeFox ePayco Payment > Edit, над налаштуваннями. Вставте ключ у поле License key і натисніть Activate. Після цього блок показує ключ у замаскованому вигляді, статус (наприклад, дату, до якої дійсна ліцензія, і ваш домен), а також кнопки Check now, щоб перевірити статус знову, Change key, щоб ввести інший ключ, і Remove key, щоб видалити ключ з цього магазину. Нижче розташовані рядок Product: opencart-payment-epayco і посилання 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.

Без активного ключа ePayco не показується покупцям під час оформлення замовлення. Якщо оплату все ж розпочато, покупець бачить This payment method is not available. Please choose another one. Адміністратор, що увійшов в адмін-панель у тому самому браузері, усе ще бачить спосіб оплати в магазині, позначений (unlicensed — visible to admins only), тож ви можете налаштувати та протестувати розширення до купівлі ключа. На OpenCart 4 цей попередній перегляд недоступний: магазин не бачить входу адміністратора, тому без активного ключа спосіб оплати приховано для всіх. Після одного відкриття сторінки Edit на Dashboard адмін-панелі з'являється нагадування. Закрийте його кнопкою ×, щоб приховати на 7 днів. Наявні замовлення не змінюються: платежі, що вже розпочаті, і далі підтверджуються.

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

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

ePayco does not appear at checkout: перевірте, чи ліцензія активна, чи увімкнено Enable/Disable, чи введено всі чотири ключі та чи покупець платить у COP або USD. Сторінка налаштувань показує попередження, якщо ключів бракує. Також перевірте, чи платіжна адреса належить до вибраної Geo Zone і чи досягає замовлення Total, встановленого в налаштуваннях.

The payment went through, but the order stays without a status: підтвердження від ePayco не доходить до вашого магазину. Перевірте, чи URL підтвердження, показаний у налаштуваннях, відкривається з інтернету і не блокується брандмауером, розширенням безпеки чи базовою автентифікацією. Перегляньте поле Log на сторінці розширення; увімкніть Logging, щоб бачити кожне підтвердження. Замовлення також отримує статус, коли покупець повертається до магазину після оплати.

Confirmation answers Invalid signature: Customer ID (P_CUST_ID_CLIENTE) або Secret Key (P_KEY) не відповідає обліковому запису ePayco, який прийняв платіж. Скопіюйте обидва знову з панелі ePayco.

Confirmation answers Gateway not configured: P_CUST_ID_CLIENTE або P_KEY порожній. Введіть їх у налаштуваннях.

Confirmation answers Order not found: підтвердження стосується замовлення без платежу ePayco цього магазину.

Confirmation answers Busy, retry later: замовлення в цей момент оновлював інший запит. ePayco повторить підтвердження. Причина є в журналі.

The customer sees We could not connect to ePayco: ePayco відхилив PUBLIC_KEY і PRIVATE_KEY. У журналі видно відповідь ePayco. Скопіюйте обидва ключі знову.

The customer sees ePayco could not start the payment: ePayco не створив сесію оформлення. Прочитайте в журналі помилку ePayco.

The customer sees This payment method is not available right now: сесія оформлення більше не відповідає замовленню, спосіб оплати тим часом вимкнули або ключі видалили. Покупець перезавантажує сторінку оформлення замовлення.

The ePayco checkout does not open: покупець бачить The ePayco checkout could not be loaded. Please reload the page or choose another payment method. Скрипт оформлення ePayco не вдалося завантажити на сторінці оплати. Покупець може перезавантажити сторінку або скористатися Choose another payment method.

A test payment did not pay the order: тестові транзакції ніколи не оплачують замовлення, створені в робочому режимі. Оформлюйте тестове замовлення, поки Test Mode увімкнено.

Order is in the review status after payment: прочитайте примітки на вкладці VibeFox ePayco Payment (див. Статуси замовлень) і перевірте транзакцію в панелі ePayco перед відправленням.

Видалення

Перейдіть до Extensions > Extensions, виберіть тип Payments і натисніть Uninstall (червона кнопка −) поруч із VibeFox ePayco Payment. Ліцензійний ключ і статус ліцензії цього розширення завжди видаляються. OpenCart завжди видаляє власні налаштування розширення: Enable/Disable, Sort Order, Geo Zone, Total і статуси замовлень у розділі Orders, які повертаються до типових значень під час повторного встановлення. Подія OpenCart розширення також видаляється (на OpenCart 4 також події та стартова дія, яка пропускає підтвердження й повернення покупця в режимі обслуговування). Якщо Delete Data on Uninstall увімкнено, видаляються інші налаштування оплати (заголовок, опис, ключі, тестовий режим, тип оформлення, журнал) і сам журнал. Якщо вимкнено, вони зберігаються для повторного встановлення. Дані ePayco, збережені для замовлень, завжди зберігаються, тож пізні підтвердження старих замовлень працюють і після повторного встановлення. Наявні замовлення зберігають свої примітки про оплату.

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

ePayco є торговельною маркою її власника. Це розширення не пов'язане з ePayco і не схвалене ePayco.