VibeFox Cashfree for PrestaShop — Помощь

Требования

PrestaShop: 8.0–9.x.

PHP: 8.0 или новее. Модуль не устанавливается на более старых версиях PHP.

HTTPS: Cashfree отправляет вебхуки только на URL с https://. Без HTTPS платежи всё равно подтверждаются, когда покупатель возвращается в магазин, но включите HTTPS до перехода на рабочую среду.

Учётная запись Cashfree: нужны App ID и Secret Key вашей учётной записи Cashfree отдельно для тестовой (sandbox) и рабочей среды, а также вебхук в Cashfree Merchant Dashboard (см. Настройка). Secret Key также используется для проверки вебхуков, поэтому отдельного секрета вебхука нет. Валюта корзины должна быть включена для вашей учётной записи Cashfree.

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

Установка

1. В back office перейдите в Modules > Module Manager и нажмите Upload a module. Выберите ZIP-файл модуля.

2. Когда загрузка завершится, нажмите Configure или позже найдите VibeFox Cashfree Payments в списке модулей и нажмите Configure.

3. Введите лицензионный ключ VibeFox в поле License key в блоке лицензии вверху страницы Configure и нажмите Activate (см. Лицензионный ключ).

4. Введите Sandbox App ID и Sandbox Secret Key, добавьте вебхук в Cashfree Merchant Dashboard (см. Настройка), включите Enable/Disable, нажмите Save и проверьте один платёж.

5. Когда всё готово, введите рабочие App ID и Secret Key, выключите Sandbox Mode и нажмите Save.

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

Настройка

Все настройки находятся на странице модуля: Modules > Module Manager > VibeFox Cashfree Payments > Configure. У каждого раздела есть своя кнопка Save, которая сохраняет всю страницу. Над полями страница объясняет, что заказ создаётся только после подтверждения платежа Cashfree. Когда способ оплаты включён, страница предупреждает, если не заполнены API-ключи выбранного режима (тогда способ оплаты скрыт на оформлении заказа), и показывает Sandbox mode is on: customers see a test checkout and no real money is charged. пока включён тестовый режим. Если вы сохраняете включённый способ оплаты без ключей выбранного режима, предупреждение сообщит, что он останется скрытым на оформлении заказа, пока ключи не будут заполнены.

Cashfree Payments

Enable/Disable: Enable Cashfree Payments включает или выключает способ оплаты. По умолчанию: off.

Title: название способа оплаты, которое видит покупатель на оформлении заказа. Оно же сохраняется в заказе как название способа оплаты. По умолчанию: Cashfree Payments. Обязательное поле.

Description: текст под способом оплаты на оформлении заказа. По умолчанию: Pay securely via Card, UPI, Net Banking, Wallet via Cashfree.

Mode and API keys

App ID и Secret Key берутся в Cashfree Merchant Dashboard в разделе Developers > API Keys. Тестовые и рабочие ключи различаются.

Sandbox Mode: использует тестовую среду Cashfree (sandbox). Реальные деньги не списываются, а под способом оплаты на оформлении заказа отображается SANDBOX MODE - no real payments will be processed. По умолчанию: on. Выключите для реальных платежей.

Sandbox App ID: App ID вашей тестовой среды Cashfree.

Sandbox Secret Key: Secret Key вашей тестовой среды Cashfree.

App ID: App ID вашей рабочей среды Cashfree.

Secret Key: Secret Key вашей рабочей среды Cashfree.

Сохранённые Secret Key больше никогда не отображаются. Поле остаётся пустым и показывает Saved — leave empty to keep it. Вводите новое значение, только если хотите его изменить.

Clear saved secrets: отметьте Secret Key и нажмите Save, чтобы удалить его. Пустое поле сохраняет сохранённое значение.

Платежи сохраняют среду, в которой были созданы. Их вебхуки проверяются, их статус запрашивается, а возвраты отправляются ключами именно этой среды, поэтому не удаляйте ключи sandbox, пока платежи в sandbox не завершены после перехода на рабочую среду.

Webhook

