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

Вимоги

PrestaShop: 8.0–9.x.

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

HTTPS: IntaSend вимагає HTTPS для платежів у робочому режимі та для вебхуків. Сторінка налаштувань попереджає вас, коли увімкнено робочий режим, а магазин не використовує HTTPS.

Обліковий запис IntaSend: потрібні публічний ключ (ISPubKey_...) і секретний ключ (ISSecretKey_...) вашого облікового запису IntaSend — для пісочниці, для робочого режиму або для обох, а також вебхук із фразою перевірки в панелі IntaSend (див. Налаштування). Публічний ключ створює сторінку оплати. Секретний ключ використовується лише на вашому сервері, щоб запитати в IntaSend статус платежу.

Валюта магазину: KES, USD, EUR, GBP, UGX, TZS, NGN, GHS, XAF або XOF. Для інших валют спосіб оплати приховується.

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

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

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

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

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

4. Вставте ваші ключі IntaSend для пісочниці та/або робочого режиму, додайте вебхук у панелі IntaSend і введіть ту саму фразу перевірки в модулі (див. Налаштування).

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

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

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

Усі налаштування розташовані на сторінці модуля: Modules > Module Manager > VibeFox IntaSend Pay Gateway > Configure. Кожен розділ має власну кнопку Save, яка зберігає всю сторінку. Над полями блок статусу показує Test mode: IntaSend sandbox, no real money is charged. або Live mode: real payments are accepted. Він також попереджає, коли ключі поточного режиму відсутні або невірні (тоді спосіб оплати приховується на оформленні замовлення), коли валюта магазину за замовчуванням не підтримується, коли не задано фразу перевірки вебхука та коли робочий режим використовується без HTTPS. Вставлені ключі очищуються від пробілів під час збереження.

IntaSend

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

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

Description: текст, який показується під способом оплати на оформленні замовлення. За замовчуванням: You will be redirected to IntaSend to pay securely with M-Pesa, card or another available method.

Ключі API

Ключі беруться в панелі IntaSend у розділі Settings > API Keys, окремо в панелі пісочниці та в панелі робочого режиму (у розділі є посилання на обидві). Тестовий режим використовує ключі пісочниці та API пісочниці, робочий режим — робочі ключі та робочий API. Модуль перевіряє, що публічний ключ починається з ISPubKey_, секретний — з ISSecretKey_, і що ключі належать до поточного режиму: ключі пісочниці містять _test, робочі — _live. Якщо ні, спосіб оплати приховується, а блок статусу пояснює причину.

Test mode: використовує пісочницю IntaSend, реальні кошти не списуються. За замовчуванням: увімкнено. Вимкніть його, щоб приймати реальні платежі робочими ключами. Поки тестовий режим увімкнено, на оформленні замовлення під способом оплати показується TEST MODE - IntaSend sandbox, no real money is charged.

Sandbox publishable key: починається з ISPubKey_test. Ідентифікує ваш бізнес під час створення сторінки оплати.

Sandbox secret key: починається з ISSecretKey_test. Використовується лише на вашому сервері для підтвердження платежів через Payment Status API.

Live publishable key: починається з ISPubKey_live.

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

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

Webhook

Вебхук повідомляє вашому магазину, що платіж здійснено, навіть коли покупець не повертається до магазину (браузер закрито, M-Pesa підтвердила пізніше). У панелі IntaSend, як у пісочниці, так і в робочому режимі, відкрийте Webhooks і додайте URL, який показано в полі Webhook URL у цьому розділі. З увімкненими зрозумілими URL він має такий вигляд: https://your-shop/module/wcp_intasend_pay/webhook, можливо з кодом мови, наприклад /en/. Скопіюйте URL точно так, як його показують налаштування. Введіть там фразу перевірки та ту саму фразу в модулі. Використовуйте одну фразу перевірки для пісочниці та робочого режиму.

Webhook challenge: та сама фраза перевірки, що й у панелі IntaSend. Вебхуки з іншою фразою відхиляються. Поки це поле порожнє, вебхуки не обробляються, а платежі підтверджуються лише тоді, коли покупець повертається до магазину. Такі вебхуки отримують відповідь Ignored, а не помилку, щоб IntaSend не вимкнув вебхук до того, як ви введете фразу перевірки.

Очищення збережених секретів: позначте Sandbox secret key, Live secret key або Webhook challenge і натисніть Save, щоб його видалити. Порожнє поле залишає збережене значення.

Модуль реагує на такі статуси платежу, які повідомляє IntaSend. Щоразу він запитує в Payment Status API реальний статус, перш ніж щось змінювати:

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

Додатково

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

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

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

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

