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

Вимоги

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

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

Валюта: новий тайванський долар (TWD). ECPay приймає оплату лише в TWD, тому спосіб оплати показується лише тоді, коли кошик покупця в TWD. Додайте TWD у розділі International > Localization > Currencies, якщо її немає у вашому магазині. Суми надсилаються в цілих TWD, оскільки ECPay не приймає десяткові значення: підсумки кошика округлюються до найближчого долара. Для цін у TWD використовуйте 0 знаків після коми, щоб уникнути округлення.

Обліковий запис ECPay: для реальних платежів потрібні MerchantID, HashKey і HashIV вашого облікового запису мерчанта ECPay з бек-офісу мерчанта ECPay (vendor.ecpay.com.tw). Для тестування обліковий запис ECPay не потрібен.

Доступ до сайту: ваш магазин має бути доступний з інтернету за протоколом HTTP/HTTPS на порту 80/443, щоб ECPay міг надсилати повідомлення про платежі. Брандмауер або базова автентифікація перед сайтом їх блокують.

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

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

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

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

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

4. Увімкніть Enable/Disable, оберіть способи оплати та залиште Test Mode увімкненим для перших тестів. Натисніть Save.

5. Для реальних платежів введіть Merchant ID, Hash Key і Hash IV (див. розділ Конфігурація), вимкніть Test Mode і натисніть Save.

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

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

Усі налаштування розташовані на сторінці модуля: Modules > Module Manager > VibeFox ECPay Payment Gateway > Configure. Кожен розділ має власну кнопку Save, яка зберігає всю сторінку. Над полями сторінка показує помилку, якщо в магазині немає валюти TWD (тоді ECPay не відображається на етапі оформлення замовлення), або попередження, якщо валюта за замовчуванням не TWD (тоді ECPay показується лише покупцям, які платять у TWD). Вона показує помилку, якщо в бойовому режимі не заповнено MerchantID, HashKey і HashIV. Поки тестовий режим увімкнено, вона попереджає, що платежі йдуть до пісочниці ECPay з публічним тестовим мерчантом 3002607, що гроші не списуються і що кожен, хто знає публічні ключі пісочниці, може підтвердити тестові замовлення, тож тестовий режим має бути вимкнений до прийняття реальних замовлень.

ECPay (綠界)

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

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

Description: текст під способом оплати на етапі оформлення замовлення. За замовчуванням: Pay securely via ECPay (Credit Card, ATM, CVS, Barcode).

Обліковий запис ECPay

Знайдіть ваші MerchantID, HashKey і HashIV у бек-офісі мерчанта ECPay (vendor.ecpay.com.tw) у розділі System development management > System integration settings (系統開發管理 > 系統介接設定).

Test Mode: надсилає платежі до пісочниці ECPay (payment-stage.ecpay.com.tw) з публічним тестовим мерчантом ECPay 3002607. Реальні гроші не списуються. Облікові дані нижче використовуються лише тоді, коли тестовий режим вимкнено. За замовчуванням: увімкнено. Поки він увімкнений, покупці бачать під способом оплати напис TEST MODE — ECPay sandbox, no real money is charged.

Merchant ID: ваш Merchant ID ECPay (продакшн). У тестовому режимі ігнорується.

Hash Key: ваш Hash Key ECPay (продакшн). У тестовому режимі ігнорується.

Hash IV: ваш Hash IV ECPay (продакшн). У тестовому режимі ігнорується.

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

Clear saved secrets: відмітьте Hash Key або Hash IV і натисніть Save, щоб видалити його. Порожнє поле зберігає збережене значення.

Параметри оплати

Enabled Payment Methods: способи оплати, які пропонуються покупцям. Якщо їх більше одного, покупець обирає на етапі оформлення замовлення. Замовлення ATM, CVS і штрих-коду залишаються в статусі Awaiting ECPay payment, доки покупець не сплатить. Має бути обраний принаймні один спосіб; якщо не обрано жодного, вмикається Credit Card, і сторінка повідомляє про це. За замовчуванням: Credit Card.

Default Payment Method: спосіб, вибраний за замовчуванням. Він має бути одним з увімкнених способів; інакше використовується перший увімкнений спосіб. За замовчуванням: Credit Card.

Order Prefix: префікс номера транзакції ECPay (MerchantTradeNo), до 5 літер або цифр. Інші символи видаляються під час збереження, з повідомленням. Корисно, коли кілька магазинів використовують один обліковий запис ECPay: дайте кожному магазину власний префікс. За замовчуванням: EC.

