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

Вимоги

OpenCart: 3.0.x (перевірено на 3.0.5.0) або 4.0.2 і новіші (перевірено на 4.1.0.3).

PHP: 8.0 або новіша версія з розширенням cURL.

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

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

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

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

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

Завантаження — це один zip-файл із пакетами для обох версій OpenCart. Розпакуйте його на своєму комп'ютері. Він містить README.txt, пакет для OpenCart 3 wcp_intasend_pay-oc3-(version).ocmod.zip і пакет для OpenCart 4 wcp_intasend_pay.ocmod.zip. Встановлюйте лише пакет для вашої версії OpenCart. Ліцензійний ключ однаковий для обох версій.

OpenCart 3

1. В адмін-панелі перейдіть до Extensions > Installer, натисніть Upload і виберіть файл wcp_intasend_pay-oc3-(version).ocmod.zip. Розширення не має модифікацій OCMOD, тому оновлювати Extensions > Modifications не потрібно. Замість інсталятора можна скопіювати вміст папки upload цього пакета в кореневу папку вашого магазину.

2. Перейдіть до Extensions > Extensions і виберіть тип Payments. Знайдіть VibeFox IntaSend Pay Gateway і натисніть Install (зелена кнопка +). Адміністратору потрібне право змінювати список платіжних розширень.

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

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

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

OpenCart 4

1. В адмін-панелі перейдіть до Extensions > Installer, натисніть Upload і виберіть файл wcp_intasend_pay.ocmod.zip. Не перейменовуйте файл: OpenCart 4 бере код розширення з назви файлу, і перейменований пакет не працює.

2. Пакет з'являється у списку встановлених розширень на цій самій сторінці. Натисніть Install (зелена кнопка +) поруч із ним.

3. Перейдіть до Extensions > Extensions і виберіть тип Payments. Знайдіть VibeFox IntaSend Pay Gateway, натисніть Install (зелена кнопка +), а потім Edit (кнопка з олівцем).

4. Введіть ліцензійний ключ, ключі IntaSend і вебхук так само, як у кроках 3–5 для OpenCart 3. Сторінка налаштувань і її поля однакові в обох версіях. Відрізняється лише URL вебхука (див. Webhook).

Нове встановлення починається з вимкненим способом оплати та увімкненим тестовим режимом.

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

Усі налаштування містяться на сторінці розширення: Extensions > Extensions > Payments > VibeFox IntaSend Pay Gateway > Edit. Розділи перелічено ліворуч; кнопка Save під списком зберігає всю сторінку. Над налаштуваннями блок статусу показує Test mode: IntaSend sandbox, no real money is charged. або Live mode: real payments are accepted. Він також попереджає, коли ключі поточного режиму відсутні або неправильні (тоді спосіб оплати приховується на оформленні замовлення), коли валюта за замовчуванням у магазині не підтримується, коли фразу перевірки вебхука не задано і коли режим production використовується без HTTPS. Без права змінювати розширення сторінка показує налаштування, але не може їх зберегти.

Під час збереження Title не може бути порожнім або довшим за 128 символів, Sort Order має бути цілим числом, Total має бути числом 0 або більше, а вибрані геозона та статуси замовлень мають існувати. Інакше нічого не зберігається, і помилка вказує поле. Проблеми з ключами не блокують збереження: їх показує блок статусу. Вставлені ключі очищуються від пробілів.

IntaSend

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

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

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

Sort Order: позиція IntaSend серед способів оплати на оформленні замовлення. Залиште поле порожнім або введіть ціле число.

Geo Zone: пропонувати IntaSend лише для платіжних адрес у вибраній геозоні. За замовчуванням: All zones. Геозони налаштовуються в розділі System > Localisation > Geo Zones.

Total: сума оформлення замовлення у валюті магазину за замовчуванням, яку має досягти замовлення, перш ніж буде запропоновано IntaSend. Залиште поле порожнім, щоб пропонувати IntaSend за будь-якої суми.

API-ключі

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

Test mode: використовує sandbox IntaSend, реальні кошти не списуються. За замовчуванням: увімкнено. Вимкніть, щоб приймати реальні платежі ключами production. Поки тестовий режим увімкнено, покупці на кроці Confirm Order бачать 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. Вводьте нове значення, лише якщо хочете його змінити. Щоб видалити збережене значення, позначте Clear the saved value під полем і натисніть Save.

Webhook

