VibeFox ePay.bg for OpenCart — Допомога

Вимоги

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

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

Валюта: болгарський лев (BGN), євро (EUR) або долар США (USD). Замовлення списується у власній валюті з 2 десятковими знаками. Коли покупець оформлює замовлення в іншій валюті, спосіб оплати приховується.

Обліковий запис ePay.bg: потрібні номер клієнта (MIN) і секретний ключ з вашого профілю мерчанта ePay.bg: бойові — з www.epay.bg, тестові — з demo.epay.bg (тестовий обліковий запис реєструється окремо). Також потрібно вказати в профілі мерчанта URL сповіщень вашого магазину.

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

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

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

OpenCart 3

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

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

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

4. Введіть MIN і секретний ключ для тестового та/або робочого режиму (див. Конфігурація).

5. Скопіюйте URL, який показано в розділі Payment notifications (IPN), у поле URL for receiving notifications профілю мерчанта ePay.bg — і в демонстраційному, і в робочому профілі. Без нього жодне замовлення не отримає статусу.

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

OpenCart 4

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

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

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

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

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

Конфігурація

Усі налаштування розташовані на сторінці розширення: Extensions > Extensions > Payments > VibeFox ePay.bg Gateway > Edit. Розділи перелічено ліворуч; кнопка Save під списком зберігає всю сторінку. Над налаштуваннями сторінка показує помилку, якщо валюта за замовчуванням у вашому магазині не BGN, EUR або USD; попередження, якщо спосіб оплати увімкнено, але MIN або секретний ключ вибраного режиму порожній (тоді він приховується під час оформлення замовлення, а під час збереження з'являється те саме попередження); і Test mode is on: payments go to demo.epay.bg and no real money is charged., доки тестовий режим увімкнено. Без права змінювати розширення сторінка показує налаштування, але не може їх зберегти.

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

ePay.bg

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

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

Description: текст, який показується покупцеві на кроці Confirm Order. За замовчуванням: Pay securely via ePay.bg with a bank card or your ePay.bg account.

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

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

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

Обліковий запис ePay.bg

Номер клієнта (MIN) і секретний ключ наведено у вашому профілі мерчанта на www.epay.bg (робочий) і demo.epay.bg (тестовий обліковий запис, реєструється окремо).

Test Mode: вмикає тестовий режим. Покупців перенаправляють у демонстраційне середовище ePay.bg, а запити підписуються тестовими обліковими даними. За замовчуванням: увімкнено. Поки він увімкнений, покупці на кроці Confirm Order бачать напис Test mode (demo.epay.bg): no real payment is taken.

Test Merchant ID (MIN): номер клієнта (MIN) вашого тестового облікового запису мерчанта на demo.epay.bg.

Test Secret Key: секретний ключ вашого облікового запису мерчанта на demo.epay.bg (64 символи).

Live Merchant ID (MIN): номер клієнта (MIN) вашого облікового запису мерчанта на www.epay.bg.

Live Secret Key: секретний ключ вашого облікового запису мерчанта на www.epay.bg (64 символи), який використовується для підпису HMAC-SHA1.

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

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

Сповіщення повідомляє вашому магазину, що запит на оплату сплачено, відхилено або минув термін його дії. Поле Notification URL показує URL, який потрібно вказати як URL for receiving notifications у профілі мерчанта ePay.bg — і в робочому, і в демонстраційному. На OpenCart 3 він має вигляд https://your-store/index.php?route=extension/payment/wcp_epaybg_gateway/notify, на OpenCart 4 — https://your-store/index.php?route=extension/wcp_epaybg_gateway/payment/wcp_epaybg_gateway.notify. Він формується з адреси вітрини вашої інсталяції OpenCart. Скопіюйте URL точно так, як його показують налаштування. Замовлення отримують статус лише з цих підписаних сповіщень; покупець, який повернувся в магазин, не сплачує замовлення.

ePay.bg повідомляє такі результати для кожного рахунку:

Сповіщення без дійсної контрольної суми відхиляються, і ePay.bg продовжує їх надсилати. Контрольна сума перевіряється секретним ключем кожного режиму, який його має, тому платежі, розпочаті до перемикання між тестовим і робочим режимами, усе одно підтверджуються. Платіж має надійти в тому режимі, в якому було зроблено запит; інакше замовлення переходить у статус утримання. Без URL сповіщень у профілі мерчанта жодне замовлення не отримає статусу.

Запит на оплату

Invoice Prefix: лише цифри (до 10), які ставляться перед ID замовлення OpenCart, утворюючи номер рахунку ePay.bg, наприклад 00001 + 123 = 00001123. Використовуйте різні префікси для різних магазинів в одному обліковому записі ePay.bg. Інші символи видаляються під час збереження, з попередженням, яке показує збережений префікс. Змінити префікс пізніше безпечно: відкриті запити на оплату знаходяться за рахунком, збереженим для кожного з них. За замовчуванням: 00001.

Expiration Time: час, після завершення якого неоплачений запит на оплату втрачає чинність; ePay.bg повідомляє про це як про прострочений, і замовлення не отримує статусу. Оберіть 1, 3, 6, 12, 24, 48 або 72 години. Час надсилається за болгарським часом, незалежно від часового поясу вашого магазину. За замовчуванням: 24 години.

Language: мова сторінки оплати ePay.bg, англійська або болгарська. За замовчуванням: English.

Замовлення

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

Order Status After Payment: який статус встановлюється після успішної оплати.

Processing status: статус OpenCart для Default і Processing. За замовчуванням: Processing.

Completed status: статус OpenCart для Completed. За замовчуванням: Complete.

On Hold status: статус OpenCart для On Hold і для платежів, які потребують ручної перевірки: сума замовлення або валюта змінилися після запиту на оплату, сповіщення надійшло в іншому режимі або статус замовлення було змінено до надходження платежу (наприклад, скасовано). Таке замовлення не позначається оплаченим; примітка пояснює причину. За замовчуванням: Pending, оскільки в OpenCart немає статусу On hold. Ви можете створити власний статус у розділі System > Localisation > Order Statuses і вибрати його тут.

Додатково

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

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

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

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

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

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

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

На кроці Payment Method покупець обирає спосіб оплати (за замовчуванням ePay.bg). На кроці Confirm Order покупець бачить ваш опис і примітку You will be redirected to ePay.bg to pay with a bank card or your ePay.bg account. OpenCart створює замовлення на цьому кроці, все ще без статусу. На OpenCart 4 покупець обирає спосіб оплати кнопкою Choose в блоці способу оплати, у вікні Payment method options, і натискає Confirm Order внизу сторінки оформлення замовлення. Коли покупець натискає Confirm Order, розширення надсилає його до ePay.bg з підписаним запитом на оплату на суму замовлення у валюті замовлення, з номером рахунку та терміном дії. Платіж відображається в ePay.bg як Order з номером замовлення. У ePay.bg покупець платить банківською карткою або з облікового запису ePay.bg.

Після оплати покупець повертається до вашого магазину. Замовлення позначається оплаченим лише після того, як ePay.bg підтверджує платіж підписаним сповіщенням. Потім замовлення отримує статус стандартним для OpenCart способом, із звичайними листами про замовлення та оновленням залишків. Якщо сповіщення вже надійшло, покупець бачить сторінку успішного оформлення замовлення OpenCart. Якщо ні, сторінка Payment confirmation показує Thank you. Your payment is being confirmed by ePay.bg — your order is confirmed as soon as ePay.bg reports the payment. з кнопками Check again і Back to checkout.

Якщо покупець скасовує оплату на ePay.bg, він повертається до оформлення замовлення з повідомленням The ePay.bg payment was cancelled. You can try again or choose another payment method. Якщо ePay.bg повідомив, що запит відхилено або прострочено, з'являється повідомлення The payment was not completed. You can try again or choose another payment method. Кошик зберігається. На OpenCart 4 ці повідомлення показуються над сторінкою оформлення замовлення. Нова спроба для того самого замовлення використовує той самий номер рахунку. OpenCart 3 створює нове замовлення щоразу, коли показується крок Confirm Order; OpenCart 4 оновлює замовлення оформлення, тож нова спроба оплачується тим самим замовленням з новим запитом на оплату. Якщо інше замовлення з того самого кошика вже оплачено, покупець переходить на сторінку успіху, і нова оплата не розпочинається.

OpenCart 4 зберігає замовлення в оформленні, доки не буде показано сторінку успіху. Якщо це замовлення тим часом закрили без оплати (наприклад, ви його скасували), покупець повертається до оформлення з повідомленням Your previous order was cancelled without a payment. Please confirm the order again to pay with a new order., а наступне натискання Confirm Order оплачує нове замовлення кошика. Якщо замовлення вже оплачене, а кошик відтоді змінився, зокрема змінилася кількість, покупець повертається до оформлення, і наступне натискання Confirm Order оплачує змінений кошик новим замовленням. Оплачене замовлення ніколи не показується як оплачене для іншого кошика.

Якщо замовлення не можна оплатити через ePay.bg, покупець залишається на кроці Confirm Order з коротким повідомленням над кнопкою, наприклад ePay.bg payments are temporarily unavailable. Please choose another payment method. або повідомленням, що ePay.bg не приймає платежі у валюті замовлення.

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

Розширення приймає лише разові платежі через ePay.bg. Воно не підтримує повернення коштів з OpenCart, збережені картки, підписки чи періодичні платежі, а також готівкові платіжні коди EasyPay або B-Pay.

Замовлення

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

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

Processing, Completed або On Hold status: платіж підтверджено. Статус відповідає Order Status After Payment. Примітка показує номер рахунку, дату платежу, STAN і код BORICA.

Статус On Hold після оплати: платіж надійшов, але не за те, що замовлення вказує зараз: сума замовлення або валюта змінилися після запиту на оплату, сповіщення надійшло в іншому режимі (тестовому або робочому), ніж запит, або спосіб оплати замовлення більше не ePay.bg. Платіж не реєструється як оплачений. Так само буває, якщо ви вже присвоїли замовленню інший статус, наприклад скасували його. Примітка пояснює причину. Перевірте платіж у панелі мерчанта ePay.bg, а потім вручну виконайте або поверніть замовлення.

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

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

Вкладка VibeFox ePay.bg Gateway

У розділі Sales > Orders відкрийте замовлення, оплачене через ePay.bg. Унизу сторінки замовлення, поруч із History і Additional, вкладка VibeFox ePay.bg Gateway показує рахунок, середовище (тестове або робоче) з міткою Test mode для тестових платежів, запитану суму та валюту, стан запиту на оплату, результат сповіщення, дату платежу, STAN, код BORICA та ePay.bg notes замовлення. Вкладка доступна лише для читання і показується користувачам, які мають доступ до розширення.

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

Повернення коштів з OpenCart недоступні, оскільки в WEB API ePay.bg немає виклику для повернення. Поверніть платіж у панелі мерчанта ePay.bg і вручну оновіть статус замовлення в OpenCart. Повернення товарів у розділі Sales > Returns не повертають кошти через ePay.bg.

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

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

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

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

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

ePay.bg не з'являється під час оформлення замовлення: перевірте, що ліцензія активна, що Enable/Disable увімкнено, що заповнено MIN і секретний ключ вибраного режиму та що покупець оформлює замовлення в BGN, EUR або USD. Сторінка налаштувань показує попередження, якщо облікові дані не заповнені. Також перевірте, що платіжна адреса входить до вибраної Geo Zone і що сума замовлення досягає Total, заданої в налаштуваннях.

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

Сповіщення відповідає ERR=Not valid CHECKSUM: жоден збережений секретний ключ не відповідає профілю мерчанта, який надіслав сповіщення. ePay.bg продовжує повторювати спроби, тож замовлення отримає статус, щойно ключ буде правильним.

Сповіщення відповідає ERR=Not configured: секретний ключ не збережено. Введіть його.

Сповіщення відповідає STATUS=NO для рахунку: рахунок виставлено не цим магазином, наприклад іншим магазином в тому самому обліковому записі ePay.bg. Дайте кожному магазину власний Invoice Prefix.

Сповіщення відповідає STATUS=ERR: тимчасова помилка, наприклад два сповіщення для одного замовлення в один момент або неможливість встановити статус замовлення. ePay.bg надішле сповіщення знову. Причину показано в журналі.

URL сповіщення показує ERR=Method not allowed in the browser: це нормально. URL приймає лише запити від ePay.bg.

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

Покупець бачить This order has nothing to pay.: сума замовлення дорівнює нулю, тому надсилати до ePay.bg нічого.

Замовлення має статус On Hold після оплати: прочитайте примітки на вкладці VibeFox ePay.bg Gateway (див. Статуси замовлень), перевірте платіж у панелі мерчанта ePay.bg, а потім виконайте замовлення або поверніть платіж там.

Префікс рахунку було змінено під час збереження: префікс може містити лише цифри, до 10. Інші символи видаляються.

Для розробників: перед надсиланням форми оплати до ePay.bg розширення запускає подію OpenCart epay_bp_form_fields з полями форми та замовленням, наприклад щоб використати пряму сторінку оплати карткою (PAGE=credit_paydirect); через неї не можна змінити підписані дані та контрольну суму.

Видалення

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

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

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