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. Если в журнале сказано, что адрес возврата содержит символы, которые 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.