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

Вимоги

PrestaShop: 8.0–9.x.

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

Валюта магазину: HUF, EUR або USD. SimplePay не приймає інші валюти, і спосіб оплати не пропонується для кошиків у них.

Облікові записи мерчанта SimplePay: SimplePay надає окремий обліковий запис мерчанта для кожної валюти, а також окремі облікові записи для робочого і тестового (sandbox) режимів. Для кожного облікового запису потрібні його MERCHANT і SECRET KEY з панелі мерчанта SimplePay (admin.simplepay.hu для робочого режиму, sandbox.simplepay.hu для тестового), account > Technical data. Якщо ви продаєте лише в HUF, достатньо облікового запису HUF. Жодні інші ключі не потрібні.

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

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

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

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

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

4. Введіть MERCHANT і SECRET KEY ваших облікових записів SimplePay для кожної валюти, у якій ви продаєте: тестові облікові записи (sandbox) для перевірки та робочі облікові записи для реальних платежів (див. розділ «Налаштування»).

5. Скопіюйте IPN URL, що відображається на сторінці Configure, в кожен обліковий запис мерчанта (робочий і тестовий) на панелі мерчанта SimplePay.

6. Увімкніть Enable/Disable і натисніть Save. Перевірте платіж із увімкненим Sandbox mode, а потім вимкніть Sandbox mode, щоб приймати реальні платежі.

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

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

Усі налаштування розташовані на сторінці модуля: Modules > Module Manager > VibeFox SimplePay Gateway > Configure. Кожен розділ має власну кнопку Save, яка зберігає всю сторінку. Над полями сторінка попереджає, якщо основна валюта магазину не підтримується SimplePay або для неї немає облікового запису мерчанта в поточному режимі. В обох випадках спосіб оплати не пропонується для кошиків у цій валюті. Поки тестовий режим увімкнено, сторінка показує Sandbox mode is on: payments go to the SimplePay sandbox, no real money is charged.

SimplePay (OTP)

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

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

Description: текст, який відображається під способом оплати під час оформлення замовлення. За замовчуванням: Pay securely with your credit or debit card via SimplePay. Угорські мерчанти можуть вказати тут декларацію про передачу даних SimplePay (з посиланням).

Sandbox mode: використовує тестове середовище SimplePay (sandbox) для тестових платежів з тестовими обліковими записами. Перемикається одночасно адреса API та облікові записи мерчанта. Реальні кошти не списуються. За замовчуванням: увімкнено. Вимкніть, щоб приймати реальні платежі з робочими обліковими записами. Поки режим увімкнено, покупці бачать під способом оплати Sandbox mode: no real payment is taken. Замовлення, створені в тестовому режимі, завжди повертаються в тестовому режимі.

Робочі облікові записи мерчанта

Облікові записи, які використовуються, коли Sandbox mode вимкнено. Заповніть облікові записи для валют, у яких продає ваш магазин. Значення MERCHANT і SECRET KEY містяться на панелі мерчанта SimplePay (admin.simplepay.hu), account > Technical data. Обліковий запис використовується лише тоді, коли заповнено обидва поля.

HUF account — Merchant ID: MERCHANT вашого робочого облікового запису HUF.

HUF account — Secret key: SECRET KEY вашого робочого облікового запису HUF.

EUR account — Merchant ID і EUR account — Secret key: те саме для вашого робочого облікового запису EUR.

USD account — Merchant ID і USD account — Secret key: те саме для вашого робочого облікового запису USD.

Тестові облікові записи мерчанта

Облікові записи, які використовуються, коли Sandbox mode увімкнено. Поля такі самі, як для робочих облікових записів: HUF account — Merchant ID, HUF account — Secret key і такі самі пари для EUR та USD. Значення беріть з тестової панелі мерчанта SimplePay (sandbox.simplepay.hu), account > Technical data.

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

IPN URL

