VibeFox Pin Payments for PrestaShop — Допомога

Вимоги

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

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

Обліковий запис Pin Payments: обліковий запис мерчанта Pin Payments (для компаній в Австралії або Новій Зеландії; покупці можуть платити з будь-якої країни). Потрібні його публічний (publishable) і секретний ключі: робочі та, для тестування, ключі тестового середовища. Секрет вебхука не потрібен: модуль не використовує вебхуки. Дані картки надсилаються з браузера покупця безпосередньо до Pin Payments через Pin.js і ніколи не потрапляють до вашого магазину, тому магазин підпадає під PCI SAQ A-EP.

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

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

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

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

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

4. У панелі Pin Payments відкрийте Account > API Keys і скопіюйте тестові ключі в Test publishable key та Test secret key. Залиште увімкненим Test mode, увімкніть Enable/Disable і натисніть Save.

5. Оформіть тестове замовлення тестовою карткою Pin Payments. Коли все працює, введіть робочі ключі, вимкніть Test mode і збережіть.

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

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

Усі налаштування розташовані на сторінці модуля: Modules > Module Manager > VibeFox Pin Payments Gateway > Configure. Кожен розділ має власну кнопку Save, яка зберігає всю сторінку. Над полями сторінка показує попередження, поки ввімкнено тестовий режим, помилку, якщо публічний або секретний ключ поточного режиму порожній, і помилку, якщо Pin Payments не підтримує валюту за замовчуванням магазину (зі списком підтримуваних валют). Без обох ключів поточного режиму спосіб оплати приховано на сторінці оформлення замовлення. Порожнє поле Title не зберігається: сторінка показує Enter a title for the payment method.

Pin Payments

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

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

Description: текст під способом оплати на сторінці оформлення замовлення. За замовчуванням: Pay with your credit card via Pin Payments.

API-ключі

Ключі знаходяться в панелі Pin Payments у розділі Account > API Keys. Тестові ключі працюють лише з тестовим API, робочі — лише з робочим API. Публічний ключ використовує Pin.js у браузері покупця. Секретний ключ ніколи не залишає ваш сервер.

Test mode: використовує тестове середовище Pin Payments (test-api.pinpayments.com) і тестові ключі. Реальні списання не виконуються, а покупці бачать під способом оплати TEST MODE — no real charges will be made. Коли режим вимкнено, використовуються робочий API і робочі ключі. За замовчуванням: увімкнено.

Test publishable key: публічний ключ вашого тестового облікового запису Pin Payments.

Test secret key: секретний ключ вашого тестового облікового запису Pin Payments.

Live publishable key: публічний ключ вашого робочого облікового запису Pin Payments.

Live secret key: секретний ключ вашого робочого облікового запису Pin Payments.

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

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

Додатково

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

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

Delete data on uninstall: якщо увімкнено, під час видалення модуля видаляються налаштування шлюзу та журнал. Платіжні дані замовлень (списання та повернення) і статус замовлення Pin Payments payment on hold завжди зберігаються. За замовчуванням: вимкнено.

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

Спосіб оплати показується, коли він увімкнений, задано обидва ключі поточного режиму, валюта кошика входить до 14 підтримуваних (AUD, USD, NZD, SGD, EUR, GBP, CAD, HKD, JPY, MYR, THB, PHP, ZAR, IDR), і модулю дозволено працювати з кошиком у Payment > Preferences.

На етапі оплати покупець обирає спосіб оплати (за замовчуванням Credit card (Pin Payments), з іконками Visa, Mastercard та American Express) і заповнює Card number, Expiry (MM / YY), CVC та Name on card. Перед надсиланням форма перевіряє довжину номера картки, місяць і рік закінчення терміну дії, CVC з 3 або 4 цифр та ім'я.

Коли покупець оформлює замовлення, Pin.js надсилає дані картки та платіжну адресу кошика з браузера безпосередньо до Pin Payments і отримує одноразовий токен картки. Лише цей токен надсилається до вашого магазину. Далі модуль створює списання з захопленням коштів на суму кошика у валюті кошика, з e-mail покупця та описом <shop name> - Cart <cart number>. Pin Payments відповідає в тому самому запиті. До цієї відповіді замовлення не існує.

