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

Вимоги

PrestaShop: 8.0–9.x.

PHP: 8.0 або новіша. Модуль не встановлюється на старіших версіях PHP.

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

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

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

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

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

1. У бек-офісі перейдіть до Modules > Module Manager і натисніть Upload a module. Оберіть ZIP-файл модуля.

2. Коли завантаження завершиться, натисніть Configure або пізніше знайдіть VibeFox ePayco Payment у списку модулів і натисніть Configure.

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

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

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

Під час встановлення модуль створює два статуси замовлення: Awaiting ePayco payment і ePayco payment on hold. PrestaShop за замовчуванням пропонує новий спосіб оплати для всіх валют, країн і груп клієнтів. Обмежити його можна в Payment > Preferences.

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

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

ePayco

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

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

Description: текст під способом оплати на етапі оформлення. За замовчуванням: Pay securely with 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. Зберігайте в таємниці.

Збережені секретні ключі більше не відображаються. Поле залишається порожнім і показує Saved — leave empty to keep it. Вводьте нове значення, лише якщо хочете його змінити.

Видалення збережених секретних ключів: позначте Secret Key (P_KEY) або Private Key (PRIVATE_KEY) і натисніть Save, щоб видалити ключ. Порожнє поле зберігає збережене значення.

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

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

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

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

URL підтвердження повідомляє вашому магазину результат оплати. Він автоматично передається в ePayco з кожним платежем, тож у панелі ePayco нічого налаштовувати не потрібно. Розділ показує URL. З ЧПУ-адресами він виглядає так: https://your-shop/module/wcp_epayco_payment/confirmation, можливо, з кодом мови, наприклад /en/. Він має бути доступним з інтернету та не блокуватися брандмауером або базовою автентифікацією. Він працює, поки магазин перебуває в режимі обслуговування, і не блокується обмеженням за країною вашого магазину.

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

Додатково

Logging: записує помилки API та підтвердження оплати до logs/epc_p_debug.log.php у папці модуля. Файл не можна відкрити через веб. Ключі та дані покупців не записуються. За замовчуванням: вимкнено. Помилки записуються завжди, навіть коли опцію вимкнено.

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

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

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

На етапі оплати покупець обирає спосіб оплати (за замовчуванням ePayco) і підтверджує вибір. Модуль створює сесію оплати ePayco на суму кошика у валюті кошика з податками, номером кошика, а також ім'ям платника, адресою, e-mail і телефоном. В ePayco платіж відображається як Cart # і номер кошика. Мова форми оплати — іспанська або англійська, залежно від мови магазину. На цьому етапі замовлення ще не існує.

Далі покупець бачить сторінку 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. Кожне натискання кнопки оплати створює нову сесію ePayco.

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

Для платежу, що очікує (наприклад, PSE або готівка), замовлення створюється в статусі Awaiting ePayco payment, а сторінка підтвердження показує 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. Кошик зберігається, замовлення не створюється.

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

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

Замовлення

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

No order yet: покупця було відправлено в ePayco, і він не оплатив, ePayco ще не підтвердив платіж або платіж було відхилено. Існує лише кошик.

Payment accepted: ePayco схвалив платіж. Платіж записується з референсом ePayco (ref_payco) як ID транзакції, а примітка показує референс, статус, суму, спосіб оплати та код схвалення.

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

ePayco payment on hold: ePayco схвалив платіж, сума або валюта якого відрізняється від замовлення (наприклад, кошик було змінено після початку оплати), або схвалив платіж після скасування замовлення. Фактично сплачена сума записується в замовлення, якщо валюта збігається. Не відправляйте товар, доки не перевірите транзакцію в панелі ePayco.

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

Refunded: ePayco скасував платіж за цим замовленням.

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

Блок платежу ePayco

На сторінці замовлення є блок ePayco payment з референсом ePayco (ref_payco), ID транзакції, статусом, способом оплати, кодом схвалення, датою транзакції, позначкою Test mode для тестових платежів і ePayco notes замовлення. Для замовлення в статусі ePayco payment on hold блок показує попередження перевірити транзакцію перед відправленням.

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

