VibeFox Cashfree for OpenCart — Help

Requirements

OpenCart: 3.0.x (tested on 3.0.5.0) or 4.0.2 and later (tested on 4.1.0.3).

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

The download is one zip file with the packages for both OpenCart versions. Unpack it on your computer. It contains README.txt, the OpenCart 3 package wcp_cashfree_payment-oc3-(version).ocmod.zip and the OpenCart 4 package wcp_cashfree_payment.ocmod.zip. Install only the package for your OpenCart version. The license key is the same for both versions.

OpenCart 3

1. In the admin go to Extensions > Installer, click Upload and choose the file wcp_cashfree_payment-oc3-(version).ocmod.zip. The extension has no OCMOD modifications, so Extensions > Modifications does not need a refresh. Instead of the installer you can copy the contents of the upload folder of this package into the root folder of your store.

2. Go to Extensions > Extensions and choose the type Payments. Find VibeFox Cashfree Payments and click Install (the green + button). Your admin user needs the right to modify the payment extensions list.

3. Click Edit (the pencil button) to open the settings page. Paste your VibeFox license key into License key in the license block at the top of the 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.

OpenCart 4

1. In the admin go to Extensions > Installer, click Upload and choose the file wcp_cashfree_payment.ocmod.zip. Do not rename the file: OpenCart 4 takes the extension code from the file name, and a renamed package does not work.

2. The package appears in the list of installed extensions on the same page. Click Install (the green + button) next to it.

3. Go to Extensions > Extensions and choose the type Payments. Find VibeFox Cashfree Payments, click Install (the green + button), then Edit (the pencil button).

4. Enter the license key, the Cashfree keys and the webhook as in steps 3 to 5 for OpenCart 3. The settings page and its fields are the same in both versions. Only the webhook URL is different (see Webhook).

A new install starts with the payment method turned off and sandbox mode on.

Configuration

All settings are on the extension page: Extensions > Extensions > Payments > VibeFox Cashfree Payments > Edit. The sections are listed on the left; the Save button under the list saves the whole page. Above the settings the page explains that the order gets a status 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. Without the right to modify the extension the page shows the settings but cannot save them.

When you save, Title must not be empty (at most 128 characters), API Version must be one of the listed versions, Sort Order must be a whole number, Total a number of 0 or more, and the geo zone and order statuses must exist; otherwise nothing is saved. When you save an enabled payment method without the keys of the selected mode, the settings are saved with a warning 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 to the customer at the Confirm Order step, above the confirm button. Default: Pay securely via Card, UPI, Net Banking, Wallet via Cashfree.

Sort Order: the position of Cashfree among the payment methods at checkout. Leave it empty or enter a whole number.

Geo Zone: offer Cashfree only for payment addresses in the selected geo zone. Default: All zones. Geo zones are set up in System > Localisation > Geo Zones.

Total: the checkout total, in the default currency of the store, that an order must reach before Cashfree is offered. Leave it empty to offer Cashfree for any total. Totals below the Cashfree minimum of the currency (1 unit; 0.01 or 0.1 for three-decimal currencies) are never offered.

Mode and API keys

Get your App ID and Secret Key in the Cashfree Merchant Dashboard under Developers > API Keys (the page links there). Test and Production keys are different.

Sandbox Mode: uses the Cashfree sandbox for testing. No real money is charged, and the Confirm Order step and the payment page show SANDBOX MODE - no real payments will be processed. 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. To remove a saved key, tick Clear the saved value on save under the field and click Save.

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 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 Webhook URL in this section, with the Payment and Refund events. On OpenCart 3 it looks like https://your-store/index.php?route=extension/payment/wcp_cashfree_payment/webhook, on OpenCart 4 like https://your-store/index.php?route=extension/wcp_cashfree_payment/payment/wcp_cashfree_payment.webhook. It is built from the storefront address of your OpenCart installation. Copy the URL exactly as the settings show it. On an HTTPS store the extension also passes this URL to Cashfree with every payment. If your store does not use HTTPS, this section shows a warning.

The extension 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 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 (or the next payment attempt for the same cart) can confirm the order.

Orders

OpenCart creates the order at the Confirm Order step without a status (a missing order). The order gets a status only after Cashfree has confirmed the payment. A failed or abandoned payment leaves it without a status, and the cart is kept. Each field below lists your OpenCart order statuses.

Order Status After Payment: the status set after the payment is confirmed and the amount and currency match. Default: Processing.

On Hold (Review) Status: Cashfree reported a paid amount or currency that differs from the order total. A note shows the expected and received amount. Default: Pending, because OpenCart has no On hold status. You can create your own status in System > Localisation > Order Statuses and select it here.

