VibeFox Cashfree for Adobe Commerce — सहायता

Requirements

Magento: Magento Open Source or Adobe Commerce 2.4.6 to 2.4.9, on your own server or hosting, on premises or on Adobe Commerce on cloud infrastructure. The module does not work with Adobe Commerce as a Cloud Service (the SaaS edition), which does not accept PHP modules.

PHP: 8.1 to 8.4, with the cURL and JSON extensions.

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 module is one ZIP file. It is a Composer package and can also be copied into app/code. Run the commands in the Magento root folder as the user that owns the Magento files.

1. With Composer: put the ZIP file into a folder that your project uses as a Composer "artifact" repository and run composer require vibefox/module-cashfree-payment. Without Composer: unpack the ZIP file into app/code/Vibefox/CashfreePayment/, so that registration.php is directly in that folder.

2. Run bin/magento module:enable Vibefox_CashfreePayment and bin/magento setup:upgrade. In production mode also run bin/magento setup:di:compile and bin/magento setup:static-content:deploy, then bin/magento cache:flush.

3. In the Admin go to Stores > Configuration > Sales > Payment Methods and open VibeFox Cashfree Payments. When the Magento PayPal module is enabled, the group is listed under Other Payment Methods. Paste your VibeFox license key into License key in the license block, the first row of the group, 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), set Enable to Yes, click Save Config and test a payment. When ready, enter the live App ID and Secret Key, set Sandbox Mode to No and click Save Config.

The module adds the Cashfree Payments payment method to the Magento checkout. It is off after installation (Enable = No). The module uses the standard Magento order states and creates no order statuses of its own. It creates three tables for the Cashfree payment attempts, refunds and processed webhook events.

Configuration

All settings are in Stores > Configuration > Sales > Payment Methods > VibeFox Cashfree Payments, in the standard Magento configuration form. Like other Magento settings, they can be changed for a website with the Scope switcher at the top of the page; Title and Description also for a store view. Remove data on uninstall is read from the Default Config only. Save Config saves the whole page. Amounts accept "9.99" and "9,99".

If a value is wrong, Magento shows an error and nothing on the page is saved: an empty Title or a title longer than 128 characters (Enter a title for the payment method (1 to 128 characters).); a Sort order that is not a whole number; a Minimum Order Total or Maximum Order Total that is not a number of 0 or greater (Order total must be a number, 0 or greater.).

When the payment method is enabled, the Webhook section warns you: Cashfree: App ID / Secret Key of the selected mode are empty. The payment method stays hidden at checkout., Cashfree: Sandbox mode is on. No real payment is taken. while sandbox mode is on, and Cashfree requires an HTTPS webhook URL. when your store does not use HTTPS. The warnings show the Default Config values.

Cashfree Payments

Enable: shows or hides Cashfree at checkout. It is shown only when the App ID and Secret Key of the current mode are set. Default: No.

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

Description: shown in the payment method list at checkout, when the customer selects Cashfree. Default: Pay securely via Card, UPI, Net Banking, Wallet via Cashfree.

Sort order: the position among the payment methods at checkout. A whole number.

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 payment is taken. under the payment method. Default: Yes. Set it to No 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.

Magento stores the Secret Keys encrypted and shows only a mask (******) after saving. Leave the mask as it is to keep the saved value, type a new value to change it. To delete a saved key, clear the field and click Save Config.

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.

Orders

Order status after payment: the order status set after a successful payment.

Amount or currency mismatches always go to On Hold.

Payment from Applicable Countries: All Allowed Countries offers Cashfree for every country your store allows, Specific Countries only for the countries below.

Payment from Specific Countries: offer Cashfree only for billing addresses in these countries.

Minimum Order Total: offer Cashfree only from this order total, in the base currency of your store. Empty means no minimum.

Maximum Order Total: offer Cashfree only up to this order total, in the base currency. Empty means no maximum.

Independently of these settings, 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, and the payment method is not shown for it.

Advanced

API Version: the Cashfree API version to use.

Order ID prefix: Cashfree order IDs are built as prefix + Magento cart (quote) ID; a new attempt for the same cart gets a number at the end (for example 123-2). Empty uses MG plus a store-specific prefix. Use a different prefix for every store connected to the same Cashfree account. Letters, digits, underscore and hyphen, up to 20 characters. Other characters are removed on save, and a warning shows the saved value: Cashfree: the order ID prefix may contain only letters, digits, underscore and hyphen (up to 20 characters).

Debug log: errors and warnings are always logged. When Yes, Cashfree API calls and webhooks are also written to var/log/cashfree_p_debug.log.php in the Magento folder. The file cannot be opened from the web. Keys and e-mail addresses are masked. Default: No.