Вебхук повідомляє вашому магазину, що платіж здійснено, навіть коли покупець не повертається до магазину (браузер закрито, M-Pesa підтверджено пізніше). У панелі IntaSend, у sandbox і в production, відкрийте Webhooks і додайте URL, який показано в полі Webhook URL у цьому розділі. На OpenCart 3 він має вигляд https://your-store/index.php?route=extension/payment/wcp_intasend_pay/webhook, на OpenCart 4 — https://your-store/index.php?route=extension/wcp_intasend_pay/payment/wcp_intasend_pay.webhook. Він формується з адреси вітрини вашої інсталяції OpenCart. Скопіюйте URL точно так, як його показують налаштування. Введіть там фразу перевірки і ту саму фразу в розширенні. Використовуйте одну фразу перевірки для sandbox і production.

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

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

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

Замовлення

OpenCart створює замовлення на кроці Confirm Order без статусу (відсутнє замовлення, missing order). Замовлення отримує статус лише після того, як IntaSend підтвердив платіж через Payment Status API. Кожне поле нижче перелічує ваші статуси замовлень OpenCart.

Paid Order Status: статус, який встановлюється після платежу, підтвердженого IntaSend. За замовчуванням: Processing.

On Hold Status: IntaSend повідомив про іншу суму чи валюту, часткову оплату або оплату після скасування замовлення. Замовлення отримує цей статус і примітку з поясненням. За замовчуванням: Pending, оскільки в OpenCart немає статусу On hold. Ви можете створити власний статус у розділі System > Localisation > Order Statuses і вибрати його тут.

Refunded Status: платіж, що надійшов для замовлення в цьому статусі, лише додає примітку; замовлення не відкривається знову. За замовчуванням: Refunded. Саме розширення коштів не повертає.

Додатково

Debug log: записує події оформлення замовлення, повернення та вебхука у файл intasend_p_debug.log.php у папці логів OpenCart (storage/logs). Файл не можна відкрити через веб; при досягненні 5 МБ його переміщують до intasend_p_debug.old.log.php. Помилки та попередження завжди записуються. API-ключі, фраза перевірки та дані покупців ніколи не записуються. За замовчуванням: вимкнено.

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

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

Імпорт / Експорт

Export: Download JSON зберігає налаштування у файл JSON. Секретні ключі та фраза перевірки вебхука не експортуються.

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

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

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

На OpenCart 4 покупець обирає спосіб оплати кнопкою Choose у блоці способу оплати, у вікні Payment method options, і натискає Confirm Order внизу сторінки оформлення. За замовчуванням OpenCart 4 не запитує платіжну адресу; тоді розширення передає в IntaSend адресу, місто, поштовий індекс і країну з адреси доставки.

Після оплати покупець повертається через адресу головної сторінки вашого магазину, оскільки IntaSend не приймає деякі символи в адресі повернення; розширення потім перенаправляє покупця на свою сторінку повернення. Замовлення позначається оплаченим лише після підтвердження IntaSend: розширення запитує Payment Status API, коли покупець повертається і коли надходить вебхук. Потім замовлення отримує статус стандартним для OpenCart способом, зі звичайними листами про замовлення та оновленням залишків, а покупець бачить сторінку успішного оформлення замовлення OpenCart. Якщо замовлення було переведено в очікування, сторінка також показує 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. Кошик зберігається, і покупець може оплатити знову. На OpenCart 4 ці повідомлення показуються над сторінкою оформлення. OpenCart 3 створює нове замовлення щоразу, коли показується крок Confirm Order; OpenCart 4 оновлює замовлення оформлення, тож після невдалої оплати покупець оплачує те саме замовлення новою спробою. Один кошик оплачується лише раз: якщо інше замовлення з цього самого кошика вже оплачено, покупець переходить на сторінку успіху, а не до нового платежу. Зміна кошика, зокрема нова кількість, вважається новим кошиком, який потребує власної оплати.

На OpenCart 4 замовлення зберігається в оформленні, доки не буде показано сторінку успіху. Якщо це замовлення тим часом закрили (наприклад, ви його скасували або повернули кошти), покупця повертають до оформлення з повідомленням Your previous order was cancelled or refunded. Please confirm the order again. Якщо замовлення вже розміщено, а в кошику тепер інші товари, повідомлення таке: Your previous order has already been placed for other cart contents. Please confirm the order of your current cart again. В обох випадках наступне натискання Confirm Order оплачує нове замовлення з кошика.

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

Вебхук працює й тоді, коли магазин перебуває в режимі обслуговування: OpenCart 3 пропускає запити платіжних розширень, а на OpenCart 4 розширення додає стартову дію, яка пропускає вебхук і повернення покупця.

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

Замовлення

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

No status (missing order): покупця було перенаправлено до IntaSend, і він не оплатив, платіж не вдався або IntaSend ще не підтвердив платіж. У розділі Sales > Orders такі замовлення показуються лише з фільтром Order Status, встановленим на Missing Orders.

Paid Order Status (default Processing): платіж підтверджено. Примітка показує рахунок IntaSend, спосіб оплати в IntaSend, суму, режим (sandbox або production) і спосіб підтвердження (вебхук або повернення покупця).

