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., поки ввімкнено режим sandbox. Коли ви зберігаєте увімкнений шлюз без ключів вибраного режиму, повідомлення про помилку вказує, що спосіб оплати залишатиметься прихованим на оформленні замовлення, доки ключі не буде введено.

Загальні

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

Sandbox App ID: App ID вашого тестового середовища Cashfree.

Sandbox Secret Key: Secret Key вашого тестового середовища Cashfree.

Робочі облікові дані

App ID: App ID вашого робочого середовища Cashfree.

Secret Key: Secret Key вашого робочого середовища Cashfree.

Замовлення зберігають середовище, в якому були створені. Їхні вебхуки перевіряються, а повернення надсилаються з ключами цього середовища, тож залишайте ключі sandbox заповненими, доки замовлення в sandbox не буде завершено після переходу на робочий режим.

Вебхук

Вебхук повідомляє вашому магазину, що платіж проведено, невдалий або повернено. У Cashfree Merchant Dashboard перейдіть до Developers > Webhooks і додайте адресу, яку показано в цьому розділі, з подіями Payment і Refund. Вона має вигляд https://your-site/wc-api/cashfree_p/?action=webhook. На сайті з HTTPS плагін також передає цю адресу 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 не можна.

Спосіб оплати працює в класичному оформленні замовлення, у блоці Checkout і на сторінці Pay for order. Він сумісний із WooCommerce High-Performance Order Storage (HPOS). Тексти для покупця перекладено на гінді.

Плагін приймає разові платежі лише на сторінці оформлення Cashfree. Він не має збережених карток, підписок чи регулярних платежів, окремих авторизації та захоплення, віджета пропозицій Cashfree, 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, у тому середовищі (sandbox або робочому), в якому його було оплачено, тож ключі цього середовища мають бути заповнені. Якщо 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 у режимі sandbox, App ID і Secret Key у робочому режимі. Спосіб оплати також приховується, коли сума замовлення менша за мінімум Cashfree. Сторінка налаштувань показує попередження, коли ключів бракує.

Платіж пройшов, але замовлення залишається Pending payment: вебхук не працює. Перевірте, що ваш сайт використовує HTTPS, що адреса в Developers > Webhooks точно збігається з тією, що показана в налаштуваннях, і що вибрано події Payment. Перевірте, що Secret Key у налаштуваннях належить до того середовища, в якому було оплачено замовлення. Замовлення також підтверджується, коли покупець після оплати повертається до магазину, і під час наступної спроби оплати.

Webhook answers Missing signature or Invalid signature: виклик не містив дійсного підпису Cashfree, або Secret Key у налаштуваннях не збігається із середовищем, у якому створено замовлення. Cashfree повторює вебхук.

Webhook answers Ignored: вебхук підписано правильно, але він належить замовленню, створеному не цим магазином, наприклад іншим магазином в тому самому обліковому записі Cashfree. Дайте кожному магазину власний Order ID prefix.

Webhook answers 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, перш ніж покупець заплатить знову.

Order is On hold after payment: прочитайте примітку до замовлення. Сума або валюта платежу не відповідали замовленню. Завершіть замовлення або поверніть платіж.

Refund fails with a message about sandbox or live mode: замовлення було оплачено в цьому середовищі, а його ключі API не заповнені. Введіть їх і повторіть спробу.

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

Видалення

Деактивація плагіна зберігає всі дані. Щоб видалити його, деактивуйте та видаліть на сторінці Plugins. Ліцензійний ключ і статус ліцензії цього плагіна завжди видаляються. Налаштування шлюзу, дані Cashfree, збережені в замовленнях, і журнали видаляються лише тоді, коли було увімкнено Delete Data on Uninstall. Інакше вони зберігаються для повторного встановлення. Існуючі замовлення зберігають свої примітки про оплату та ID транзакцій.

Cashfree є товарним знаком відповідного власника. Цей плагін не пов'язаний із компанією Cashfree і не схвалений нею.