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 для боевых платежей и вебхуков. Страница настроек предупреждает, если включён боевой режим, а адрес магазина не использует HTTPS.

Учётная запись IntaSend: нужны публичный ключ (ISPubKey_...) и секретный ключ (ISSecretKey_...) вашей учётной записи IntaSend для песочницы, для боевого режима или для обоих, а также вебхук с контрольной фразой (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 для песочницы и/или для боевого режима, добавьте вебхук в панели 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. Блок также предупреждает, если ключи текущего режима не заполнены или неверны (тогда способ оплаты скрывается на странице оформления заказа), если валюта магазина по умолчанию не поддерживается, если не задана контрольная фраза вебхука и если боевой режим используется без 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, отдельно в панели песочницы и в боевой панели (в разделе есть ссылки на обе). Тестовый режим использует ключи песочницы и API песочницы, боевой режим — боевые ключи и боевой API. Расширение проверяет, что публичный ключ начинается с ISPubKey_, секретный — с ISSecretKey_, и что ключи соответствуют текущему режиму: ключи песочницы содержат _test, боевые ключи содержат _live. Если нет, способ оплаты скрывается, а блок статуса объясняет причину.

Test mode: использует песочницу IntaSend, реальные деньги не списываются. По умолчанию: включено. Выключите, чтобы принимать реальные платежи боевыми ключами. Пока тестовый режим включён, покупатели на шаге 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, в песочнице и в боевом режиме, откройте 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 точно так, как он показан в настройках. Введите там контрольную фразу и ту же фразу в расширении. Используйте одну контрольную фразу для песочницы и боевого режима.

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. E-mail и телефон покупателя, а также имя, адрес и страна платёжного адреса передаются в 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. Подробности записываются в журнал. Заказ на нулевую сумму оплатить через IntaSend нельзя.

Вебхук работает и тогда, когда магазин находится в режиме обслуживания: OpenCart 3 пропускает запросы платёжных расширений, а в OpenCart 4 расширение добавляет стартовое действие (startup action), которое пропускает вебхук и возврат покупателя.

Расширение принимает только разовые платежи. Возвраты из магазина в IntaSend не отправляются; сохранённых карт, подписок и встроенной (всплывающей) платёжной формы нет. Более ранние ссылки на оплату того же заказа нельзя отменить в IntaSend.

Заказы

Статусы заказов

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

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

On Hold Status (default Pending): IntaSend сообщил о сумме или валюте, отличных от суммы заказа, о частичной оплате или о платеже, поступившем после отмены заказа. Примечание объясняет это. Проверьте платёж в панели IntaSend и выполните заказ или сделайте возврат платежа. Если позже поступит правильный платёж, заказ переходит в Paid Order Status, и покупатель получает уведомление по e-mail.

Если второй платёж поступает за уже оплаченный заказ, заказ не меняется. Примечание просит вас вернуть его в панели 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 включён, ключи текущего режима заполнены и соответствуют ему: ключи песочницы (с _test) в тестовом режиме, боевые ключи (с _live) в боевом режиме. Блок статуса вверху страницы настроек показывает, что не так. Валюта оформления заказа покупателя должна поддерживаться. Также проверьте, что платёжный адрес входит в выбранную Geo Zone и что сумма заказа достигает Total, заданного в настройках.

Платёж прошёл, но заказ остаётся без статуса: подтверждения 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.

Заказ в 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. означает, что сессия оформления больше не соответствует заказу или способ оплаты был отключён: покупатель перезагружает страницу оформления. Если в журнале сказано, что адрес возврата содержит символы, которые 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 также его стартовое действие (startup action), которое пропускает вебхук и возврат покупателя в режиме обслуживания). Если Delete data on uninstall включено, удаляются остальные настройки шлюза (название, описание, тестовый режим, ключи, контрольная фраза вебхука, переключатель журнала отладки) и журнал. Если выключено, они сохраняются для повторной установки. Записи о попытках оплаты IntaSend и счета заказов всегда сохраняются. Существующие заказы сохраняют свои платёжные примечания.

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

IntaSend — товарный знак его правообладателя. Это расширение не связано с IntaSend и не одобрено IntaSend.