On Hold Status (default Pending): IntaSend повідомив про суму або валюту, відмінні від суми замовлення, про часткову оплату або про платіж, що надійшов після скасування замовлення. Примітка пояснює це. Перевірте платіж у панелі IntaSend і потім виконайте замовлення або поверніть кошти. Якщо пізніше надійде правильний платіж, замовлення переходить у Paid Order Status, а покупець отримує сповіщення листом.

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

Примітки — це записи в History замовлення, які покупець не бачить.

Вкладка VibeFox IntaSend Pay Gateway

У розділі Sales > Orders відкрийте замовлення, оплачене через IntaSend. Унизу сторінки замовлення, поруч із History і Additional, вкладка VibeFox IntaSend Pay Gateway показує IntaSend checkout attempts замовлення (дата, посилання, платіжна сесія IntaSend, середовище, сума, рахунок і спосіб оплати, результат із причиною невдачі), Invoices processed (рахунок, стан в IntaSend, сума та результат) і IntaSend notes замовлення. Вкладка лише для читання і показується користувачам, які мають доступ до розширення.

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

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

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

Розширення працює з ліцензійним ключем VibeFox, отриманим на vibefox.net. Блок ліцензії License — VibeFox IntaSend Pay Gateway — це перший блок на сторінці Extensions > Extensions > Payments > VibeFox IntaSend Pay Gateway > Edit, над налаштуваннями. Вставте ключ у поле License key і натисніть Activate. Після цього блок показує ключ у замаскованому вигляді, статус (наприклад, дату, до якої дійсна ліцензія, і ваш домен), а також кнопки Check now, щоб перевірити статус знову, Change key, щоб ввести інший ключ, і Remove key, щоб видалити ключ із цього магазину. Нижче розташовано рядок Product: opencart-payment-intasend і посилання Manage licenses and domains in your account, яке відкриває ваш обліковий запис на vibefox.net. Змінювати ключ можуть лише адміністратори з правом Modify для розширення. Тексти блоку відповідають мові адмін-панелі (включено англійську та російську).

Якщо ключ не прийнято, блок пояснює причину, наприклад Key not found, This key belongs to another product, Domain limit reached або License expired on і дата. Після зміни адреси магазину або після звільнення місця для домену у вашому обліковому записі натисніть Check now. Якщо сервер ліцензій недоступний, розширення продовжує працювати за останнім відомим статусом.

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

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

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

Вирішення проблем

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

Платіж пройшов, але замовлення лишається без статусу: підтвердження M-Pesa можуть зайняти певний час. Вебхук встановлює статус, коли IntaSend повідомляє остаточний стан. Перевірте, що URL вебхука в панелі IntaSend (sandbox або production, залежно від режиму, який ви використовуєте) точно збігається з показаним у 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.

Замовлення в On Hold Status: прочитайте примітки на вкладці VibeFox IntaSend Pay Gateway. Оплачена сума або валюта відрізнялися від замовлення, платіж був частковим або надійшов після скасування замовлення. Перевірте платіж у панелі IntaSend.

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

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

Для розробників: перед створенням оплати розширення викликає подію OpenCart intasend_p_checkout_payload з даними запиту, замовленням і режимом; подія intasend_p_supported_currencies може змінити список валют.

Видалення

Перейдіть до Extensions > Extensions, виберіть тип Payments і натисніть Uninstall (червона кнопка −) поруч із VibeFox IntaSend Pay Gateway. Ліцензійний ключ і статус ліцензії цього розширення завжди видаляються. OpenCart завжди видаляє власні налаштування розширення: Enable/Disable, Sort Order, Geo Zone, Total і статуси замовлень у розділі Orders, які повертаються до значень за замовчуванням під час повторного встановлення. Також видаляються події OpenCart розширення (на OpenCart 4 також його стартова дія, яка пропускає вебхук і повернення покупця в режимі обслуговування). Якщо Delete data on uninstall увімкнено, видаляються інші налаштування шлюзу (назва, опис, тестовий режим, ключі, фраза перевірки вебхука, перемикач журналу налагодження) та журнал. Якщо вимкнено, вони зберігаються для повторного встановлення. Спроби оплати IntaSend і рахунки замовлень завжди зберігаються. Наявні замовлення зберігають свої примітки про оплату.

На OpenCart 4, щоб видалити також файли розширення, перейдіть до Extensions > Installer після видалення і натисніть Uninstall (помаранчева кнопка −) поруч із VibeFox IntaSend Pay Gateway у списку встановлених розширень, а потім Delete (червона кнопка з кошиком), щоб видалити завантажений пакет.

IntaSend є торговельною маркою її власника. Це розширення не пов'язане з IntaSend і не схвалене IntaSend.