Після успішного списання замовлення створюється, і покупець бачить стандартну сторінку підтвердження замовлення з Your card payment has been received. Якщо замовлення потрапило в Pin Payments payment on hold, сторінка показує Your card payment has been received and is being reviewed. We will update your order as soon as the review is complete.

Якщо Pin Payments не відповідає (тайм-аут, помилка сервера, нечитабельна відповідь), списання могло все ж відбутися. Тоді замовлення створюється в Pin Payments payment on hold без оплати, а сторінка підтвердження показує We could not confirm your payment with Pin Payments. Please check your e-mail and card statement before paying again, or contact us. Повторне надсилання того самого кошика ніколи не створює друге списання.

Для одного кошика одночасно виконується лише одна спроба оплати. Повторне надсилання отримує This order is already being paid. Please wait a moment and check your e-mail before trying again. Кошик, який уже має замовлення, або раніша спроба, що списала чи могла списати кошти, повторно не списується; замовлення створюється з цієї спроби. Токен картки можна використати лише один раз: після невдалої спроби або коли покупець змінює дані картки, створюється новий токен.

Якщо оплата не вдалася, замовлення не створюється. Покупець лишається на етапі оплати, кошик зберігається, і показується одне з цих повідомлень: Your card was declined. Please use another card or contact your bank.; Your card has insufficient funds. Please use another card.; Your card has expired. Please use another card.; The card security code (CVC) is incorrect.; This card type is not accepted. Please use Visa, Mastercard or American Express.; Payment failed: з причиною від Pin Payments щодо відхилених даних; Your card details have expired. Please enter them again and retry., коли токен не можна використати; The secure card form could not be loaded. Please reload the page or choose another payment method., коли Pin.js не завантажився; Card payments are temporarily unavailable. Please try again later or choose another payment method., коли Pin Payments відхилив секретний ключ; Your payment could not be processed. Please try again or choose another payment method. для інших помилок. Технічна причина записується в журнал.

Модуль не має сценарію 3-D Secure. Якщо ваш обліковий запис Pin Payments вимагає 3-D Secure, списання залишається очікуваним, замовлення не створюється, і покупець бачить Your card payment could not be completed (additional verification is required). Please try another card or another payment method. Немає режиму лише авторизації з подальшим захопленням, немає збережених карток, підписок, Apple Pay чи Google Pay і немає вебхуків.

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

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

No order yet: картку відхилено, списання потребувало 3-D Secure, або покупець не сплатив. Існує лише кошик.

Payment accepted: Pin Payments повідомив про успішне списання з захопленням коштів точно на суму та у валюті кошика. Платіж записується з токеном списання Pin Payments як ID транзакції, а примітка показує суму й токен списання (і TEST MODE для тестових платежів).

Pin Payments payment on hold: списання потребує вашої перевірки. Примітка пояснює причину: Pin Payments списав суму або валюту, відмінні від кошика (записується платіж на списану суму), кошик змінився під час оплати, списання авторизоване, але не захоплене (захопіть його в панелі Pin Payments, а потім переведіть замовлення в статус «Оплату прийнято»), або Pin Payments не дав чіткої відповіді (платіж не записується; знайдіть опис списання в панелі Pin Payments до відправлення замовлення).

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

Якщо для кошика, який уже має замовлення, виконано друге списання, замовлення не змінюється. Примітка просить перевірити його та повернути кошти в панелі Pin Payments.

Блок Pin Payments

На сторінці замовлення показано блок Pin Payments з позначкою Test mode для тестових платежів, токеном списання, статусом, брендом картки та останніми чотирма цифрами, списаною сумою, сумою замовлення та поверненою сумою, Description at Pin Payments, історією повернень і Pin Payments notes замовлення.

Повернення