IPN — це повідомлення, яке SimplePay надсилає до вашого магазину, коли змінюється статус платежу. Саме так зазвичай створюється замовлення. У розділі показано IPN URL вашого магазину. З дружніми URL він має такий вигляд: https://your-shop/module/wcp_simplepay_gateway/ipn, можливо, з кодом мови, наприклад /en/. Вкажіть цю URL для кожного облікового запису мерчанта, робочого і тестового, на панелі мерчанта SimplePay. Копіюйте URL точно так, як його показують налаштування, бо перенаправлений IPN губиться.

IPN має бути підписаний SECRET KEY облікового запису мерчанта, який він вказує, у тому режимі (тестовому або робочому), у якому почався платіж. IPN без дійсного підпису відхиляються. Модуль підтверджує кожен дійсний IPN для SimplePay у підписаній формі, яку вимагає SimplePay. Використовуються такі статуси IPN:

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

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

Замовлення

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

Платіж на суму або у валюті, відмінних від замовлення, завжди переходить у статус SimplePay payment on hold.

Додатково

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

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

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

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

На етапі оплати покупець обирає спосіб оплати (за замовчуванням SimplePay (Card Payment)) і бачить примітку You will be redirected to the SimplePay payment page to pay by card. Після підтвердження модуль запускає платіж карткою SimplePay на суму кошика у валюті кошика, через обліковий запис мерчанта цієї валюти в поточному режимі, і надсилає покупця на платіжну сторінку SimplePay. E-mail покупця та, якщо він повністю заповнений, адреса для рахунку передаються до SimplePay. Платіжна сторінка використовує мову магазину, якщо SimplePay її підтримує, інакше англійську. Розпочатий платіж можна сплатити протягом 30 хвилин. На цьому етапі замовлення ще не існує.

Після успішного платежу покупець повертається до вашого магазину. Саме лише повернення ніколи не оплачує замовлення: модуль запитує у SimplePay статус транзакції підписаним запитом, тож замовлення створюється, навіть якщо IPN прийшов із запізненням. Замовлення позначається оплаченим лише після підтвердження SimplePay. Тоді покупець бачить стандартну сторінку підтвердження замовлення з Successful transaction. SimplePay transaction ID: та ID. Якщо SimplePay ще не підтвердив платіж, сторінка Payment confirmation показує Your payment is being confirmed by SimplePay. SimplePay transaction ID: з ID і кнопку Check again; IPN створить замовлення, щойно він надійде.

Якщо платіж не вдався, скасовано або минув час, покупець повертається до оформлення замовлення з повідомленням SimplePay та ID транзакції, наприклад Cancelled payment. You cancelled the payment або Timeout. The time allowed to complete the payment has expired. У разі невдалого платежу покупцеві пропонують перевірити введені дані та звернутися до банку, що випустив картку. Кошик зберігається, і покупець може спробувати знову. Кожна нова спроба отримує власний референс SimplePay: PS, номер кошика та номер спроби, наприклад PS123-1, PS123-2.

Якщо SimplePay не може розпочати платіж, покупець бачить The SimplePay payment could not be started. Please try again or choose another payment method. Якщо для валюти кошика немає облікового запису мерчанта, повідомлення таке: SimplePay is not available for the currency of this order. Please choose another payment method. Технічна причина записується в журнал.

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

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

Замовлення та повернення

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

Замовлення ще немає: покупця було відправлено до SimplePay, і він не сплатив, платіж не вдався, було скасовано або минув час, або SimplePay ще не підтвердив платіж. Існує лише кошик.

Payment accepted or Delivered: платіж підтверджено. Статус відповідає Order Status After Payment. Платіж записується з ID транзакції SimplePay, а примітка показує ID транзакції та те, чи підтвердив його IPN або запит статусу.

SimplePay payment on hold: сума або валюта кошика були змінені після початку оплати, тож сплачена сума відрізняється від замовлення. Платіж не записується. Примітка показує обидві суми. Перевірте замовлення та виконайте його або поверніть платіж на панелі мерчанта SimplePay. Якщо згодом інша спроба того самого кошика буде оплачена на правильну суму, замовлення переходить у оплачений статус.

Refunded: платіж повністю повернено через модуль.

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

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