Вебхук сообщает вашему магазину, что платёж прошёл, не удался или был возвращён. В Cashfree Merchant Dashboard перейдите в Developers > Webhooks и добавьте URL, показанный в этом разделе в поле Webhook URL, с событиями Payment и Refund. При понятных URL он выглядит так: https://your-shop/module/wcp_cashfree_payment/webhook. Копируйте URL точно так, как он показан в настройках. В магазине с HTTPS модуль также передаёт этот URL в Cashfree при каждом платеже. Если ваш магазин не использует HTTPS, в этом разделе появляется предупреждение.

Модуль обрабатывает эти события (они также перечислены в этом разделе):

Cashfree подписывает каждый вебхук вашим Secret Key. Вебхуки без действительной подписи отклоняются. Вебхук должен быть подписан Secret Key той среды, в которой был сделан платёж, поэтому ключ sandbox никогда не подтверждает реальный платёж. Подписанные вебхуки для платежей, которые начал не этот магазин (например, другой магазин на той же учётной записи Cashfree), подтверждаются и игнорируются. Без вебхука заказ создаётся только тогда, когда покупатель возвращается в магазин после оплаты. Если покупатель закрыл браузер после оплаты, заказ может создать только вебхук (или следующая попытка оплаты той же корзины).

Advanced

API Version: версия API Cashfree для использования.

Order ID prefix: ID заказов Cashfree формируются как префикс + ID корзины PrestaShop; новая попытка для той же корзины получает номер в конце (например, 123-2). Оставьте поле пустым, чтобы использовать автоматический префикс этого магазина, который показан в описании поля. Для каждого магазина, подключённого к той же учётной записи Cashfree, используйте свой префикс. Допускаются только буквы, цифры, «_» и «-», до 20 символов. Остальные символы удаляются при сохранении с предупреждением.

Debug log: ошибки записываются всегда. Когда опция включена, вызовы API Cashfree и вебхуки также записываются в logs/cashfree_p_debug.log.php в папке модуля. Файл нельзя открыть через веб. Ключи и данные покупателей никогда не записываются в журнал. По умолчанию: off.

Log: показывает размер и последние записи журнала. Нажмите Clear log, чтобы очистить его.

Delete Data on Uninstall: если включено, при удалении модуля удаляются настройки Cashfree и журнал модуля. Заказы, их транзакции и возвраты Cashfree, а также статус заказа Cashfree payment on hold всегда сохраняются, поэтому существующие заказы продолжают работать. По умолчанию: off.

Оформление заказа

На этапе оплаты покупатель выбирает способ оплаты (по умолчанию Cashfree Payments) и подтверждает выбор. Модуль создаёт заказ в Cashfree на сумму корзины в валюте корзины и открывает страницу оплаты, которая показывает Redirecting to Cashfree for payment... и загружает страницу оплаты Cashfree. Если она не открылась сама, покупатель может нажать Pay Now. На странице оплаты Cashfree покупатель платит любым способом, включённым в вашей учётной записи Cashfree, например картой, UPI, интернет-банкингом или электронным кошельком. E-mail и телефон для выставления счёта покупателя передаются в Cashfree. На этом этапе заказа ещё не существует.

После оплаты покупатель возвращается в ваш магазин. Заказ отмечается оплаченным только после подтверждения Cashfree: подписанным вебхуком или серверным запросом к Cashfree, когда покупатель возвращается. Тогда заказ создаётся, и покупатель видит стандартную страницу подтверждения заказа. Возврат работает и в другом браузере, например когда покупатель возвращается из приложения UPI. Если банк ещё не подтвердил платёж, страница Payment confirmation показывает Your payment is being processed by the bank. We will update the order as soon as Cashfree confirms it — please do not pay again. и кнопку Check again; вебхук создаёт заказ, как только банк подтверждает платёж.

