VibeFox Cashfree for WooCommerce — Help

Requirements

WordPress: 5.8 or later.

WooCommerce: 6.0 or later, installed and active. The plugin refuses to activate without it.

PHP: 8.0 or later.

HTTPS: Cashfree delivers webhooks only to https:// URLs. Without HTTPS payments are still confirmed when the customer returns to the store, but enable HTTPS before going live.

Cashfree account: you need the App ID and Secret Key of your Cashfree account, separately for the test (sandbox) and the production environment, and a webhook in the Cashfree Merchant Dashboard (see Configuration). The Secret Key is also used to verify webhooks, so there is no separate webhook secret. The order currency must be enabled for your Cashfree account.

VibeFox license key: bought on vibefox.net. One key works on one domain.

Installation

1. In WordPress go to Plugins > Add New > Upload Plugin, choose the plugin ZIP file and click Install Now. You can also upload the wcp_cashfree_payment folder to /wp-content/plugins/ by FTP.

2. Click Activate.

3. Open the settings: WooCommerce > Settings > Payments > Cashfree Payments > Manage, or click Settings under the plugin name on the Plugins page.

4. Enter your VibeFox license key in the license block at the top of the page and click Activate.

5. Enter the Sandbox App ID and Sandbox Secret Key, add the webhook in the Cashfree Merchant Dashboard (see Configuration), turn on Enable/Disable and test a payment.

6. When ready, enter the live App ID and Secret Key and untick Sandbox Mode.

Configuration

All settings are on one page: WooCommerce > Settings > Payments > Cashfree Payments. When the payment method is enabled, the page warns you if the API keys of the selected mode are missing (the payment method is then hidden at checkout) and shows Sandbox mode is on: customers see a test checkout and no real money is charged. while sandbox mode is on. When you save an enabled gateway without the keys of the selected mode, an error message tells you that the payment method stays hidden at checkout until they are set.

General

Enable/Disable: Enable Cashfree Payments turns the payment method on or off. Default: off.

Title: the payment method name customers see at checkout. Default: Cashfree Payments.

Description: the text shown under the payment method at checkout. Default: Pay securely via Card, UPI, Net Banking, Wallet via Cashfree.

Mode and API keys

Get your App ID and Secret Key in the Cashfree Merchant Dashboard under Developers > API Keys. Test and Production keys are different; enter each in its own section.

Sandbox Mode: Enable Sandbox (test) mode uses the Cashfree sandbox for testing. No real money is charged, and the checkout shows SANDBOX MODE - no real payments will be processed. Default: on. Untick it for live payments.

Sandbox Credentials

Sandbox App ID: the App ID of your Cashfree test environment.

Sandbox Secret Key: the Secret Key of your Cashfree test environment.

Live Credentials

App ID: the App ID of your Cashfree production environment.

Secret Key: the Secret Key of your Cashfree production environment.

Orders keep the environment they were created in. Their webhooks are verified and their refunds are sent with the keys of that environment, so keep the sandbox keys filled in until sandbox orders are settled after switching to live.

Webhook

The webhook tells your store that a payment was made, failed or was refunded. In the Cashfree Merchant Dashboard go to Developers > Webhooks and add the URL shown in this section, with the Payment and Refund events. It looks like https://your-site/wc-api/cashfree_p/?action=webhook. On an HTTPS site the plugin also passes this URL to Cashfree with every order. If your site does not use HTTPS, this section shows a warning.

The plugin handles these events:

Cashfree signs every webhook with your Secret Key. Webhooks without a valid signature are rejected. Signed webhooks for orders that were not created by this store (for example another store on the same Cashfree account) are acknowledged and ignored. Without the webhook, an order is confirmed only when the customer comes back to the store after paying. If the customer closes the browser after paying, only the webhook can confirm the order.

Advanced

API Version: the Cashfree API version to use.

