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

Вимоги

WordPress: 6.2 або новіша версія.

WooCommerce: 8.0 або новіша версія, встановлено й активовано. Без нього плагін не активується.

PHP: 8.0 або новіша версія.

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

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

VibeFox license key: придбаний на vibefox.net. Один ключ працює на одному домені.

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

1. У WordPress відкрийте Plugins > Add New > Upload Plugin, виберіть ZIP-файл плагіна й натисніть Install Now. Також можна завантажити папку wcp_pesapal_pay до /wp-content/plugins/ через FTP.

2. Натисніть Activate.

3. Відкрийте налаштування: WooCommerce > Settings > Payments > Pesapal > Manage, або натисніть Settings під назвою плагіна на сторінці плагінів.

4. Введіть ліцензійний ключ VibeFox у блоці ліцензії вгорі сторінки й натисніть Activate.

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

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

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

Усі налаштування розміщено на одній сторінці: WooCommerce > Settings > Payments > Pesapal. Над полями позначка показує середовище: 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 позначено як тестовий режим, доки тестове середовище ввімкнено.

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

Цей блок показує URL сповіщень вашого магазину. Він має вигляд https://your-site/wc-api/pesapal_pay/. URL реєструється в Pesapal автоматично під час першого платежу, окремо для тестового й робочого середовищ і кожної пари ключів, тому нічого налаштовувати не потрібно. Після першого платежу блок показує Registered IPN ID: з ідентифікатором від Pesapal; до цього він показує Not registered yet for the current mode and keys. URL має бути доступний з інтернету: без режиму обслуговування, брандмауера чи захисту паролем, які блокують доступ.

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

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 consumer secret: секрет споживача вашого тестового облікового запису мерчанта. Використовується лише в тестовому середовищі.

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

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

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

Додатково

Debug log: Log Pesapal requests and notifications записує подробиці до WooCommerce > Status > Logs, джерело wcp_pesapal_pay. Помилки й попередження записуються завжди. Ключі, токени та дані покупців ніколи не записуються. Типово: вимкнено.

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

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

Покупець вибирає спосіб оплати (типово Pesapal (M-Pesa, Airtel Money, cards)) і оформлює замовлення. У тестовому середовищі блок Checkout показує Sandbox mode: no real money will be charged. Плагін створює запит на оплату Pesapal на загальну суму замовлення в його валюті з платіжними реквізитами замовлення та додає примітку із середовищем, сумою й ідентифікатором відстеження Pesapal. Покупець переходить на платіжну сторінку Pesapal і платить одним із запропонованих способів, наприклад через M-Pesa, Airtel Money, MTN, карткою або через банк.

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

Після оплати покупець повертається на сторінку отриманого замовлення. Платежі мобільними грошима можуть тривати певний час. Якщо платіж ще не підтверджено, сторінка показує 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. Сповіщення Pesapal завершить замовлення пізніше. Якщо замовлення переведено на утримання, сторінка показує Your payment was received and is being reviewed by the shop. You will receive an e-mail once the order is confirmed.

Якщо покупець скасовує оплату на сторінці Pesapal, він повертається на сторінку Pay for order з повідомленням 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. Технічні подробиці потрапляють до приміток замовлення й журналу. Загальна сума замовлення має бути більшою за нуль.

Спосіб оплати працює в класичному оформленні замовлення, у блоці Checkout і на сторінці Pay for order. Він сумісний із високопродуктивним сховищем замовлень WooCommerce (HPOS).

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

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

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

Pending payment: покупець перейшов до Pesapal і ще не заплатив або Pesapal ще не підтвердив платіж.

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

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

Failed: Pesapal повідомляє про невдачу останньої спроби оплати. Примітка містить причину від Pesapal. Якщо покупець повторює спробу зі сторінки Pay for order і вона теж не вдається, додається ще одна примітка з причиною. Невдача старішої спроби не змінює замовлення. Покупець може заплатити знову.

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

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

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

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

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

Плагін працює з ліцензійним ключем VibeFox з vibefox.net. Блок ліцензії розташований угорі WooCommerce > Settings > Payments > Pesapal. Вставте ключ у License key та натисніть Activate. Блок показує статус, наприклад дату завершення дії ліцензії та ваш домен. Використовуйте Check now для повторної перевірки статусу, Change key для введення іншого ключа та Remove key для видалення ключа з цього сайту. Посилання Manage licenses and domains in your account відкриває ваш обліковий запис vibefox.net.

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

Без активного ключа Pesapal не показується покупцям під час оформлення замовлення. Якщо платіж усе ж розпочато, покупець бачить This payment method is not available. Please choose another one. Авторизовані керівники магазину й далі бачать спосіб оплати з позначкою (unlicensed — visible to admins only), щоб ви могли налаштувати й перевірити плагін до придбання ключа. Нагадування з’являється на сторінці плагінів і сторінках WooCommerce. Наявні замовлення не зачіпаються: уже розпочаті платежі й далі підтверджуються сповіщенням Pesapal і поверненням покупця.

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

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

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

Платіж пройшов, але замовлення залишається в стані «Очікування оплати»: сповіщення Pesapal не дійшло до магазину, а покупець не повернувся. Перевірте доступність URL із Payment notifications (IPN) з інтернету (без режиму обслуговування, брандмауера чи захисту паролем перед /wc-api/pesapal_pay/). Перегляньте WooCommerce > Status > Logs, джерело wcp_pesapal_pay.

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

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

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

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

Блок ліцензії показує помилку: дотримуйтеся повідомлення в блоці. Наприклад, якщо ключ уже використовується на іншому домені, звільніть місце в обліковому записі vibefox.net і натисніть Check now. Якщо адреса сайту змінилася, натисніть Check now для активації ключа на новому домені. Якщо сервер ліцензій недоступний, плагін працює з останнім відомим статусом.

Видалення

Вимкнення плагіна зберігає всі дані. Для видалення вимкніть і видаліть його на сторінці Plugins. Ліцензійний ключ і статус ліцензії цього плагіна, кешовані токени доступу Pesapal та зареєстровані ідентифікатори сповіщень видаляються завжди. Налаштування плагіна та його журнали (файли журналів, включно з ротованими, і записи журналу в базі даних джерела wcp_pesapal_pay) видаляються лише за ввімкненого Delete data. Інакше вони залишаються для подальшого перевстановлення. Наявні замовлення зберігають примітки про оплату, ідентифікатори транзакцій та ідентифікатори відстеження Pesapal.

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