VibeFox Cashfree for WooCommerce — Помощь

Требования

WordPress: 5.8 или новее.

WooCommerce: 6.0 или новее, установлен и активен. Без него плагин не активируется.

PHP: 8.0 или новее.

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

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

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

Установка

1. В WordPress перейдите в Plugins > Add New > Upload Plugin, выберите ZIP-файл плагина и нажмите Install Now. Также можно загрузить папку wcp_cashfree_payment в /wp-content/plugins/ по FTP.

2. Нажмите Activate.

3. Откройте настройки: WooCommerce > Settings > Payments > Cashfree Payments > Manage или нажмите Settings под названием плагина на странице Plugins.

4. Введите лицензионный ключ VibeFox в блоке лицензии вверху страницы и нажмите Activate.

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

6. Когда будете готовы, введите рабочие App ID и Secret Key и снимите отметку с Sandbox Mode.

Настройка

Все настройки находятся на одной странице: WooCommerce > Settings > Payments > Cashfree Payments. Если способ оплаты включён, страница предупреждает, когда не заполнены API-ключи выбранного режима (тогда способ оплаты скрыт при оформлении заказа), и показывает Sandbox mode is on: customers see a test checkout and no real money is charged., пока включён тестовый режим. При сохранении включённого шлюза без ключей выбранного режима появляется сообщение об ошибке: способ оплаты остаётся скрытым при оформлении заказа, пока ключи не заполнены.

Общие

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

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

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

Режим и API-ключи

App ID и Secret Key можно получить в Cashfree Merchant Dashboard в разделе Developers > API Keys. Ключи тестовой и рабочей среды различаются; введите каждый в своём разделе.

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

Учётные данные тестовой среды

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

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

Рабочие учётные данные

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

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

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

Вебхук

Вебхук сообщает вашему магазину, что платёж выполнен, не удался или был возвращён. В Cashfree Merchant Dashboard перейдите в Developers > Webhooks и добавьте URL из этого раздела с событиями Payment и Refund. Он выглядит так: https://your-site/wc-api/cashfree_p/?action=webhook. На сайте с HTTPS плагин также передаёт этот URL в Cashfree с каждым заказом. Если ваш сайт не использует HTTPS, в этом разделе появится предупреждение.

Плагин обрабатывает следующие события:

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

Дополнительно

API Version: версия API Cashfree, которая используется.

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

Debug log: Log Cashfree API events for debugging. Ошибки записываются всегда. Если включено, вызовы API и вебхуки также пишутся в WooCommerce > Status > Logs, источник wcp_cashfree_payment. Ключи и данные покупателя никогда не записываются. По умолчанию: выключено.

Delete Data on Uninstall: Delete all plugin data when uninstalling. Если включено, удаление плагина удаляет настройки Cashfree, журналы плагина и ссылки Cashfree, сохранённые в заказах. Сами заказы сохраняются. По умолчанию: выключено.

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

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

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

Если платёж не прошёл или покупатель покинул страницу Cashfree, не заплатив, он возвращается на страницу Pay for order с сообщением 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 нельзя.

Способ оплаты работает в классическом оформлении заказа, в блоке «Оформление заказа» и на странице Pay for order. Он совместим с High-Performance Order Storage (HPOS) WooCommerce. Тексты для покупателя переведены на хинди.

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

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

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

Pending payment: покупатель отправлен в Cashfree и ещё не заплатил, либо платёж ещё ожидает подтверждения банка. Когда покупатель возвращается с ожидающим платежом, в примечании указано, что плагин ждёт вебхука Cashfree.

Processing: оплата подтверждена (заказы только с виртуальными загружаемыми товарами переходят в статус Выполнен — это стандартное поведение WooCommerce). В примечании к заказу показаны ID транзакции Cashfree и группа способа оплаты. ID транзакции заказа — это ID платежа Cashfree. Платёж, пришедший после отмены заказа, всё равно записывается, потому что деньги списаны.

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

Failed: платёж не прошёл или был отменён в Cashfree. В примечании показаны статус и причина Cashfree. Каждая следующая неудачная попытка добавляет одно примечание.

Оплаченный заказ никогда не меняется назад из-за последующего вебхука или возврата покупателя.

Возвраты

Откройте заказ, нажмите Refund, введите сумму и нажмите Refund via Cashfree Payments (на кнопке показано название способа оплаты). Поддерживаются полные и частичные возвраты. Возврат отправляется в оплаченный заказ Cashfree, в той среде (тестовой или рабочей), где он был оплачен, поэтому ключи этой среды должны быть заданы. Если Cashfree не принимает возврат или отмечает его как отменённый или отклонённый, WooCommerce показывает ошибку, и возврат не записывается. Начатый возврат добавляется в примечания к заказу с ID возврата, суммой и статусом. Окончательный статус приходит вебхуком возврата отдельным примечанием к заказу.

Вебхуки статуса возврата только добавляют примечания. Они автоматически не записываются как возвраты WooCommerce.

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

Плагин работает с лицензионным ключом VibeFox с vibefox.net. Блок лицензии находится вверху страницы WooCommerce > Settings > Payments > Cashfree Payments. Вставьте ключ в поле License key и нажмите Activate. В блоке показан статус, например дата окончания действия лицензии и ваш домен. Используйте Check now, чтобы проверить статус снова, Change key, чтобы ввести другой ключ, и Remove key, чтобы удалить его с этого сайта. Ссылка Manage licenses and domains in your account открывает ваш аккаунт на vibefox.net.

Один ключ работает на одном домене. Удаление ключа с сайта не освобождает слот домена. Освободите слот в вашем аккаунте на vibefox.net.

Без активного ключа Cashfree не показывается покупателям при оформлении заказа. Если оплата всё же начата, покупатель видит сообщение This payment method is not available. Please choose another one. Менеджеры магазина, вошедшие в систему, по-прежнему видят способ оплаты с пометкой (unlicensed — visible to admins only), чтобы вы могли настроить и протестировать плагин до покупки ключа. Напоминание появляется на странице Plugins и на страницах WooCommerce. Существующие заказы не затрагиваются: уже начатые платежи по-прежнему подтверждаются, а возвраты работают.

Когда срок лицензии истекает, плагин продолжает работать, но для обновлений и поддержки нужно продление. Статус автоматически проверяется снова в фоновом режиме.

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

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

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

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

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

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

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

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

Покупатель видит The minimum amount for a Cashfree payment is …: сумма заказа ниже минимума Cashfree для валюты.

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

Заказ в статусе On hold после оплаты: прочитайте примечание к заказу. Оплаченная сумма или валюта отличались от заказа. Завершите заказ или сделайте возврат платежа.

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

Блок лицензии показывает ошибку: следуйте сообщению в блоке. Например, если ключ уже используется на другом домене, освободите слот в вашем аккаунте на vibefox.net и нажмите Check now. Если адрес сайта изменился, нажмите Check now, чтобы активировать ключ для нового домена. Если сервер лицензий недоступен, плагин продолжает работать по последнему известному статусу.

Удаление

Деактивация плагина сохраняет все данные. Чтобы удалить плагин, деактивируйте его и удалите на странице Plugins. Лицензионный ключ и статус лицензии этого плагина всегда удаляются. Настройки платёжного шлюза, данные Cashfree, сохранённые в заказах, и журналы удаляются, только если была включена опция Delete Data on Uninstall. Иначе они сохраняются для повторной установки. Существующие заказы сохраняют свои примечания об оплате и ID транзакций.

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