Если платёж не удался или покупатель ушёл со страницы Cashfree без оплаты, он возвращается на оформление заказа и видит The Cashfree payment was not completed. Please try again or choose another payment method. Корзина сохраняется. Открытый платёж Cashfree используется повторно, когда покупатель пробует снова. Если сумма корзины изменилась или сессия скоро истечёт, старый заказ в Cashfree закрывается и создаётся новый, поэтому корзину нельзя оплатить дважды. Если корзина уже оплачена в Cashfree, но не записана, следующая попытка создаёт заказ вместо повторного списания.

Если Cashfree не может начать платёж, покупатель остаётся на оформлении заказа и видит We could not start the Cashfree payment. Please try again or choose another payment method. Техническая причина записывается в журнал. Сумма корзины ниже минимума Cashfree (1 единица валюты; 0,01 для BHD, JOD, KWD, OMR и 0,1 для TND) не может быть оплачена через Cashfree, и для такой корзины способ оплаты не показывается.

Вебхук работает, пока магазин находится в режиме обслуживания, и не блокируется ограничением по странам вашего магазина.

Модуль принимает только разовые платежи на странице оплаты Cashfree. В нём нет сохранённых карт, подписок и регулярных платежей, раздельной авторизации и списания, виджета предложений Cashfree, наложенного платежа (COD) и платёжных ссылок через Cashfree, а также конвертации валют: корзина списывается в валюте корзины.

Заказы и возвраты

Order statuses

No order yet: покупатель был отправлен в Cashfree и не оплатил, платёж не удался или платёж ещё ожидает ответа банка. Существует только корзина.

Payment accepted: платёж подтверждён. Платёж записывается с ID платежа Cashfree в качестве ID транзакции, а примечание показывает ID транзакции и группу способа оплаты (например, upi или credit_card).

Cashfree payment on hold: Cashfree сообщил об оплаченной сумме или валюте, которые отличаются от суммы корзины (например, корзина была изменена в другой вкладке после начала платежа). В примечании указаны ожидаемая и полученная сумма и ID транзакции. Проверьте платёж в панели Cashfree, затем выполните заказ или сделайте возврат платежа.

Refunded: платёж полностью возвращён через модуль.

Платёж, поступивший после отмены заказа, всё равно записывается, и заказ снова становится оплаченным, потому что деньги были списаны. Оплаченный заказ никогда не возвращается в неоплаченный из-за более позднего неудачного платежа.

Cashfree payment block

На странице заказа есть блок Cashfree payment с ID транзакции, заказом Cashfree, статусом платежа, оплаченной и возвращённой суммами, значком Sandbox для платежей в sandbox, историей возвратов и Cashfree notes заказа.

Refunds

В блоке Cashfree payment введите сумму (подставляется сумма, которая ещё не возвращена), при желании причину, и нажмите Refund via Cashfree. Подтвердите вопрос Refund this amount through Cashfree? This cannot be undone. Поддерживаются полные и частичные возвраты. Нужно право редактировать заказы; доступ к страницам модулей не требуется. Возвраты выполняются в сумме и валюте, которые списал Cashfree, поэтому после расхождения суммы можно вернуть не больше того, что покупатель фактически заплатил, а не сумму заказа. Возврат отправляется в оплаченный заказ Cashfree, в той среде (sandbox или рабочей), в которой был сделан платёж, поэтому должны быть заполнены ключи этой среды. Если Cashfree не принимает возврат или сообщает, что он отменён или отклонён, в блоке появляется ошибка и возврат не записывается. Начатый возврат добавляется в историю возвратов и примечания с ID возврата, суммой и статусом. Полный возврат переводит заказ в статус Refunded; частичный возврат статус не меняет. Возвраты доступны после подтверждения платежа Cashfree.

Окончательный статус возврата приходит через вебхук возврата и добавляется в примечания. Модуль не создаёт кредитных накладных. Стандартные кнопки возврата PrestaShop на странице заказа не возвращают деньги через Cashfree.

Лицензионный ключ

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

Без активного ключа Cashfree не показывается покупателям на оформлении заказа. Если оплата всё же начата, покупатель видит This payment method is not available. Please choose another one. Витрина PrestaShop не знает, что вы вошли в админ-панель, поэтому способ оплаты скрыт и для вас: настроить модуль можно до покупки ключа, но протестировать его на оформлении заказа нельзя. Напоминание появляется в Modules > Module Manager на вкладке Alerts. Существующие заказы не затрагиваются: уже начатые платежи по-прежнему подтверждаются, и возвраты работают.