Refunded Status: set after the payment is fully refunded from the order page. Default: Refunded.

Advanced

API Version: the Cashfree API version to use.

Order ID prefix: Cashfree order IDs are built as prefix + OpenCart order ID; a new attempt for the same order gets a number at the end (for example 123-2). Leave it empty to use the automatic prefix of this store, shown in the field description (OC, four letters derived from the store address and a hyphen). 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 warning.

Debug log: errors are always logged. When on, Cashfree API calls and webhooks are also written to cashfree_p_debug.log.php in the OpenCart logs folder (storage/logs). The file cannot be opened from the web, and at 5 MB it is rotated. 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 extension removes the Cashfree settings and the extension log. Orders and their Cashfree transactions and refunds are always kept. Default: off.

Import / Export

Export: Download JSON saves the settings as a JSON file. Secret keys are not exported.

Import: paste previously exported JSON and click Import to restore the settings. Saved secret keys are kept.

Checkout

At the Payment Method step the customer chooses the payment method (by default Cashfree Payments). At the Confirm Order step the customer sees your description and the note You will be redirected to the Cashfree checkout to pay securely (cards, UPI, net banking, wallets). OpenCart creates the order at this step, still without a status. When the customer clicks Confirm Order, the extension creates a Cashfree order for the order total in the order currency and opens a Cashfree 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 phone number are passed to Cashfree. On OpenCart 4 the customer picks the payment method with the Choose button of the payment method block, in the window Payment method options, and clicks Confirm Order at the bottom of the checkout page. OpenCart 4 does not ask for a phone number by default: if the order has none, the confirm block shows an optional Phone field (Optional: the phone number of the payer for Cashfree (UPI, OTP).). A wrong format gives Please enter a valid phone number (10 digits, or + and the country code) or leave the field empty. The number is remembered for the next attempt.

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. The order then gets its status the standard OpenCart way, with the usual order e-mails and stock update, and the customer sees the OpenCart order success 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 sets the order status as soon as the bank confirms the payment. On OpenCart 4 the browser does not send the store session when Cashfree sends the customer back, so the extension first shows a short page that opens the same return address again from your store: the customer keeps the cart and the login.

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. On OpenCart 4 the checkout messages are shown above the checkout page. The order stays without a status and the cart is kept. OpenCart 3 creates a new order every time the Confirm Order step is shown; OpenCart 4 keeps one order for the checkout and updates it, so the customer pays the same order again. An open Cashfree payment of the same order is reused when the amount is unchanged and more than five minutes are left; otherwise the old Cashfree order is closed and a new one is created. The open Cashfree payments of earlier orders of the same cart are closed too, so the cart cannot be paid twice. If the cart was already paid at Cashfree but not recorded, the next attempt confirms that payment instead of charging again. A cart that is already paid by another order is not charged again: the customer goes to the success page. If the same cart is still paid twice (for example in two browser tabs at once), the second order keeps no status and the paid order gets a note that the customer may have been charged twice, so you can refund it in the Cashfree dashboard.

OpenCart 4 keeps the order in the checkout until the success page is shown. If that order was closed meanwhile (for example cancelled) and Cashfree holds no money for it, the customer is sent back to the checkout with The Cashfree payment was not completed. Please try again or choose another payment method., and the next Confirm Order pays a new order of the cart. If the order already has a status and the cart has changed since (other products or quantities), the customer is sent back to the checkout with Your previous order has already been placed. Please confirm the order again: the current cart will be paid with a new order.

If Cashfree cannot start the payment, the customer stays at the Confirm Order step with We could not start the Cashfree payment. Please try again or choose another payment method. above the button. The technical reason is written to the log. An order total below the Cashfree minimum (1 unit of the currency; 0.01 for three-decimal currencies such as KWD and 0.1 for TND) cannot be paid with Cashfree, and the payment method is not shown for it.

The webhook also works while the store is in maintenance mode: OpenCart 3 lets payment extension requests through, and on OpenCart 4 the extension adds a startup action that lets the webhook and the customer's return through.

The extension 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

No status (missing order): the customer was sent to Cashfree and has not paid, the payment failed, or the payment is still pending at the bank. In Sales > Orders such orders are shown only with the filter Order Status set to Missing Orders.

Order Status After Payment (default Processing): the payment was confirmed. A note shows the Cashfree transaction ID and the payment method group (for example upi or credit_card).

On Hold (Review) Status (default Pending): Cashfree reported a paid amount or currency that differs from the order total. 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 Status (default Refunded): the payment was fully refunded through the extension.

