VibeFox Cashfree for PrestaShop — Help

Requirements

PrestaShop: 8.0 to 9.x.

PHP: 8.0 or later. The module refuses to install on older PHP versions.

HTTPS: Cashfree delivers webhooks only to https:// URLs. Without HTTPS payments are still confirmed when the customer returns to the shop, 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 cart currency must be enabled for your Cashfree account.

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

Installation

1. In the back office go to Modules > Module Manager and click Upload a module. Choose the module ZIP file.

2. When the upload finishes, click Configure, or find VibeFox Cashfree Payments in the module list later and click Configure.

3. Paste your VibeFox license key into License key in the license block at the top of the Configure page and click Activate (see License key).

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

5. When ready, enter the live App ID and Secret Key, turn off Sandbox Mode and click Save.

On install the module creates the order status Cashfree payment on hold. PrestaShop offers a new payment module for all currencies, countries and customer groups. You can limit them in Payment > Preferences.

Configuration

All settings are on the module page: Modules > Module Manager > VibeFox Cashfree Payments > Configure. Each section has its own Save button, which saves the whole page. Above the fields the page explains that the order is created only after Cashfree confirms the payment. 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 payment method without the keys of the selected mode, a warning tells you that it stays hidden at checkout until they are set.

Cashfree Payments

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

Title: the payment method name customers see at checkout. It is also the payment method name stored in the order. Default: Cashfree Payments. Required.

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.

Sandbox Mode: uses the Cashfree sandbox for testing. No real money is charged, and the checkout shows SANDBOX MODE - no real payments will be processed. under the payment method. Default: on. Turn it off for live payments.

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

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

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

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

Saved Secret Keys are never shown again. The field stays empty and shows Saved — leave empty to keep it. Type a new value only to change it.

Clear saved secrets: tick a Secret Key and click Save to remove it. An empty field keeps the saved value.

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

Webhook

The webhook tells your shop that a payment was made, failed or was refunded. In the Cashfree Merchant Dashboard go to Developers > Webhooks and add the URL shown in Webhook URL in this section, with the Payment and Refund events. With friendly URLs it looks like https://your-shop/module/wcp_cashfree_payment/webhook. Copy the URL exactly as the settings show it. On an HTTPS shop the module also passes this URL to Cashfree with every payment. If your shop does not use HTTPS, this section shows a warning.

The module handles these events (they are also listed in this section):

Cashfree signs every webhook with your Secret Key. Webhooks without a valid signature are rejected. A webhook must be signed with the Secret Key of the environment the payment was made in, so a sandbox key never confirms a live payment. Signed webhooks for payments that were not started by this shop (for example another shop on the same Cashfree account) are acknowledged and ignored. Without the webhook, an order is created only when the customer comes back to the shop after paying. If the customer closes the browser after paying, only the webhook (or the next payment attempt for the same cart) can create the order.

Advanced

API Version: the Cashfree API version to use.

Order ID prefix: Cashfree order IDs are built as prefix + PrestaShop cart ID; a new attempt for the same cart gets a number at the end (for example 123-2). Leave it empty to use the automatic prefix of this shop, shown in the field description. Use a different prefix for every shop connected to the same Cashfree account. Letters, digits, "_" and "-" only, up to 20 characters. Other characters are removed on save with a warning.

Debug log: errors are always logged. When on, Cashfree API calls and webhooks are also written to logs/cashfree_p_debug.log.php in the module folder. The file cannot be opened from the web. Keys and customer data are never logged. Default: off.

Log: shows the size and the latest entries of the log. Click Clear log to empty it.

Delete Data on Uninstall: when on, uninstalling the module removes the Cashfree settings and the module log. Orders, their Cashfree transactions and refunds and the order status Cashfree payment on hold always stay, so existing orders keep working. Default: off.

Checkout

At the payment step the customer chooses the payment method (by default Cashfree Payments) and confirms. The module creates a Cashfree order for the cart total in the cart currency and opens a payment page that 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. The customer's e-mail and billing phone are passed to Cashfree. No order exists yet at this point.

After paying, the customer returns to your shop. 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. The order is then created and the customer sees the standard order confirmation page. The return works in another browser too, for example when the customer comes back from a UPI app. If the bank has not confirmed the payment yet, a Payment confirmation 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. and a Check again button; the webhook creates the order as soon as the bank confirms the payment.

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

If Cashfree cannot start the payment, the customer stays at checkout with We could not start the Cashfree payment. Please try again or choose another payment method. The technical reason is written to the log. A cart 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, and the payment method is not shown for it.

The webhook works while the shop is in maintenance mode and is not blocked by the country restriction of your shop.

The module 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 cart is charged in the cart currency.

Orders and refunds

Order statuses

No order yet: the customer was sent to Cashfree and has not paid, the payment failed, or the payment is still pending at the bank. Only the cart exists.