Когда лицензия истекает, модуль продолжает работать, но для обновлений и поддержки нужно продление. Статус автоматически проверяется снова, пока вы работаете в админ-панели: раз в день в первые 14 дней после ввода ключа, затем раз в неделю. Cron-задача не нужна. Удаление или сброс модуля всегда удаляет лицензионный ключ и статус лицензии.

Устранение неполадок

Cashfree не появляется на оформлении заказа: проверьте, что лицензия активна, что Enable/Disable включено и что для текущего режима заполнены ключи: Sandbox App ID и Sandbox Secret Key в тестовом режиме, App ID и Secret Key в рабочем. Страница настроек показывает предупреждение, когда ключи не заполнены. Способ оплаты также скрывается, если сумма корзины ниже минимума Cashfree. В разделе Payment > Preferences проверьте, разрешён ли модуль для валюты корзины, страны покупателя и группы покупателя.

Платёж прошёл, но заказ не создан: вебхук не работает. Проверьте, что ваш магазин использует HTTPS, что URL в Developers > Webhooks точно совпадает с показанным в Webhook URL и что выбраны события Payment. Проверьте, что Secret Key в настройках относится к той среде, в которой был сделан платёж. Панель Cashfree показывает ответ вашего магазина на каждый вебхук. Заказ также создаётся, когда покупатель возвращается в магазин после оплаты, и при следующей попытке оплаты той же корзины.

Вебхук отвечает Missing signature или Invalid signature: вызов не содержал действительной подписи Cashfree, либо Secret Key в настройках не соответствует среде, в которой был сделан платёж. Проверьте, что ключи sandbox и рабочей среды не перепутаны местами.

Вебхук отвечает Ignored: вебхук подписан правильно, но относится к платежу, который начал не этот магазин, например другой магазин на той же учётной записи Cashfree. Задайте каждому магазину свой Order ID prefix.

Вебхук отвечает Busy, retry later: заказ в этот момент создавал другой запрос, либо заказ не удалось создать (например, модуль отключён). Cashfree повторит вебхук. Включите Debug log, чтобы увидеть причину.

Покупатель видит The Cashfree payment page could not be loaded: скрипт Cashfree не удалось загрузить в браузере, например из-за блокировщика. Покупатель может снова нажать Pay Now или Choose another payment method.

Покупатель видит We could not start the Cashfree payment: посмотрите поле Log на странице модуля. Типичные причины — неверные ключи для выбранного режима или валюта, не включённая для вашей учётной записи Cashfree.

Покупатель видит We could not verify the payment: ссылка возврата не совпала с корзиной. Если деньги списаны, вебхук всё равно создаст заказ. Проверьте платёж в панели Cashfree, прежде чем покупатель заплатит снова.

Заказ в статусе Cashfree payment on hold после оплаты: прочитайте примечания в блоке Cashfree payment (см. Статусы заказа), затем выполните заказ или сделайте возврат платежа.

Возврат не проходит с сообщением о тестовом или рабочем режиме: платёж был сделан в этой среде, а её API-ключи не заполнены. Введите их и повторите попытку.

Удаление

Перейдите в Modules > Module Manager, откройте меню рядом с VibeFox Cashfree Payments и выберите Uninstall. Лицензионный ключ и статус лицензии этого модуля всегда удаляются. Если Delete Data on Uninstall включено, настройки Cashfree и журнал удаляются. Если выключено, все настройки сохраняются для последующей переустановки. Транзакции и возвраты Cashfree и статус заказа Cashfree payment on hold всегда сохраняются, поэтому заказы, оплаченные раньше, можно вернуть и после переустановки. Существующие заказы сохраняют свои платёжные примечания и ID транзакций.

Cashfree — товарный знак его правообладателя. Этот модуль не связан с Cashfree и не одобрен Cashfree.