На сторінці замовлення відображається блок SimplePay payment з ID транзакції, референсом замовлення (orderRef), обліковим записом мерчанта та режимом, статусом SimplePay, сплаченою та поверненою сумами, позначкою Sandbox для тестових платежів, спробами оплати кошика (якщо їх було більше однієї), історією повернень і SimplePay notes замовлення.

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

У блоці SimplePay payment введіть суму (підставляється сума, яку ще не повернуто), за бажанням причину, і натисніть Refund via SimplePay (OTP). Підтвердьте запитання Refund this amount via SimplePay? This cannot be undone. Підтримуються повні та часткові повернення. Потрібне право редагувати замовлення; доступ до сторінок модулів не потрібен. Повернення в HUF мають бути цілими форинтами. Повернення надсилається для транзакції SimplePay, яка оплатила замовлення, з її сумою та валютою, через обліковий запис мерчанта і в режимі (тестовому або робочому) цього платежу, тож цей обліковий запис має залишатися в налаштуваннях. Якщо SimplePay не приймає повернення, блок показує помилку і повернення не записується. Успішне повернення додається до історії повернень і приміток із ID транзакції повернення SimplePay та причиною, якщо ви її вказали. Повне повернення переводить замовлення в статус Refunded. Часткове повернення статус не змінює. Замовлення на утриманні після розбіжності сум не можна повернути з блоку: поверніть його на панелі мерчанта SimplePay.

Модуль не створює кредитових нот. Стандартні кнопки повернення PrestaShop на сторінці замовлення не повертають кошти через SimplePay. Повернення, зроблені на панелі мерчанта SimplePay, не синхронізуються з PrestaShop. Фіксуйте їх вручну.

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

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

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

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

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

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

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

SimplePay не з'являється під час оформлення замовлення: перевірте, що ліцензія активна, Enable/Disable увімкнено, валюта кошика — HUF, EUR або USD, і для цієї валюти заповнено Merchant ID та Secret key у поточному режимі: тестові облікові записи, поки Sandbox mode увімкнено, робочі — поки вимкнено. У Payment > Preferences перевірте, що модуль дозволено для валюти кошика, країни покупця та групи покупця.

Платіж пройшов, але замовлення не створено: IPN не дійшов до магазину. На панелі мерчанта SimplePay перевірте IPN URL облікового запису мерчанта, який ви використовуєте (робочого або тестового, залежно від валюти кошика). Вона має точно збігатися з URL, показаною в налаштуваннях, а ваш сервер має бути доступним з інтернету. Замовлення також створюється, коли покупець повертається до магазину після оплати.

IPN відповідає Invalid signature: IPN вказує обліковий запис мерчанта, якого немає в налаштуваннях, його Secret key невірний, або він підписаний обліковим записом іншого режиму, ніж платіж. Введіть MERCHANT і SECRET KEY точно так, як їх показує панель мерчанта SimplePay. SimplePay повторює непідтверджені IPN.

IPN відповідає Order not found або Unknown transaction: IPN стосується платежу, який цей магазин не розпочинав. Нічого не змінюється.

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

Покупець бачить The SimplePay payment could not be started: перегляньте поле Log на сторінці модуля. Невірний секретний ключ дає Invalid response signature from SimplePay. Check the secret key of the merchant account. Помилки SimplePay записуються в журнал з їх кодами.

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

Замовлення переходить у SimplePay payment on hold після оплати: прочитайте примітки в блоці SimplePay payment. Сума або валюта кошика були змінені після початку оплати. Виконайте замовлення або поверніть платіж на панелі мерчанта SimplePay.

Повернення не виконується: прочитайте повідомлення в блоці. SimplePay refunds in HUF must be whole amounts. означає, що сума в HUF мала десяткові знаки. Якщо повідомлення каже, що обліковий запис мерчанта цього платежу не налаштовано, введіть знову обліковий запис (валюту та режим), з яким було здійснено платіж. Якщо SimplePay повернув іншу суму, повідомлення просить перевірити повернення на панелі SimplePay.

Видалення

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

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