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

Вимоги

PrestaShop: 8.0–9.x.

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

Валюта: кошик має бути у KES, UGX, TZS, ZMW, RWF або USD. У інших валютах спосіб оплати приховано на етапі оформлення замовлення. Кошик списується у власній валюті; модуль не конвертує валюти. Суми надсилаються в основних одиницях валюти, округлених до її точності (для UGX і RWF без десяткових знаків).

Обліковий запис Pesapal: потрібні ключ і секрет споживача облікового запису мерчанта Pesapal. Ключі для тестового і робочого середовища різні. Тестові ключі (sandbox) беруться з демонстраційного облікового запису мерчанта на cybqa.pesapal.com (Pesapal також публікує демонстраційні ключі на своєму порталі розробників). Робочі ключі беруться з вашої панелі мерчанта Pesapal. Більше нічого в панелі Pesapal налаштовувати не потрібно: модуль сам реєструє свій URL для сповіщень. Ваш магазин має бути доступний з інтернету, оскільки Pesapal надсилає йому сповіщення про платежі.

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

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

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

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

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

4. Введіть ключ і секрет споживача для тестового середовища, увімкніть Enable/Disable, натисніть Save і зробіть тестове замовлення.

5. Введіть ключ і секрет споживача для робочого середовища, вимкніть Sandbox mode і натисніть Save, щоб приймати реальні платежі.

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

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

Усі параметри розташовані на сторінці модуля: Modules > Module Manager > VibeFox Pesapal Pay Gateway > Configure. Кожен розділ має власну кнопку Save, яка зберігає всю сторінку. Над полями значок показує режим: SANDBOX — Test payments on cybqa.pesapal.com — no real money is charged. або LIVE — Real payments on pay.pesapal.com. Попередження з'являється, коли не заповнено ключі поточного режиму (Enter the sandbox consumer key and secret — until then Pesapal is not shown at checkout. або те саме для робочого середовища), а також коли Pesapal не підтримує типову валюту вашого магазину.

Pesapal

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

Title: назва способу оплати, яку бачить покупець на етапі оформлення замовлення. Вона також зберігається в замовленні як назва способу оплати. За замовчуванням: Pesapal (M-Pesa, Airtel Money, cards). Обов'язкове поле: порожня назва не зберігається, залишається попередня.

Description: текст під способом оплати на етапі оформлення замовлення. За замовчуванням: Pay securely with M-Pesa, Airtel Money, card or bank via Pesapal. You will be redirected to Pesapal to complete the payment.

Облікові дані API

У цьому розділі пояснюється, де взяти ключі, і є посилання на cybqa.pesapal.com і pesapal.com. Введіть ключі для тестового та робочого середовища, кожен у своє поле.

Sandbox mode: Use the Pesapal sandbox (no real money). Коли увімкнено, нові платежі йдуть через cybqa.pesapal.com з тестовими ключами. Вимкніть, щоб приймати реальні платежі на pay.pesapal.com з робочими ключами. За замовчуванням: увімкнено.

Sandbox consumer key: ключ споживача вашого демонстраційного облікового запису мерчанта для тестового середовища. Використовується лише в режимі sandbox.

Sandbox consumer secret: секрет споживача вашого облікового запису мерчанта для тестового середовища. Використовується лише в режимі sandbox.

Live consumer key: ключ споживача з вашої панелі мерчанта Pesapal. Використовується, коли режим sandbox вимкнено.

Live consumer secret: секрет споживача з вашої панелі мерчанта Pesapal. Використовується, коли режим sandbox вимкнено.

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

Clear saved consumer keys and secrets: позначте прапорець і натисніть Save, щоб видалити всі чотири збережені ключі та секрети.

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

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

IPN URL: показує URL сповіщень вашого магазину. З «зрозумілими» URL він має такий вигляд: https://your-shop/module/wcp_pesapal_pay/webhook, можливо, з кодом мови, наприклад /en/. URL автоматично реєструється в Pesapal під час першого платежу, окремо для тестового та робочого середовища і для кожної пари ключів, тож нічого налаштовувати не потрібно. Після першого платежу розділ показує Registered IPN ID: з ID, який повернув Pesapal; до цього там написано Not registered yet for the current mode and keys. URL має бути доступний з інтернету: без брандмауера й парольного захисту перед ним. Він продовжує працювати, поки магазин на обслуговуванні, і не блокується обмеженням за країнами вашого магазину.

Додатково

Debug log: Log Pesapal requests and notifications. Записує деталі у logs/pesapal_p_debug.log.php у папці модуля. Файл не можна відкрити з веб-браузера. Помилки та попередження записуються завжди, навіть коли перемикач вимкнено. Ключі, токени та дані покупців ніколи не записуються. За замовчуванням: вимкнено.

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

Delete data: Delete the module settings and logs when the module is uninstalled. Дані Pesapal, збережені в замовленнях (ідентифікатори відстеження, примітки), є історією платежів і завжди зберігаються. Вимкнення модуля нічого не видаляє. За замовчуванням: вимкнено.

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

На етапі оплати покупець обирає спосіб оплати (за замовчуванням Pesapal (M-Pesa, Airtel Money, cards)) і бачить його опис. Після підтвердження модуль створює запит на платіж Pesapal на суму кошика у валюті кошика з платіжними даними з адреси для рахунку та перенаправляє покупця на платіжну сторінку Pesapal. Опис платежу, який передається в Pesapal, — Cart, номер кошика і назва магазину. Там покупець платить одним із способів, які пропонує Pesapal, наприклад M-Pesa, Airtel Money, MTN, карткою або банківським переказом. На цьому етапі замовлення ще не існує.

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