Remove data on uninstall: when Yes, uninstalling the module with its data removes the Cashfree settings and the log (see Uninstall). Payment, refund and event history is always preserved. Default: No.

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 at the top of the Webhook section, with the Payment and Refund events. It looks like https://your-store/wcpcashfreepayment/webhook/index. Copy the URL exactly as the settings show it. On an HTTPS store the module also passes this URL to Cashfree with every payment.

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. The key is read for the store of the order. 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, or on the next payment attempt for the same cart.

Log

The Log row below the sections shows the size and the latest entries of the log. Click Clear log to empty it.

Checkout

At the payment step the customer chooses the payment method (by default Cashfree Payments) and sees the description and the note You will be redirected to Cashfree to complete the payment securely. After Place Order, Magento places the order in Pending Payment. No invoice is created and no order e-mail is sent yet. The module then creates a Cashfree order for the order total in the order currency and opens a 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, name and billing phone are passed to Cashfree, and the Cashfree order carries the note Magento order # and the order number.

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. Magento then creates the invoice with the Cashfree payment ID, sets the status from Order status after payment and sends the order e-mail. The customer sees the standard order success page. If Cashfree has not confirmed the payment yet, for example while the bank is still processing it, the success page shows Your payment is being confirmed by Cashfree. Please wait for confirmation. The webhook confirms the order as soon as it arrives. A customer who comes back in another browser, for example from a UPI app, lands on the home page. If the customer comes back without having started any payment on the Cashfree page, Cashfree has nothing to report yet: the success page shows the same notice and the order stays in Pending Payment until Cashfree reports the payment as failed or dropped, or the order is cancelled (see below).

If the payment fails or the customer leaves it, the order is cancelled (the stock goes back), the cart is restored and the customer sees The Cashfree payment was not completed. Please try again. in the cart. When the customer tries again, an open Cashfree payment of the same order is reused if the amount and mode are the same and it does not expire within 5 minutes. Otherwise the previous Cashfree order is closed and a new one is created, so the cart cannot be paid twice. If the previous Cashfree order turns out to be paid already, that payment is confirmed instead of a new one.

If Cashfree cannot start the payment, the order is cancelled, the cart is restored and 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. If the Cashfree script cannot be loaded in the browser, the page shows Could not load Cashfree. Please try again.

When an order in Pending Payment is cancelled in Magento, by you or by the Magento cron after the Pending Payment Order Lifetime (Stores > Configuration > Sales > Sales > Orders Cron Settings), its open Cashfree order is closed and can no longer be paid.

The module works with the standard Magento checkout. It 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. Cashfree is not offered for orders created in the Admin.

Orders and refunds

Order statuses

Pending Payment: the order was placed and the customer was sent to Cashfree, but Cashfree has not confirmed the payment yet, or the payment is still pending at the bank. There is no invoice.

Processing, Complete or On Hold: the payment was confirmed. The status follows Order status after payment. The invoice is created with the Cashfree payment ID as the transaction ID, and a note shows the payment and how it was confirmed (webhook, return or reconcile).

On Hold after a mismatch: Cashfree reported a different amount or currency than the order total. No invoice is created. The note shows the amount paid and the amount expected. Check the payment in the Cashfree dashboard, then fulfil the order or refund the payment there.

Late payment: the payment arrived after the order had been cancelled or put on hold. The order is not invoiced; a note asks you to check the stock and fulfil the order or refund the payment. An order that is not cancelled is put On Hold.

Canceled: the payment failed, the customer left it, the payment could not be started, or the order was cancelled in Magento.

Closed: the payment was fully refunded with a credit memo.

If a second payment arrives for an order that is already paid, or the same cart is paid again under another order, no second invoice is created. A note asks you to review and refund the duplicate in the Cashfree dashboard. The notes are order comments that the customer does not see.

Cashfree payment information

On the admin order page (Sales > Orders > View) the payment information shows the payment method title and, for the Cashfree payment, Cashfree environment (sandbox or production), Cashfree order, Cashfree payment (the payment ID) and Charged by Cashfree (the amount and currency Cashfree charged). The customer sees only the payment method title.

Refunds

Open the order, go to the Invoices tab, open the invoice and click Credit Memo. Choose the items and amounts to refund and click Refund. The money is sent back through Cashfree. Full and partial refunds are supported. A credit memo started from the order page instead of the invoice offers only Refund Offline, which does not send money back through Cashfree.