На етапі оплати покупець обирає спосіб оплати (за замовчуванням IntaSend (M-Pesa, card)) і підтверджує вибір. Модуль створює сторінку оплати IntaSend на суму кошика у валюті кошика та переспрямовує покупця на сторінку оплати, яку розміщує IntaSend. Там покупець платить через M-Pesa, картку або інший спосіб, увімкнений у вашому обліковому записі IntaSend. Електронна адреса покупця, а також ім'я, адреса, телефон і країна платіжної адреси передаються в IntaSend, якщо відповідають правилам полів IntaSend. Порожні або непридатні поля пропускаються. На цьому етапі замовлення ще не існує.

Після оплати покупець повертається до вашого магазину. Замовлення позначається оплаченим лише тоді, коли IntaSend це підтвердить: модуль запитує статус у Payment Status API, коли покупець повертається, і коли надходить вебхук. Тоді замовлення створюється, і покупець бачить стандартну сторінку підтвердження замовлення. Якщо замовлення було переведено в статус «На утриманні», сторінка показує Your payment was received and your order is being reviewed. We will contact you if anything is needed. Якщо платіж ще не підтверджено або IntaSend у цей момент недоступний, з'являється сторінка Payment confirmation з текстом Your payment is being confirmed by IntaSend (M-Pesa confirmations can take a minute). You will receive an e-mail as soon as it is confirmed. і кнопками Check again та Back to checkout. Вебхук створює замовлення, щойно IntaSend підтверджує платіж.

Якщо платіж не пройшов, покупець повертається до оформлення з повідомленням The payment was not successful. Please try again or choose another payment method. (з причиною від IntaSend, якщо вона є). Якщо покупець повернувся без оплати, повідомлення таке: The payment was not completed. Please try again or choose another payment method. Кошик зберігається, і покупець може оплатити знову. Кожна спроба отримує власне посилання IntaSend.

Якщо IntaSend не може розпочати платіж, покупець залишається на оформленні з повідомленням IntaSend could not start the payment: і причиною від IntaSend або з повідомленням IntaSend is temporarily unavailable. Please try again in a moment or choose another payment method. Подробиці записуються в журнал. Кошик на нульову суму оплатити через IntaSend не можна.

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

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

Замовлення

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

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

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

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

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

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

Сторінка замовлення показує блок IntaSend payment з кожною спробою оформлення для кошика замовлення (дата, посилання, сторінка оплати IntaSend, середовище, сума, рахунок і результат, з причиною невдачі) та Invoices processed (рахунок, статус в IntaSend, сума і результат). Блок доступний лише для читання.

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

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

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

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

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

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

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

IntaSend не з'являється на оформленні замовлення: перевірте, що ліцензія активна, Enable/Disable увімкнено, а ключі поточного режиму заповнені й належать до цього режиму: ключі пісочниці (з _test) у тестовому режимі, робочі ключі (з _live) у робочому режимі. Валюта кошика має підтримуватися. Блок статусу вгорі сторінки налаштувань показує, що не так. У Payment > Preferences перевірте, що модуль дозволено для валюти кошика, країни покупця і групи покупця.

Платіж пройшов, але замовлення не створено: підтвердження M-Pesa можуть тривати деякий час. Вебхук створює замовлення, коли IntaSend повідомляє фінальний статус. Перевірте, що URL вебхука в панелі IntaSend (пісочниця або робочий режим, той, яким ви користуєтесь) точно збігається з адресою в полі Webhook URL, а фраза перевірки там така сама, як у Webhook challenge. Замовлення також створюється, коли покупець повертається до магазину або натискає Check again.

Вебхук відповідає Ignored: webhook challenge not configured: поле Webhook challenge порожнє. Введіть фразу перевірки з панелі IntaSend.

Вебхук відповідає Invalid challenge: фраза перевірки в IntaSend і в модулі не збігаються, або у вебхуку немає фрази перевірки.

Вебхук відповідає Verification unavailable, retry later або Busy, retry later: IntaSend у цей момент був недоступний, кошик підтверджував інший запит, або замовлення не вдалося створити (наприклад, модуль вимкнено). IntaSend повторить вебхук. Причина є в журналі.

Вебхук відповідає Invoice not verified або Invoice does not match the reference: IntaSend не підтвердив, що цей рахунок належить до кошика. Нічого не змінюється.

URL вебхука в браузері показує Method not allowed: це нормально. URL приймає лише запити від IntaSend.

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

Покупець бачить помилку, коли обирає IntaSend: перегляньте поле Log на сторінці модуля (увімкніть Debug log для більшої деталізації). Якщо ключі поточного режиму невірні, покупець бачить IntaSend is not available at the moment. Please choose another payment method or contact the store. Якщо в журналі сказано, що URL повернення містить символи, які IntaSend не приймає, причина в адресі магазину.

Покупець бачить We could not match this payment to an order: посилання на повернення було змінено або воно належить до іншого кошика. Якщо покупець оплатив, вебхук однаково створить замовлення.

Видалення

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

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