Платежі через мобільні гроші можуть тривати трохи довше. Якщо Pesapal ще не підтвердив платіж, коли покупець повертається, сторінка Payment confirmation показує Your payment is being confirmed by Pesapal. You will receive an e-mail as soon as it is confirmed — there is no need to pay again. з кнопками Check again і Back to checkout. Сповіщення від Pesapal створює замовлення, щойно платіж підтверджено. Якщо замовлення було переведено в статус очікування, сторінка підтвердження показує Your payment was received and is being reviewed by the shop. You will receive an e-mail once the order is confirmed.

Якщо покупець скасовує платіж на сторінці Pesapal, він повертається до оформлення замовлення з повідомленням The Pesapal payment was cancelled. You can try again or choose another payment method. Якщо платіж не пройшов, з'являється повідомлення The Pesapal payment was not successful. Please try again or choose another payment method. Кошик зберігається, і покупець може оплатити знову. Кожна спроба оплати кошика запам'ятовується, тож платіж, зроблений пізніше на старішій сторінці Pesapal цього кошика, також приймається.

Якщо Pesapal не може розпочати платіж, покупець залишається на етапі оформлення замовлення з коротким повідомленням, наприклад Pesapal is temporarily unavailable. Please try again in a few minutes or choose another payment method., Pesapal is not available at the moment. Please choose another payment method. (неправильні ключі) або Pesapal could not start the payment:, після чого йде причина від Pesapal. Технічна причина записується в журнал. Сума замовлення має бути більшою за нуль.

Модуль не має платіжної форми на вашому сайті (покупець завжди платить на сторінці Pesapal), немає збережених карток, підписок чи регулярних платежів і немає конвертації валют.

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

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

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

Payment accepted: Pesapal позначає платіж як завершений, а сума й валюта збігаються. Платіж записується з ідентифікатором відстеження Pesapal як ID транзакції, а примітка показує суму, спосіб оплати, код підтвердження Pesapal і ідентифікатор відстеження. Кожен платіж застосовується лише один раз.

Pesapal payment on hold: сплачені сума або валюта відрізняються від кошика (примітка Pesapal amount/currency mismatch — held for review), або надійшли гроші за замовлення, яке було скасовано. Фактично сплачена сума записується в замовлення, якщо вона у валюті замовлення. Перевірте платіж у панелі Pesapal, а потім завершіть замовлення або поверніть кошти.

Refunded: Pesapal повідомляє, що платіж, яким оплачено замовлення, було відмінено. Відміна іншої спроби лише відзначається в замовленні.

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

Блок оплати Pesapal

На сторінці замовлення показано блок Pesapal payment зі значком Sandbox або Live, ідентифікатором відстеження, референсом мерчанта, статусом Pesapal, способом оплати, кодом підтвердження, запитаною та сплаченою сумою, причиною перевірки, усіма Payment attempts кошика та Payment notes замовлення. Блок призначений лише для читання.

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

Модуль не надсилає повернення коштів до Pesapal. Поверніть платіж у панелі Pesapal, а потім вручну зафіксуйте повернення в PrestaShop.

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

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

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

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

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

Pesapal не з'являється на етапі оформлення замовлення: перевірте, що ліцензія активна, Enable/Disable увімкнено, введено ключ і секрет споживача поточного режиму (Sandbox consumer key і Sandbox consumer secret у режимі sandbox, Live consumer key і Live consumer secret у робочому режимі) і валюта кошика — KES, UGX, TZS, ZMW, RWF або USD. Попередження у верхній частині налаштувань вказують на проблему. У Payment > Preferences перевірте, що модуль дозволений для валюти кошика, країни покупця та групи покупця. Розробники можуть змінити список валют за допомогою хука actionPesapalSupportedCurrencies.

Платіж пройшов, але замовлення не створено: сповіщення від Pesapal не дійшло до вашого магазину, а покупець не повернувся. Перевірте, що URL, показаний у IPN URL, доступний з інтернету (без брандмауера й парольного захисту перед ним). Увімкніть Debug log і перегляньте поле Log на сторінці модуля.

Як магазин відповідає на сповіщення: оброблене сповіщення отримує відповідь HTTP 200. Якщо модуль не може його обробити, він відповідає помилкою, і Pesapal надішле сповіщення повторно пізніше: 400 (ідентифікатор відстеження відсутній або некоректний), 404 (жоден кошик цього магазину не має такого ідентифікатора відстеження), 409 (транзакція належить до іншого референсу мерчанта; нічого не змінюється), 502 (API Pesapal у цей момент був недоступний або не заповнено ключі того режиму, в якому розпочато платіж) і 503 (кошик у цей самий час оновлювався поверненням покупця, або замовлення не вдалося створити, наприклад тому, що модуль вимкнено).

Покупець бачить Pesapal is not available at the moment: Pesapal відхилив ключ або секрет споживача поточного режиму. Перевірте, що ключі відповідають режиму: тестові ключі працюють лише в sandbox, робочі — лише в робочому режимі. Журнал показує помилку Pesapal.

Покупець бачить Pesapal is temporarily unavailable: Pesapal був недоступний або не вдалося зареєструвати URL сповіщень. Прочитайте журнал і спробуйте ще раз.

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

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

Видалення

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

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