The refund is made in the order currency, up to the amount Cashfree charged minus the amounts already refunded. It 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, rejected or failed, Magento shows the error and the credit memo is not created. After a successful request Magento records the refund on the order with the Cashfree refund ID as the transaction ID. A full refund closes the order. Refunds are available once Cashfree has confirmed the payment and the order has an invoice.

The final refund status arrives by the refund webhook and is added to the order notes. If Cashfree rejects a refund later, the credit memo is not cancelled automatically: check the refund in the Cashfree dashboard. A payment with a different currency than the order, or without an invoice, cannot be refunded with a credit memo: refund it in the Cashfree dashboard.

License key

The module works with a VibeFox license key from vibefox.net. The license block License — VibeFox Cashfree Payments is the first row of the VibeFox Cashfree Payments group in Stores > Configuration > Sales > Payment Methods, 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: magento-payment-cashfree and the link Manage licenses and domains in your account, which opens your vibefox.net account. Only Admin users whose role allows the Payment Methods configuration section can change the key. The texts of the block follow the Admin interface locale (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 module keeps working on the last known status.

One key works on one domain: the domain of the default store view, also when the installation has several websites or stores. 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 order is cancelled, the cart is restored and the customer sees We could not start the Cashfree payment. Please try again or choose another payment method. The Magento storefront does not know that you are logged in to the Admin, 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 the System Messages of the Admin, with the links Enter the license key and Dismiss, which hides it for 7 days. 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: once a day for the first 14 days after the key is entered, then once a week, by the Magento cron and while you work in the Admin. Uninstalling the module with its data always removes the license key and license status.

Troubleshooting

Cashfree does not appear at checkout: check that the license is active and Enable is Yes for the website of the store, and that 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 Webhook section shows a warning when the keys are missing. Check Payment from Applicable Countries and Payment from Specific Countries against the customer's billing address, and Minimum Order Total and Maximum Order Total. The payment method is also hidden when the order total is below the Cashfree minimum.

The payment went through, but the order stays Pending Payment: the webhook is not working. Check that your store uses HTTPS, that the URL in Developers > Webhooks is exactly the one shown in the Webhook section 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 is also confirmed 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 updated by another request at the same moment, or an error occurred while the order was being confirmed. Cashfree retries the webhook. Turn on Debug log to see the reason.

The webhook URL shows Method not allowed in the browser: this is normal. The URL accepts only requests from Cashfree.

Webhooks fail while the store is in maintenance mode: Magento maintenance mode closes the whole site, the webhook URL too. Cashfree retries the webhook later, and the order is also confirmed when the customer returns.

The customer sees Could not load Cashfree or Could not open Cashfree: the Cashfree script could not be loaded or opened in the browser, for example because of a blocker. The customer can click Pay Now again.

The customer is back in the cart with We could not start the Cashfree payment: look at the Log row on the settings page. Typical reasons are wrong keys for the selected mode, a currency that is not enabled for your Cashfree account, or a missing license. The order of that attempt is cancelled.

The customer sees Invalid Cashfree return link: the return link did not match a payment of the store. 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 notes (see Order statuses), then fulfil the order or refund the payment.

Refund fails: Magento shows the reason, for example Invalid refund amount: at most the amount still refundable, The captured currency differs from the order. Refund it in Cashfree and review the order manually. or Cashfree refund failed: with the answer of Cashfree. If the payment was made in the other environment, check that the keys of that environment are set.

The Refund button is missing on the credit memo: start the credit memo from the invoice (Invoices tab), not from the order page. An order without an invoice (for example On Hold after a mismatch) cannot be refunded online; refund it in the Cashfree dashboard.

The settings page or the checkout looks unchanged after installing or updating: run bin/magento setup:upgrade and bin/magento cache:flush; in production mode also setup:di:compile and setup:static-content:deploy.

Uninstall

Deleting the module code alone removes nothing from the database: the license key and the settings stay. To remove the data, uninstall the module with the Magento command:

Installed with Composer: run bin/magento module:uninstall --remove-data Vibefox_CashfreePayment. It removes the data and the code.

Installed in app/code: run bin/magento module:uninstall --non-composer Vibefox_CashfreePayment to remove the data, then bin/magento module:disable Vibefox_CashfreePayment, delete the folder app/code/Vibefox/CashfreePayment and run bin/magento setup:upgrade.

The license key and license status are always removed. If Remove data on uninstall is Yes, the Cashfree settings and the log are removed too. If it is No, the settings are kept for a re-install. The Cashfree payment attempts, refunds and webhook events are always kept, so orders paid before can still be refunded after a re-install. Existing orders keep their invoices, payment notes and transaction IDs.

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