Повернення з магазину не підтримуються. Поверніть платіж у панелі ePayco, а за потреби оновіть замовлення в PrestaShop вручну. Скасування платіжної транзакції, про яке повідомляє ePayco, переводить замовлення у статус Refunded.

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

Модуль працює з ліцензійним ключем VibeFox з vibefox.net. Блок ліцензії License — VibeFox ePayco Payment є першим блоком на Modules > Module Manager > VibeFox ePayco Payment > Configure, над налаштуваннями. Введіть ключ у License key і натисніть Activate. Після цього блок показує ключ у замаскованому вигляді, статус (наприклад, дату, до якої ліцензія активна, і ваш домен) та кнопки Check now, щоб перевірити статус знову, Change key, щоб ввести інший ключ, і Remove key, щоб видалити ключ із цього магазину. Нижче розташовані рядок Product: presta-payment-epayco і посилання Manage licenses and domains in your account, яке відкриває ваш обліковий запис vibefox.net. Змінювати ключ можуть лише співробітники з дозволом Configure для модуля. Тексти блоку відповідають мові бек-офісу (включено англійську та російську).

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

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

Без активного ключа ePayco не показується покупцям на етапі оформлення. Якщо оплату все одно розпочато, покупець бачить This payment method is not available. Please choose another one. Вітрина магазину PrestaShop не знає, що ви увійшли в бек-офіс, тож спосіб оплати приховується й для вас: модуль можна налаштувати до придбання ключа, але протестувати його на етапі оформлення не можна. Нагадування з'являється в Modules > Module Manager на вкладці Alerts. Наявні замовлення не постраждають: платежі, які вже почалися, усе одно підтверджуються.

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

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

ePayco не з'являється на етапі оформлення: перевірте, що ліцензія активна, Enable/Disable увімкнено, введено всі чотири ключі та валюта кошика COP або USD. Сторінка налаштувань показує попередження, якщо ключі не заповнені. У Payment > Preferences перевірте, що модуль дозволений для валюти кошика, країни покупця та групи покупця.

Оплата пройшла, але замовлення не створено: підтвердження ePayco не доходить до вашого магазину. Перевірте, що URL підтвердження з налаштувань відкривається з інтернету і не блокується брандмауером, модулем безпеки чи базовою автентифікацією. Подивіться поле Log на сторінці модуля; увімкніть Logging, щоб бачити кожне підтвердження. Замовлення також створюється, коли покупець повертається до магазину після оплати.

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

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

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

Підтвердження відповідає «Busy, retry later»: замовлення в цей момент оновлювалося іншим запитом, або замовлення не вдалося створити (наприклад, модуль вимкнено). ePayco повторить підтвердження. Причина є в журналі.

Покупець бачить «We could not connect to ePayco»: ePayco відхилив PUBLIC_KEY і PRIVATE_KEY. Журнал показує відповідь ePayco. Скопіюйте обидва ключі заново.

Покупець бачить «ePayco could not start the payment»: ePayco не створив сесію оплати. Прочитайте в журналі помилку ePayco.

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

Тестовий платіж не оплатив замовлення: тестові транзакції ніколи не оплачують замовлення, оформлені в робочому режимі. Оформлюйте тестове замовлення, коли Test Mode увімкнено.

Замовлення має статус ePayco payment on hold: прочитайте примітки в блоці ePayco payment (див. Статуси замовлення) і перевірте транзакцію в панелі ePayco перед відправленням.

Видалення

Перейдіть до Modules > Module Manager, відкрийте меню поруч із VibeFox ePayco Payment і виберіть Uninstall. Ліцензійний ключ і статус ліцензії цього модуля завжди видаляються. Якщо Delete Data on Uninstall увімкнено, налаштування модуля та журнал видаляються. Якщо вимкнено, усі налаштування зберігаються для повторного встановлення. Дані ePayco, збережені для замовлень, і статуси замовлень Awaiting ePayco payment та ePayco payment on hold завжди зберігаються. Наявні замовлення зберігають свої примітки про оплату та ID транзакцій.

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