A payment that arrives after you gave the waiting order a status by hand (for example Canceled) is still recorded, and the order becomes paid, because the money was taken; OpenCart notifies the customer of this change. A paid order is never changed back by a later failed payment, and a second payment for an already paid order does not change it.

Notes are entries in the order History that the customer does not see.

VibeFox Cashfree Payments tab

In Sales > Orders open an order paid with Cashfree. At the bottom of the order page, next to History and Additional, the VibeFox Cashfree Payments tab shows the Transaction ID with a Sandbox label for sandbox payments, the Cashfree order, the payment Status, the amounts Paid / refunded, the refund form, the refund history with the status of each refund and the Cashfree notes of the order. The tab is shown to users who have access to the extension.

Refunds

In the tab enter the Amount (the amount not refunded yet is filled in), optionally a Reason (optional), 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 modify the extension (set in System > Users > User Groups). 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 tab 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 Status without notifying the customer and without returning products to stock, like a manual status change. 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. Product returns in Sales > Returns do not send money back through Cashfree.

License key

The extension works with a VibeFox license key from vibefox.net. The license block License — VibeFox Cashfree Payments is the first block on Extensions > Extensions > Payments > VibeFox Cashfree Payments > Edit, 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 store. Below them are the line Product: opencart-payment-cashfree and the link Manage licenses and domains in your account, which opens your vibefox.net account. Only admin users with the Modify permission for the extension can change the key. The texts of the block follow the admin 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 store address changes, or after you free a domain slot in your account, click Check now. If the license server cannot be reached, the extension keeps working on the last known status.

One key works on one domain: the store address from the OpenCart configuration. Removing the key from the store 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. An admin user who is logged in to the admin in the same browser still sees the payment method in the store, marked (unlicensed — visible to admins only), so you can set up and test the extension before you buy a key. On OpenCart 4 this preview is not available: the store does not see the admin login, so without an active key the payment method is hidden for everybody. After you have opened the Edit page once, a reminder appears on the admin Dashboard. Close it with × to hide it for 7 days. Existing orders are not affected: payments already started are still confirmed, and refunds work.

When a license expires, the extension keeps working, but updates and support need a renewal. The status is checked again automatically when you open the admin Dashboard or the Edit page: once a day for the first 14 days after the key is entered, then once a week. No cron job is needed. Uninstalling the extension 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 order total is below the Cashfree minimum. Also check that the payment address is in the selected Geo Zone and that the order reaches the Total set in the settings.

The payment went through, but the order stays without a status: the webhook is not working. Check that your store 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 store for each webhook. The order also gets its status when the customer returns to the store 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 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 confirmed by another request at the same moment, or the order status could not be set. Cashfree retries the webhook. Turn on Debug log to see the reason.

The customer sees The Cashfree payment page could not be loaded. Please try again.: 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 extension page. Typical reasons are wrong keys for the selected mode or a currency that is not enabled for your Cashfree account.

The customer sees This payment method is not available. after Confirm Order: the checkout session no longer matches the order, or the payment method was turned off meanwhile. The customer reloads the checkout.

The customer sees Payment session not found. Please try again.: the payment page link does not belong to a payment of this store, or the Cashfree session has ended. The customer confirms the order again.

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

Order is in the review status after payment: read the notes in the VibeFox Cashfree Payments tab (see Order statuses), then fulfil the order or refund the payment.

No refund form in the tab: the tab says why: the payment is not confirmed yet, it is fully refunded, your user group has no right to modify the extension, or the API keys of the payment's environment are not set.

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 Extensions > Extensions, choose the type Payments and click Uninstall (the red − button) next to VibeFox Cashfree Payments. The license key and license status of this extension are always removed. OpenCart always removes its own settings of the extension: Enable/Disable, Sort Order, Geo Zone, Total and the order statuses of the Orders section, which return to their defaults on a re-install. On OpenCart 4 the events of the extension and its startup action, which lets the webhook through in maintenance mode, are removed too. If Delete Data on Uninstall is on, the other Cashfree settings (title, description, mode, keys, API version, order ID prefix, logging) and the log are removed. If it is off, they are kept for a later re-install. The Cashfree transactions and refunds are always kept, so orders paid before can still be refunded after a re-install. Existing orders keep their payment notes.

On OpenCart 4, to remove the files of the extension as well, go to Extensions > Installer after the uninstall and click Uninstall (the orange − button) next to VibeFox Cashfree Payments in the list of installed extensions, then Delete (the red bin button) to remove the uploaded package.

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