Повідомлення про платежі

ECPay передає результати платежів до вашого магазину. Цей розділ показує Notification URL. З дружніми URL вона виглядає так: https://your-shop/module/wcp_ecpay_payment_gateway/notify, можливо, з кодом мови, наприклад /en/. URL надсилається з кожним платежем, тож у ECPay нічого налаштовувати не потрібно, але він має бути доступний з інтернету на порту 80/443, без брандмауера чи базової автентифікації перед ним. Режим обслуговування та обмеження за країною вашого магазину його не блокують.

Кожне повідомлення перевіряється за підписом CheckMacValue ключами того середовища (тестового чи бойового), у якому було розпочато платіж, а також за MerchantID цього платежу. Повідомлення без дійсного підпису відхиляються, і ECPay надсилає їх повторно. Без повідомлення замовлення не створюється; перевірте платіж у бек-офісі ECPay.

Додатково

Enable Logging: записує ID замовлень, номери транзакцій, суми та коди відповідей ECPay у logs/ecpay_p_debug.log.php у папці модуля. Цей файл не можна відкрити з веб-браузера. Ключі та дані покупців не записуються. Помилки завжди записуються, навіть коли цей перемикач вимкнено. За замовчуванням: вимкнено.

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

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

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

На кроці оплати покупець обирає спосіб оплати (за замовчуванням ECPay (綠界)). Якщо увімкнено кілька способів, покупець також обирає Credit Card, ATM (Virtual Account), CVS (Convenience Store) або Barcode у полі Payment Method.

Після підтвердження покупець бачить Redirecting to ECPay for payment. Please wait... і його перенаправляють на сторінку оплати ECPay, з кнопкою Proceed to ECPay на випадок, якщо перенаправлення не почалося. Сума кошика надсилається в цілих TWD разом з назвами та кількістю товарів. Сторінка ECPay відкривається традиційною китайською для тайванської та гонконгської мов, спрощеною китайською, корейською або японською для цих мов і англійською для всіх інших, згідно з мовою магазину покупця. На цьому етапі замовлення ще не існує.

Замовлення створюється лише після того, як ECPay підтвердить його підписаним повідомленням сервера. Коли покупець натискає посилання повернення до магазину на сторінці ECPay і замовлення вже існує, відкривається стандартна сторінка підтвердження замовлення. Вона показує Your ECPay payment has been received. для оплаченого замовлення, Your ECPay payment was received and is being reviewed by the store. для замовлення на утриманні та інструкції з оплати для замовлення ATM, CVS або зі штрих-кодом, що очікує оплати. Якщо повідомлення ще не надійшло, сторінка Payment confirmation показує We have not received a payment confirmation from ECPay for this order yet. Your order will be created as soon as ECPay confirms the payment. з кнопками Check again і Back to checkout. Якщо ECPay повідомив про невдалу оплату, покупець повертається до оформлення замовлення з повідомленням The payment was not completed. You can try again or choose another payment method. Кошик зберігається.

Для ATM, CVS і штрих-коду покупець спочатку отримує платіжні реквізити. Замовлення створюється в статусі Awaiting ECPay payment, а код банку та віртуальний рахунок, код оплати в магазині біля дому або штрих-коди, сума та дата Pay before показуються в розділі ECPay payment instructions на сторінці підтвердження замовлення та в деталях замовлення в особистому кабінеті покупця. Коли покупець сплачує, ECPay надсилає ще одне повідомлення, і замовлення позначається оплаченим. Інструкції з оплати не додаються до листів PrestaShop.

Кожна спроба створює новий номер транзакції ECPay, бо ECPay відхиляє повторно використані номери. Тому повторні спроби після невдалої оплати працюють, а якщо покупець повертається в браузері на сторінку перенаправлення, починається нова спроба. Кошик може мати до 30 спроб оплати. Щойно в кошика з'являється замовлення, його більше не можна оплатити через оформлення замовлення; замовлення ATM або CVS, що очікує оплати, сплачується за вже виданими реквізитами.

Якщо оплату не вдалося розпочати, покупець залишається на етапі оформлення замовлення з коротким повідомленням, наприклад The order total is too small for ECPay., коли сума після округлення менша за 1 TWD. Ліміти сум ECPay для кожного способу перевіряються на сторінці ECPay, а не на етапі оформлення замовлення.

