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

Вимоги

WordPress: 6.0 або новіша версія.

WooCommerce: 7.0 або новіша, установлений і активний.

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

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

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

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

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

1. У WordPress відкрийте Plugins > Add New > Upload Plugin, виберіть ZIP-файл плагіна та натисніть Install Now. Також можна завантажити папку wcp_epaybg_gateway до /wp-content/plugins/ через FTP.

2. Натисніть Activate. WooCommerce має бути активним.

3. Відкрийте налаштування: WooCommerce > Settings > Payments > ePay.bg > Manage, або натисніть Settings під назвою плагіна на сторінці плагінів.

4. Введіть ліцензійний ключ VibeFox у блоці ліцензії вгорі сторінки та натисніть Activate.

5. Введіть тестові та/або робочі MIN і секретний ключ (див. розділ «Налаштування»).

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

7. Увімкніть Enable/Disable. Зробіть тестове замовлення в тестовому режимі, потім зніміть позначку Test Mode.

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

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

Загальні

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

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

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

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

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

Test Mode: Enable test mode (use demo.epay.bg and the test credentials). Коли режим увімкнено, покупців перенаправляють до демосередовища ePay.bg, а запити підписуються тестовими обліковими даними. За замовчуванням: увімкнено.

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.

Якщо ви оновлюєтеся з версії 1.0, єдиний набір облікових даних цієї версії переноситься до тестових полів, якщо був увімкнений тестовий режим.

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

Сповіщення повідомляє вашому магазину, що платіжний запит оплачено, відхилено або строк його дії завершився. У цьому розділі показано URL сповіщень. Він має такий вигляд: https://your-site/wc-api/epaybg_payment_callback/. Укажіть його як URL for receiving notifications у мерчант-профілі ePay.bg — робочому й тестовому. Замовлення позначаються оплаченими лише цими підписаними сповіщеннями; повернення покупця до магазину не позначає замовлення оплаченим.

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

PAID: покупець сплатив. Замовлення позначається оплаченим.

DENIED: платіж відхилено. Неоплачене замовлення скасовується.

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

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

Платіжний запит

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

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

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

Order Status After Payment: статус замовлення, який встановлюється після успішної оплати. Статус встановлюється одразу, без повторної зміни статусу.

Default (WooCommerce decides): «Обробляється» або «Виконано» для замовлень, що містять лише віртуальні товари для завантаження (за замовчуванням).

Processing: кожне оплачене замовлення отримує статус «Обробляється».

Completed: кожне оплачене замовлення отримує статус «Виконано».

On Hold: кожне оплачене замовлення очікує вашої ручної перевірки.

Додатково

Logging: Enable logging записує платіжні запити та сповіщення до WooCommerce > Status > Logs, джерело wcp_epaybg_gateway, без секретних ключів і даних картки. За замовчуванням: вимкнено.

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

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

Покупець вибирає спосіб оплати (за замовчуванням ePay.bg) і оформлює замовлення. Він бачить повідомлення Redirecting to ePay.bg for payment... і перенаправляється на ePay.bg з підписаним платіжним запитом на суму замовлення у валюті замовлення, з номером рахунку та строком дії. На сторінці також є кнопка Pay via ePay.bg на випадок, якщо перенаправлення не почнеться, і кнопка Cancel order. На ePay.bg покупець сплачує банківською карткою або за допомогою облікового запису ePay.bg.

Після оплати покупець повертається на сторінку «Замовлення прийнято» вашого магазину. Замовлення позначається оплаченим лише тоді, коли надходить підписане сповіщення ePay.bg. Кошик очищується лише на сторінці «Замовлення прийнято».

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

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

Спосіб оплати працює в класичному оформленні замовлення, у блоці Checkout і на сторінці Pay for order. Він сумісний із високопродуктивним сховищем замовлень WooCommerce (HPOS).

Плагін приймає лише разові платежі на ePay.bg. У ньому немає повернень коштів із WooCommerce, збережених карток і токенізації, підписок і регулярних платежів, кодів оплати готівкою EasyPay та B-Pay.