Order ID prefix: Cashfree order IDs are built as prefix + WooCommerce order ID; a repeated attempt gets a number at the end. Leave it empty to use the automatic prefix of this site, shown in the field description. Use a different prefix for every store connected to the same Cashfree account. Letters, digits, "_" and "-" only, up to 20 characters. Other characters are removed on save with a message.

Debug log: Log Cashfree API events for debugging. Errors are always logged. When on, API calls and webhooks are also written to WooCommerce > Status > Logs, source wcp_cashfree_payment. Keys and customer data are never logged. Default: off.

Delete Data on Uninstall: Delete all plugin data when uninstalling. When on, deleting the plugin removes the Cashfree settings, the plugin logs and the Cashfree references stored on orders. Orders themselves are kept. Default: off.

Checkout

The customer chooses the payment method (by default Cashfree Payments) and places the order. The plugin creates a Cashfree order for the order total in the order currency and opens the Pay for order page, which shows Redirecting to Cashfree for payment... and loads the Cashfree checkout. If it does not open by itself, the customer can click Pay Now. On the Cashfree checkout the customer pays with any method enabled in your Cashfree account, for example card, UPI, net banking or wallet.

After paying, the customer returns to your store. The order is marked paid only after Cashfree confirms it: by the signed webhook or by a server-side request to Cashfree when the customer comes back. If the bank has not confirmed the payment yet, the order received page shows Your payment is being processed by the bank. We will update the order as soon as Cashfree confirms it — please do not pay again.

If the payment fails or the customer leaves the Cashfree page without paying, the customer returns to the Pay for order page with The Cashfree payment was not completed. Please try again or choose another payment method. An open Cashfree payment is reused when the customer tries again. If the order total changed or the session is about to expire, the old Cashfree order is closed and a new one is created, so the order cannot be paid twice. If the order was already paid at Cashfree but not recorded, the next attempt records the payment instead of charging again.

If Cashfree cannot start the payment, the customer sees We could not start the Cashfree payment. Please try again or choose another payment method. The technical reason is written to the log. An order total below the Cashfree minimum (1 unit of the currency; 0.01 for BHD, JOD, KWD, OMR and 0.1 for TND) cannot be paid with Cashfree.

The payment method works on the classic checkout, on the Checkout block and on the Pay for order page. It is compatible with WooCommerce High-Performance Order Storage (HPOS). The customer-facing texts are translated into Hindi.

The plugin takes one-time payments on the Cashfree checkout only. It has no saved cards, subscriptions or recurring payments, no separate authorize and capture, no Cashfree offers widget, COD through Cashfree or payment links, and no currency conversion: the order is charged in the order currency.

Orders and refunds

Order statuses

Pending payment: the customer was sent to Cashfree and has not paid yet, or the payment is still pending at the bank. When the customer returns with a pending payment, a note says that the plugin is waiting for the Cashfree webhook.

Processing: the payment was confirmed (orders with only virtual downloadable products become Completed, the WooCommerce default). The order note shows the Cashfree transaction ID and the payment method group. The transaction ID of the order is the Cashfree payment ID. A payment that arrives after the order was cancelled is still recorded, because the money was taken.

On hold: Cashfree reported a paid amount or currency that differs from the order total. The order note shows the expected and received amount and the transaction ID. Check the payment in the Cashfree dashboard and complete or refund the order manually.

Failed: the payment failed or was cancelled at Cashfree. The note shows the Cashfree status and reason. Each further failed attempt adds one note.

A paid order is never changed back by a later webhook or return.

Refunds

Open the order, click Refund, enter the amount and click Refund via Cashfree Payments (the button shows the payment method title). Full and partial refunds are supported. The refund is sent to the Cashfree order that was paid, in the environment (sandbox or live) it was paid in, so the keys of that environment must be set. If Cashfree does not accept the refund, or reports it as cancelled or rejected, WooCommerce shows the error and no refund is recorded. A started refund is added to the order notes with its refund ID, amount and status. The final status arrives by the refund webhook as another order note.