Модуль приймає лише одноразові платежі на сторінці ECPay. Він не підтримує повернення коштів з PrestaShop, збережені картки, підписки чи періодичні платежі (定期定額), розстрочку, Apple Pay, TWQR, WeChat Pay, BNPL, WebATM, електронні рахунки-фактури чи логістику, а також запит статусу на стороні сервера: якщо ваш магазин не може отримати повідомлення, перевірте платіж у бек-офісі ECPay.

Замовлення

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

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

Awaiting ECPay payment: покупець обрав ATM, CVS або штрих-код і отримав платіжні реквізити. Нотатка показує код банку та віртуальний рахунок, код оплати або штрих-коди та кінцевий термін.

Payment accepted: оплату підтверджено. Платіж записується з TradeNo ECPay як ID транзакції, а нотатка показує TradeNo, тип платежу, суму та номер транзакції (з позначкою тестового режиму для платежів пісочниці).

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

Payment error: ECPay повідомив, що остання оплата ATM, CVS або штрих-кодом для замовлення, що очікує оплати, не вдалася. Нотатка показує код відповіді та повідомлення ECPay.

Повторні повідомлення ігноруються. Оплачене, повернуте або скасоване замовлення ніколи не відкривається знову через пізню невдачу. Другий платіж за вже оплачене замовлення, наприклад з двох вкладок браузера, записується в нотатку один раз, щоб ви могли повернути його в бек-офісі ECPay. Симульовані платежі, розпочаті з бек-офісу ECPay, лише позначаються і ніколи не позначають замовлення оплаченим, бо ECPay за них гроші не списує.

Блок платежів ECPay

Сторінка замовлення показує блок ECPay payment з усіма спробами оплати замовлення: MerchantTradeNo з позначкою Test mode для спроб пісочниці, спосіб оплати, суму в TWD, статус, TradeNo ECPay, тип платежу та дату, а також код відповіді ECPay. Нижче розташовані ECPay notes замовлення. Для замовлення в статусі ECPay payment on hold блок нагадує звірити його з бек-офісом ECPay.

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

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

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

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

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

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

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

ECPay не відображається на етапі оформлення замовлення: перевірте, що ліцензія активна, Enable/Disable увімкнено, кошик покупця в TWD і, у бойовому режимі, заповнені Merchant ID, Hash Key і Hash IV. Сторінка налаштувань показує повідомлення в кожному з цих випадків. У розділі Payment > Preferences перевірте, що модуль дозволено для TWD, для країни покупця та для групи покупця.

Платіж пройшов, але замовлення не створено: повідомлення ECPay не дійшло до вашого магазину (сайт недоступний, брандмауер, базова автентифікація). ECPay повторює спроби кілька разів. Транзакцію також можна перевірити в бек-офісі ECPay. Увімкніть Enable Logging, щоб побачити повідомлення, які отримав модуль; відхилені повідомлення в будь-якому разі записуються як помилки.

Повідомлення відповідає 0|CheckMacValue verification failed: Hash Key або Hash IV не відповідають вашому обліковому запису ECPay, або платіж розпочато в іншому середовищі. Скопіюйте їх заново з бек-офісу ECPay.

Повідомлення відповідає 0|MerchantID mismatch: повідомлення належить іншому мерчанту ECPay, ніж той, з яким розпочато платіж.

Повідомлення відповідає 0|Order not found: номер транзакції видано не цим магазином, наприклад, коли кілька магазинів використовують один обліковий запис ECPay. Дайте кожному магазину власний Order Prefix.

Повідомлення відповідає 0|Retry: кошик у цей момент оброблялося іншим повідомленням, або замовлення не вдалося створити (наприклад, модуль вимкнено). ECPay надішле повідомлення повторно. Увімкніть Enable Logging, щоб побачити причину.

URL повідомлення показує 0|Method not allowed in the browser: це нормально. URL приймає лише запити від ECPay.

Покупець бачить «The order total is too small for ECPay.»: сума кошика після округлення менша за 1 TWD і не може бути сплачена через ECPay.

Покупець бачить «Too many payment attempts for this order»: у кошика 30 спроб оплати. Попросіть покупця почати новий кошик.

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

Розробникам: хук actionEcpayPRequestParams дозволяє іншому модулю змінити параметри, що надсилаються до ECPay; мерчант, номер транзакції та суму ним змінити не можна.

Видалення

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

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