Замовлення

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

Pending payment: покупця перенаправлено на ePay.bg, і він ще не сплатив, або сповіщення ще не надійшло. У нотатці до замовлення зазначено Awaiting ePay.bg payment.

Processing, Completed or On Hold: платіж підтверджено. Статус визначається налаштуванням Order Status After Payment. У нотатці до замовлення вказано номер рахунку, дату платежу, STAN і код BORICA. ID транзакції — це STAN (або номер рахунку, якщо STAN немає).

On hold after payment: платіж надійшов, але не за те, що зазначено в замовленні зараз: суму або валюту змінили після платіжного запиту, запит було зроблено в іншому режимі або шлюз пізніше перемкнули між тестовим і робочим режимом, змінили спосіб оплати замовлення, або замовлення було скасоване раніше. Причину пояснено в нотатці до замовлення. Перевірте платіж у мерчант-панелі ePay.bg і завершіть замовлення чи поверніть кошти вручну.

Cancelled: ePay.bg повідомив, що платіжний запит відхилено або строк його дії завершився, або покупець скасував оплату на ePay.bg. WooCommerce повертає залишки на склад. Скасоване замовлення не можна оплатити повторно, оскільки номер рахунку ePay.bg — це префікс плюс ID замовлення. Покупець оформлює нове замовлення.

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

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

Повернення коштів із WooCommerce недоступні, оскільки в WEB API ePay.bg немає виклику повернення. Поверніть кошти в мерчант-панелі ePay.bg і вручну зафіксуйте повернення в WooCommerce.

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

Плагін працює з ліцензійним ключем VibeFox з vibefox.net. Блок ліцензії розташований угорі сторінки WooCommerce > Settings > Payments > ePay.bg. Вставте ключ у поле License key і натисніть Activate. У блоці показано статус, наприклад дату, до якої діє ліцензія, і ваш домен. Кнопка Check now повторно перевіряє статус, Change key дає змогу ввести інший ключ, а Remove key видаляє його з цього сайту. Посилання Manage licenses and domains in your account відкриває ваш обліковий запис на vibefox.net.

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

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

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

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

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

Платіж пройшов, але замовлення залишається в стані «Очікує на оплату»: замовлення позначається оплаченим лише за сповіщенням ePay.bg. Перевірте, що URL сповіщень указано в мерчант-профілі ePay.bg того режиму, який ви використовуєте (демо чи робочий), і що секретний ключ активного режиму правильний. Увімкніть Logging і подивіться WooCommerce > Status > Logs, джерело wcp_epaybg_gateway.

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

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

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

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

Після оплати замовлення має стан «На утриманні»: прочитайте нотатку до замовлення. Сума або валюта змінилася після платіжного запиту, запит було зроблено в іншому режимі або режим пізніше перемкнули, змінився спосіб оплати або замовлення було скасоване. Перевірте платіж у мерчант-панелі ePay.bg.

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

Блок ліцензії показує помилку: дотримуйтесь повідомлення в блоці. Наприклад, якщо ключ уже використовується на іншому домені, звільніть слот у своєму обліковому записі на vibefox.net і натисніть Check now. Якщо адреса сайту змінилася, натисніть Check now, щоб активувати ключ для нового домену. Якщо ліцензійний сервер недоступний, плагін продовжує працювати за останнім відомим статусом.

Для розробників: у readme згадано фільтр epay_bp_form_fields, наприклад для використання прямої сторінки оплати карткою (PAGE=credit_paydirect).

Видалення

Деактивація плагіна зберігає всі дані. Щоб видалити його, деактивуйте й видаліть плагін на сторінці Plugins. Ліцензійний ключ і статус ліцензії цього плагіна видаляються завжди. Налаштування шлюзу, дані ePay.bg, збережені в замовленнях, і журнали видаляються лише тоді, коли було ввімкнено Delete Data on Uninstall. В іншому разі вони залишаються для подальшого перевстановлення. Наявні замовлення зберігають свої нотатки про оплату та ID транзакцій.

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