Payment accepted: the payment was confirmed. The payment is recorded with the Cashfree payment ID as the transaction ID, and a note shows the transaction ID and the payment method group (for example upi or credit_card).

Cashfree payment on hold: Cashfree reported a paid amount or currency that differs from the cart total (for example, the cart was changed in another tab after the payment started). The note shows the expected and received amount and the transaction ID. Check the payment in the Cashfree dashboard, then fulfil the order or refund the payment.

Refunded: the payment was fully refunded through the module.

A payment that arrives after the order was cancelled is still recorded and the order becomes paid again, because the money was taken. A paid order is never changed back by a later failed payment.

Cashfree payment block

The order page shows a Cashfree payment block with the transaction ID, the Cashfree order, the payment status, the amount paid and refunded, a Sandbox badge for sandbox payments, the refund history and the Cashfree notes of the order.

Refunds

In the Cashfree payment block enter the amount (the amount not refunded yet is filled in), optionally a reason, and click Refund via Cashfree. Confirm the question Refund this amount through Cashfree? This cannot be undone. Full and partial refunds are supported. You need the right to edit orders; access to the Modules pages is not needed. Refunds are made in the amount and currency Cashfree charged, so after an amount mismatch you can refund up to what the customer actually paid, not the order total. 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, the block shows the error and no refund is recorded. A started refund is added to the refund history and the notes with its refund ID, amount and status. A full refund sets the order to Refunded; a partial refund does not change the status. Refunds are available once Cashfree has confirmed the payment.

The final refund status arrives by the refund webhook and is added to the notes. The module does not create credit slips. The standard PrestaShop refund buttons of the order page do not send money back through Cashfree.

License key

The module works with a VibeFox license key from vibefox.net. The license block License — VibeFox Cashfree Payments is the first block on Modules > Module Manager > VibeFox Cashfree Payments > Configure, above the settings. Paste the key into License key and click Activate. After that the block shows the key masked, the status (for example the date the license is active until and your domain) and the buttons Check now to check the status again, Change key to enter another key and Remove key to remove the key from this shop. Below them are the line Product: presta-payment-cashfree and the link Manage licenses and domains in your account, which opens your vibefox.net account. Only employees with the Configure permission for the module can change the key. The texts of the block follow the back office language (English and Russian are included).

If the key is not accepted, the block says why, for example Key not found, This key belongs to another product, Domain limit reached or License expired on a date. After the shop address changes, or after you free a domain slot in your account, click Check now. If the license server cannot be reached, the module keeps working on the last known status.

One key works on one domain: the domain of the main shop, also in a multistore setup. Removing the key from the shop 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. The PrestaShop storefront does not know that you are logged in to the back office, so the payment method is hidden for you too: you can set up the module before you buy a key, but not test it at checkout. A reminder appears in Modules > Module Manager on the Alerts tab. Existing orders are not affected: payments already started are still confirmed, and refunds work.

When a license expires, the module keeps working, but updates and support need a renewal. The status is checked again automatically while you work in the back office: once a day for the first 14 days after the key is entered, then once a week. No cron job is needed. Uninstalling or resetting the module always removes the license key and license status.

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 settings page shows a warning when the keys are missing. The payment method is also hidden when the cart total is below the Cashfree minimum. In Payment > Preferences check that the module is allowed for the cart currency, the customer's country and the customer's group.

The payment went through, but no order was created: the webhook is not working. Check that your shop uses HTTPS, that the URL in Developers > Webhooks is exactly the one shown in Webhook URL and that the Payment events are selected. Check that the Secret Key in the settings belongs to the environment the payment was made in. The Cashfree dashboard shows the answer of your shop for each webhook. The order is also created when the customer returns to the shop after paying, and on the next payment attempt for the same cart.

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 payment was made in. Check that the sandbox and live keys are not swapped.

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

Webhook answers Busy, retry later: the order was being created by another request at the same moment, or the order could not be created (for example, the module is disabled). Cashfree retries the webhook. Turn on Debug log to see the reason.

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: look at the Log field on the module page. Typical reasons are wrong keys for the selected mode or a currency that is not enabled for your Cashfree account.

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

Order is Cashfree payment on hold after payment: read the notes in the Cashfree payment block (see Order statuses), then fulfil the order or refund the payment.

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

Uninstall

Go to Modules > Module Manager, open the menu next to VibeFox Cashfree Payments and choose Uninstall. The license key and license status of this module are always removed. If Delete Data on Uninstall is on, the Cashfree settings and the log are removed. If it is off, all settings are kept for a later re-install. The Cashfree transactions and refunds and the order status Cashfree payment on hold are always kept, so orders paid before can still be refunded after a re-install. Existing orders keep their payment notes and transaction IDs.

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