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

Вимоги

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

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

Валюта: південноафриканський ранд (ZAR). PayFast проводить розрахунки лише в рандах, тому кошик має бути в ZAR. Якщо валюти немає в магазині, додайте її в розділі International > Localization > Currencies. Мінімальна сума замовлення — R5,00.

Обліковий запис PayFast: Merchant ID і Merchant Key вашого облікового запису PayFast, які можна знайти в розділі Settings > Developer Settings панелі PayFast. Passphrase настійно рекомендована; якщо її задано в PayFast, ту саму passphrase потрібно ввести в модулі. Для тестів потрібні облікові дані sandbox PayFast.

Доступний магазин: URL для сповіщень про платежі має бути доступний з інтернету, без basic auth і без блокування файрволом.

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

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

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

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

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

4. Введіть Merchant ID, Merchant Key і passphrase. Для тестування залиште Test mode увімкненим і введіть облікові дані sandbox.

5. Увімкніть Enable/Disable і натисніть Save. Зробіть тестовий платіж, а потім вимкніть Test mode, щоб приймати реальні платежі.

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

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

Усі налаштування розташовані на сторінці модуля: Modules > Module Manager > VibeFox PayFast Pay Gateway > Configure. Кожен розділ має власну кнопку Save, яка зберігає всю сторінку. Над полями сторінка попереджає, якщо облікові дані поточного режиму порожні (тоді PayFast приховано на оформленні замовлення), якщо валюта магазину за замовчуванням не ZAR, якщо в робочому режимі використовується публічний Merchant ID sandbox 10000100 і якщо passphrase не задано. Поки тестовий режим увімкнено і модуль активний, показується повідомлення: Тестовий режим увімкнено: замовлення оплачуються в sandbox PayFast, реальні кошти не списуються. Порожнє поле Title не приймається, з'являється повідомлення Введіть назву способу оплати.

PayFast

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

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

Description: текст під способом оплати на оформленні замовлення. За замовчуванням: Pay securely by card, Instant EFT and other methods on the PayFast payment page.

Обліковий запис PayFast (робочий режим)

Знайдіть Merchant ID і Merchant Key на панелі PayFast у розділі Settings > Developer Settings. Якщо ви задали passphrase там, введіть тут точно таку саму.

Merchant ID: ваш робочий Merchant ID PayFast.

Merchant Key: ваш робочий Merchant Key PayFast. Він передається в PayFast з кожною формою платежу, тому це звичайне текстове поле.

Passphrase: salt passphrase з PayFast, Settings > Developer Settings. Настійно рекомендовано: вона підписує платежі та сповіщення.

Sandbox (тестовий режим)

У тестовому режимі платежі надсилаються в sandbox PayFast, реальні кошти не списуються. Облікові дані sandbox відображаються після входу в sandbox PayFast (публічний тестовий мерчант — 10000100 / 46f0cd694581a).

Test mode: Use the PayFast sandbox and the sandbox credentials below. Поки режим увімкнено, покупець бачить під способом оплати: ТЕСТОВИЙ РЕЖИМ: платежі надсилаються в sandbox PayFast, реальні кошти не списуються. За замовчуванням: увімкнено.

Sandbox Merchant ID: Merchant ID вашого облікового запису sandbox.

Sandbox Merchant Key: Merchant Key вашого облікового запису sandbox.

Sandbox Passphrase: лише якщо passphrase задано у вашому обліковому записі sandbox.

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

Clear saved passphrases: позначте Passphrase або Sandbox Passphrase і натисніть Save, щоб видалити її. Порожнє поле зберігає збережене значення.

Сповіщення про платежі (ITN)

Notification URL: PayFast підтверджує кожен платіж серверним сповіщенням на вказаний тут URL. З дружніми URL він має вигляд https://your-shop/module/wcp_payfast_pay/itn, можливо, з кодом мови за замовчуванням. Адреса передається з кожним платежем, тому в PayFast нічого налаштовувати не потрібно, але вона має бути доступною з інтернету. Замовлення створюються лише такими перевіреними сповіщеннями; повернення покупця до магазину не створює і не оплачує замовлення.

Source check: приймати сповіщення робочого режиму лише з серверів PayFast. Адреси беруться з DNS-записів PayFast (кешуються 6 годин) і з задокументованих PayFast діапазонів адрес. Вимикайте перевірку, лише якщо магазин розміщено за проксі або CDN, які приховують адресу відвідувача. Підпис і серверне підтвердження перевіряються завжди. Сповіщення sandbox за адресою не перевіряються. За замовчуванням: увімкнено.

Додатково

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

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

Uninstall: Delete the gateway settings when the module is uninstalled (налаштування, кеш адрес PayFast і журнал). Записи платежів PayFast, замовлення та статуси замовлень завжди зберігаються. За замовчуванням: вимкнено.

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

На етапі оплати покупець обирає спосіб оплати (за замовчуванням PayFast) і підтверджує. Сторінка з повідомленням Дякуємо за замовлення. Вас перенаправляють на PayFast для завершення оплати. автоматично надсилає підписану форму платежу в PayFast. Якщо браузер не продовжує сам, покупець натискає Pay with PayFast; Cancel повертає до оформлення замовлення. Форма містить суму кошика в ZAR, Cart # з номером кошика, ім'я та e-mail покупця, посилання на платіж (номер кошика і спроба) та випадковий токен спроби. На цьому етапі замовлення ще не існує. Кожна нова спроба отримує нове посилання і новий токен.

На сторінці PayFast покупець платить карткою, Instant EFT або іншим способом вашого облікового запису PayFast. Потім PayFast надсилає сповіщення про платіж (ITN) вашому магазину. Замовлення позначається оплаченим лише після того, як PayFast підтвердить платіж сповіщенням, яке проходить усі перевірки:

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