Refund status webhooks are added as notes only. They are not recorded as WooCommerce refunds automatically.

License key

The plugin works with a VibeFox license key from vibefox.net. The license block is at the top of WooCommerce > Settings > Payments > Cashfree Payments. Paste the key into License key and click Activate. The block shows the status, for example the date the license is active until and your domain. Use Check now to check the status again, Change key to enter another key and Remove key to remove it from this site. The link Manage licenses and domains in your account opens your vibefox.net account.

One key works on one domain. Removing the key from a site does not free its domain slot. Free the slot in your vibefox.net account.

Without an active key, Cashfree is not shown to customers at checkout. If a payment is started anyway, the customer sees This payment method is not available. Please choose another one. Logged-in store managers still see the payment method, marked (unlicensed — visible to admins only), so you can set up and test the plugin before you buy a key. A reminder appears on the Plugins page and on WooCommerce pages. Existing orders are not affected: payments already started are still confirmed, and refunds work.

When a license expires, the plugin keeps working, but updates and support need a renewal. The status is checked again automatically in the background.

Troubleshooting

Cashfree does not appear at checkout: check that the license is active, Enable/Disable is on and the current mode has its keys: Sandbox App ID and Sandbox Secret Key in sandbox mode, App ID and Secret Key in live mode. The payment method is also hidden when the order total is below the Cashfree minimum. The settings page shows a warning when the keys are missing.

The payment went through, but the order stays Pending payment: the webhook is not working. Check that your site uses HTTPS, that the URL in Developers > Webhooks is exactly the one shown in the settings and that the Payment events are selected. Check that the Secret Key in the settings belongs to the environment the order was paid in. The order is also confirmed when the customer returns to the store after paying, and on the next payment attempt.

Webhook answers Missing signature or Invalid signature: the call did not carry a valid Cashfree signature, or the Secret Key in the settings does not match the environment the order was created in. Cashfree retries the webhook.

Webhook answers Ignored: the webhook is signed correctly but belongs to an order that was not created by this store, for example another store on the same Cashfree account. Give each store its own Order ID prefix.

Webhook answers Busy, retry later: the order was being processed by another request at the same moment. Cashfree retries the webhook.

The customer sees The Cashfree payment page could not be loaded: the Cashfree script could not be loaded in the browser, for example because of a blocker. The customer can click Pay Now again or Choose another payment method.

The customer sees We could not start the Cashfree payment: turn on Debug log and look at WooCommerce > Status > Logs, source wcp_cashfree_payment. Typical reasons are wrong keys for the selected mode or a currency that is not enabled for your Cashfree account.

The customer sees The minimum amount for a Cashfree payment is …: the order total is below the Cashfree minimum for the currency.

The customer sees We could not verify the payment: the return link did not match the order. If money was charged, the webhook still confirms the order. Check the payment in the Cashfree dashboard before the customer pays again.

Order is On hold after payment: read the order note. The paid amount or currency differed from the order. Complete the order or refund the payment.

Refund fails with a message about sandbox or live mode: the order was paid in that environment, and its API keys are not set. Enter them and try again.

The license block shows an error: follow the message in the block. For example, if the key is already used on another domain, free a slot in your vibefox.net account and click Check now. If the site address changed, click Check now to activate the key for the new domain. If the license server cannot be reached, the plugin keeps working on the last known status.

Uninstall

Deactivating the plugin keeps all data. To remove it, deactivate and delete it on the Plugins page. The license key and license status of this plugin are always removed. The gateway settings, the Cashfree data stored on orders and the logs are removed only if Delete Data on Uninstall was on. Otherwise they stay for a later re-install. Existing orders keep their payment notes and transaction IDs.

Cashfree is a trademark of its respective owner. This plugin is not affiliated with or endorsed by Cashfree.