У блоці Pin Payments введіть суму (ще не повернена сума підставляється автоматично), за потреби причину, і натисніть Refund via Pin Payments. Підтвердіть питання Refund this amount through Pin Payments? This cannot be undone. Підтримуються повні та часткові повернення. Потрібне право редагувати замовлення. Повернення обмежені сумою та валютою, які Pin Payments фактично списав, тож після розбіжності суми або валюти можна повернути не більше, ніж заплатив покупець, а не суму замовлення. Повернення надсилається в середовище (тестове або робоче), у якому було оплачено замовлення, тож секретний ключ цього режиму має бути заповнений. Pin Payments обробляє повернення асинхронно, тому статус зазвичай «В очікуванні». Успішний запит додається до історії повернень і приміток разом із токеном повернення Pin Payments та його статусом. Повне повернення переводить замовлення в статус Refunded. Часткове повернення статус не змінює. Якщо Pin Payments відхилив повернення або не відповів, блок показує помилку, і повернення не записується.

Якщо для замовлення немає записаного списання (Pin Payments не дав чіткої відповіді), блок не показує форму повернення і підказує, який опис шукати в панелі Pin Payments.

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

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

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

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

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

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

Pin Payments не з'являється на сторінці оформлення замовлення: перевірте, що ліцензія активна, Enable/Disable увімкнено, обидва ключі поточного режиму заповнені (Test publishable key та Test secret key у тестовому режимі, інакше робочі ключі), і валюта кошика входить до 14 підтримуваних. У Payment > Preferences перевірте, що модуль дозволено для валюти кошика, країни покупця та групи покупця. Сторінка налаштувань показує помилку за відсутніх ключів і за непідтримуваної валюти магазину.

Оплата пройшла, але замовлення в статусі Pin Payments payment on hold: прочитайте примітки в блоці Pin Payments (див. Статуси замовлення). Якщо Pin Payments не дав чіткої відповіді, знайдіть у панелі Pin Payments списання з описом <shop name> - Cart <cart number>, потім відправте замовлення або поверніть списання в панелі.

Покупець бачить Your payment was received, but the order could not be completed automatically: картку списано, але PrestaShop не зміг створити замовлення (наприклад, модуль тим часом вимкнули). Причина записана в журнал. Покупця просять не платити повторно; повторне надсилання того самого кошика створює замовлення без нового списання.

Покупці бачать Card payments are temporarily unavailable: Pin Payments відхилив секретний ключ, або ключ поточного режиму відсутній. Тестові ключі працюють лише в тестовому режимі, робочі — лише в робочому. Журнал показує причину.

Замовлення не проходять з additional verification is required: ваш обліковий запис Pin Payments вимагає 3-D Secure, який модуль не підтримує. Попросіть Pin Payments вимкнути обов'язковий 3-D Secure.

Захищену форму картки не вдалося завантажити: Pin.js із CDN Pin Payments не завантажився в браузері, наприклад через блокувальник скриптів або модуль, що об'єднує чи змінює скрипти. Виключіть оформлення замовлення з таких оптимізацій.

Pin Payments не відповів: токен картки не було створено в браузері протягом 30 секунд. Покупець може перевірити з'єднання та спробувати знову; нічого не списано.

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

Повернення не проходить: прочитайте повідомлення в блоці. Повідомлення про режим TEST або LIVE означає, що секретний ключ режиму, у якому оплачено замовлення, порожній. Pin Payments did not confirm the refund означає, що відповіді не було; перевірте списання в панелі Pin Payments, перш ніж повторювати. at most показує суму, яку ще можна повернути за списанням.

Тестові платежі: тестовий режим використовує тестове середовище та тестові ключі. Використовуйте тестові картки з документації розробника Pin Payments, наприклад 4200 0000 0000 0000 (успішно) або 4100 0000 0000 0001 (відхилено), з будь-яким майбутнім терміном дії та будь-яким CVC. Замовлення зберігають режим, у якому були оплачені, тож повернення йдуть у правильне середовище після зміни режиму.

Де шукати помилки: помилки завжди записуються в журнал; див. поле Log на сторінці модуля. Увімкніть Debug log, щоб бачити кожен виклик API.

Видалення

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

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