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

Вимоги

PrestaShop: від 8.0 до 9.x.

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

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

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

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

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

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

2. Після завершення завантаження натисніть Configure або пізніше знайдіть VibeFox ePay.bg Gateway у списку модулів і натисніть Configure.

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

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

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

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

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

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

Усі налаштування розміщено на сторінці модуля: Modules > Module Manager > VibeFox ePay.bg Gateway > Configure. Кожна кнопка Save зберігає всю сторінку. Над полями сторінка показує помилку, якщо основна валюта магазину не 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: вмикає тестовий режим. Покупців перенаправляють у демо-середовище 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.

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

Clear saved secret keys: позначте ключ і натисніть Save, щоб видалити його. Порожнє поле зберігає збережене значення.

Payment notifications (IPN)

Сповіщення повідомляє вашому магазину, що платіжний запит оплачено, відхилено або він прострочений. У полі Notification URL показано URL, який потрібно вказати як URL for receiving notifications у мерчант-профілі ePay.bg — робочому і тестовому. Якщо увімкнено зрозумілі URL, він має вигляд https://your-shop/module/wcp_epaybg_gateway/notify, можливо з кодом мови, наприклад /en/. Скопіюйте URL точно так, як його показують налаштування. Замовлення створюються лише цими підписаними сповіщеннями; повернення покупця до магазину не створює і не оплачує замовлення.

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

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

Payment request

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: статус замовлення, що встановлюється після успішної оплати.

Advanced

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

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

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

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

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

Після оплати покупець повертається до вашого магазину. Замовлення створюється лише тоді, коли надходить підписане сповіщення ePay.bg. Якщо воно вже надійшло, покупець бачить стандартну сторінку підтвердження замовлення. Якщо ні, сторінка Payment confirmation показує Thank you. Your payment is being confirmed by ePay.bg — your order will be created as soon as ePay.bg confirms it, and you will receive an e-mail. з кнопками 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. Кошик зберігається. Нова спроба для того самого кошика використовує той самий номер рахунку.

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

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

Модуль приймає лише разові платежі через ePay.bg. Немає повернень із PrestaShop, збережених карток, підписок або регулярних платежів, а також кодів оплати готівкою EasyPay чи B-Pay.

Замовлення

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

No order yet: покупця перенаправили на ePay.bg, і він не сплатив, сповіщення ще не надійшло або ePay.bg повідомив, що запит відхилено чи прострочено. Існує лише кошик.

Payment accepted, Delivered or ePay.bg payment on hold: платіж підтверджено. Статус відповідає Order Status After Payment. Платіж записується з STAN як ID транзакції (або номером рахунку, якщо STAN немає), а примітка показує номер рахунку, дату платежу, STAN і код BORICA.

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

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

Блок платежу ePay.bg

На сторінці замовлення показано блок ePay.bg payment з рахунком, запитаними сумою та валютою, результатом сповіщення, датою платежу, STAN, кодом BORICA, позначкою Test mode для тестових платежів і ePay.bg notes замовлення.

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

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

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

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

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

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

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

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

Платіж пройшов, але замовлення не створено: замовлення створюється лише сповіщенням 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.

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

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

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

Видалення

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

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