Коли покупець повертається і замовлення існує, показується стандартна сторінка підтвердження замовлення. Якщо PayFast позначив платіж як очікуваний, з'являється: PayFast підтверджує ваш платіж. Ви отримаєте лист, щойно його буде підтверджено — платити повторно не потрібно. Якщо замовлення на утриманні, з'являється: Ваш платіж перевіряється. Ми зв'яжемося з вами, якщо знадобиться щось іще. Якщо очікуваний платіж згодом не вдався, з'являється: Ваш платіж PayFast не було завершено. Зв'яжіться з нами щодо цього замовлення. Якщо сповіщення ще не надійшло, показується сторінка Payment confirmation, де повідомляється, що PayFast підтверджує платіж і замовлення буде створено, щойно PayFast його підтвердить, з кнопками Check again і Back to checkout.

Якщо покупець скасовує платіж на сторінці PayFast, він повертається до оформлення замовлення з повідомленням Платіж PayFast скасовано. Ви можете повторити спробу або обрати інший спосіб оплати. Якщо PayFast позначив платіж як невдалий, з'являється Платіж не було завершено. Ви можете повторити спробу або обрати інший спосіб оплати. Кошик зберігається, і його можна оплатити знову.

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

Модуль приймає лише разові платежі в ZAR. Він не підтримує повернення коштів зі сторінки замовлення, підписки, збережені (токенізовані) картки та платежі з розподілом.

Замовлення

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

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

Payment accepted: PayFast підтвердив платіж. Платіж записується з ID платежу PayFast як ID транзакції, а примітка показує ID платежу. Платіж у sandbox отримує примітку про те, що реальні кошти не списано.

Awaiting PayFast payment: PayFast позначив платіж як очікуваний. Замовлення переходить у статус Payment accepted, коли PayFast завершить платіж.

Payment error: очікуваний платіж не вдався. Якщо PayFast завершить його пізніше, замовлення стане Payment accepted.

PayFast payment on hold: сплачена сума відрізняється від суми кошика, або кошик не в ZAR; платіж надійшов для замовлення, яке було скасовано, або спосіб оплати якого більше не PayFast; або платіж у sandbox надійшов, поки шлюз працює в робочому режимі. Сума, отримана від PayFast, записується в замовлення (не для платежу в sandbox), а примітка пояснює ситуацію. Перевірте замовлення та панель PayFast, потім переведіть замовлення в Payment accepted або скасуйте його і поверніть платіж у PayFast.

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

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

На сторінці замовлення показано блок PayFast payment з посиланням на платіж (m_payment_id), ID платежу PayFast, середовищем (live або sandbox), статусом, сумами брутто, комісії та нетто в ZAR і примітками модуля. Для замовлення на утриманні показується нагадування перевірити платіж.

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

Повернення коштів зі сторінки замовлення не підтримуються. Поверніть платіж у панелі PayFast, а потім вручну оновіть замовлення в PrestaShop.

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

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

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

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

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

PayFast не з'являється на оформленні замовлення: перевірте, що ліцензія активна, Enable/Disable увімкнено, заповнені Merchant ID і Merchant Key поточного режиму, кошик у ZAR і сума замовлення не менша за R5,00. Сторінка налаштувань показує попередження, якщо чогось бракує. У Payment > Preferences перевірте, що модуль дозволений для ранда, країни покупця і групи покупця.

Платіж пройшов, але замовлення не створено: PayFast не зміг доставити сповіщення про платіж або сповіщення було відхилено. Перегляньте поле Log на сторінці модуля; помилки та відхилені сповіщення записуються завжди, а Debug log додає кожен крок. Типові причини: магазин недоступний з інтернету (basic auth, файрвол), різні passphrase у PayFast і в модулі або, у робочому режимі за проксі чи CDN, перевірка джерела. У такому разі вимкніть Source check.

Сповіщення відповідає Invalid signature: passphrase у модулі не та, що задана в PayFast для режиму, в якому було здійснено платіж.

Сповіщення відповідає Invalid source: сповіщення надійшло не з адреси PayFast, або проксі чи CDN приховує справжню адресу. Вимкніть Source check, якщо магазин розміщено за проксі або CDN.

Сповіщення відповідає Merchant mismatch або Order mismatch: платіж було здійснено на інший обліковий запис PayFast або він не належить до цієї спроби оплати. Нічого не змінюється.

Сповіщення відповідає Order not found: посилання на платіж невідоме цьому магазину. Нічого не змінюється.

Сповіщення відповідає Confirmation unavailable, Busy або Temporary error: не вдалося зв'язатися з PayFast для серверного підтвердження, інше сповіщення для того самого кошика оброблялося в той самий момент, або замовлення не вдалося створити (наприклад, модуль вимкнено). PayFast повторить сповіщення. У журналі вказано причину.

Сповіщення відповідає Not configured: відсутні облікові дані режиму, у якому розпочато платіж. Введіть їх знову, наприклад облікові дані sandbox для тестового платежу.

Покупець бачить повідомлення PayFast приймає платежі лише в південноафриканських рандах (ZAR): кошик у іншій валюті. Попросіть покупця платити в рандах або обрати інший спосіб оплати.

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

Платіж у sandbox не оплатив замовлення: шлюз працює в робочому режимі. Платежі в sandbox ніколи не оплачують замовлення в робочому режимі; примітка до замовлення повідомляє про це.

Для розробників: хук actionPayfastPPaymentData може змінити поля форми платежу до підписання. Облікові дані мерчанта, URL, посилання на платіж, суму та токен через нього змінити не можна.

Видалення

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

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