Cashfree Payments for ERPNext: Setup and User Guide

Cashfree Payments for ERPNext (technical name ki_erp_cashfree) connects the Cashfree payment gateway to ERPNext 16. Your customers pay Payment Requests, Sales Orders, Sales Invoices and Webshop orders on the Cashfree checkout. ERPNext verifies every payment with Cashfree and posts it automatically.

The app is free and open source under the MIT licence. You can get it from the KalvyAI store page.

This guide covers what the app does, who it is for, installation, setup, each main feature, tips, limitations and common questions.

What the app is for

The app lets you collect online payments in ERPNext without manual entry. The flow is:

1. You send a Payment Request from a Sales Order or Sales Invoice.
2. Your customer opens the link and pays on the hosted Cashfree checkout using UPI, credit or debit card, net banking, a wallet, Pay Later or cardless EMI.
3. The app reads the payment result from the Cashfree API and checks the amount and currency.
4. The Payment Request is marked Paid and a Payment Entry is created against the order or invoice.

The browser is never trusted for the payment result. Signed webhooks and an hourly check catch payments that finish after the customer closes the browser.

Who it helps

• Business owners who invoice customers in India and want UPI, card and net banking payments recorded in ERPNext without retyping them.
• Accounts teams who reconcile payments by hand today. Each verified payment creates its own Payment Entry against the right document.
• ERP admins who need a gateway that keeps working when emailed links are opened days later, or when webhooks cannot reach the site.
• Webshop owners who want customers to pay their own orders from the order page, even if checkout used Cash on Delivery.
• Developers who want to read or extend the code. The source is in a public GitHub repository under the MIT licence.

Requirements

Before you install, make sure you have:

• ERPNext 16 (Frappe 16). Version 15 and older are not supported.
• The Frappe Payments app installed on the site.
• A Cashfree merchant account. Use Sandbox for testing and Production for live payments.
• An HTTPS address for the site, so Cashfree can send webhooks.
• The scheduler enabled, for the hourly safety check.
• The Webshop app, only if you want the Webshop Pay button.

Installation

You can buy and install the app from the store page. On a self-hosted bench, install it from the command line.

1. Make sure the Frappe Payments app is already installed on your site. [CHECK: install commands and branch for the Payments app on Frappe 16]
2. Get the app and install it on your site:

bench get-app https://github.com/Kalvyai-erpnext/ki_erp_cashfree --branch version-16
bench --site <site> install-app ki_erp_cashfree

3. Enable the scheduler so the hourly check can run:

bench enable-scheduler

Replace <site> with your site name, for example erp.example.com.

Setup

Step 1: Enter your Cashfree keys

1. Open Cashfree Settings in ERPNext. [CHECK: menu path or search term for Cashfree Settings]
2. Choose Sandbox or Production.
3. Enter the App ID and Secret Key from your Cashfree dashboard.
4. Save.
5. Click Test Connection to confirm the keys work.

Start with Sandbox keys. Switch to Production keys only after a full test.

Step 2: Add the webhook in Cashfree

Webhooks let Cashfree tell ERPNext about payments that finish after the customer leaves the checkout.

1. In Cashfree Settings, copy the Webhook URL.
2. In the Cashfree dashboard, go to Developers > Webhooks.
3. Add the copied URL for payment events.
4. Save the webhook in Cashfree.

The site must be reachable over HTTPS for this to work.

Step 3: Set a fallback mobile number

Cashfree needs a mobile number for every payment. If a customer record has no mobile number, the app uses the fallback number you set in Cashfree Settings. [CHECK: exact field label for the fallback mobile number]

Step 4: Confirm the gateway account

Payment Requests use the Cashfree - INR payment gateway account. Check that it exists and is linked to the right payment account before you send your first request. [CHECK: whether the Cashfree - INR gateway account is created automatically or must be set up manually, and where]

Step 5: Run a Sandbox test

1. Create a test Sales Order or Sales Invoice.
2. Send a Payment Request using the Cashfree - INR gateway account (see below).
3. Open the link and complete a payment. Cashfree Sandbox simulates both successful and failed payments.
4. Confirm the Payment Request shows Paid and a Payment Entry exists against the document.
5. Repeat with a failed payment and confirm nothing is marked paid.

Using the app

Send a Payment Request

1. Open a submitted Sales Order or Sales Invoice.
2. Create a Payment Request from it. [CHECK: exact button and menu label in ERPNext 16]
3. Select the Cashfree - INR payment gateway account.
4. Save and send the request to the customer.

Each Payment Request uses one gateway. The customer does not choose between gateways on the checkout.

How the customer pays

1. The customer opens the payment link.
2. The app creates the Cashfree order at that moment and opens the hosted Cashfree checkout.
3. The customer pays with any available method: UPI, credit or debit card, net banking, wallet, Pay Later or cardless EMI.
4. The customer returns to your site when the payment is done.

Guest pay links work the same way. The customer does not need to log in.

How payments are verified and posted

The app does not accept a payment result from the browser. When a payment completes:

1. The app reads the payment status from the Cashfree API.
2. It checks that the amount and currency match the Payment Request.
3. Only if both match, it marks the Payment Request as Paid.
4. It creates the Payment Entry against the Sales Order or Sales Invoice.

This protects you from tampered return URLs and partial amounts being treated as full payment. It also applies to guest pay links.

Payments finished after the browser closes

Customers sometimes pay and then close the tab before returning to your site. The app has three ways to catch these payments:

• Signed webhooks. Cashfree sends a payment event to your Webhook URL. The app checks the HMAC-SHA256 signature and the timestamp before acting on it.
• Hourly safety check. Every hour, the app re-checks unpaid orders from the last 72 hours with Cashfree. This covers sites that webhooks cannot reach. It needs the scheduler enabled.
• Check Status button. You can check any Payment Request by hand (see below).

Links that do not expire

Because the Cashfree order is created only when the customer opens the link, a link sent by email keeps working even if it is opened days later. If the customer opens the link again or retries a payment, the app reuses the active Cashfree order instead of creating a new one.

Check Status button

Use this when a customer says they paid but the Payment Request is not yet marked Paid.

1. Open the Payment Request.
2. Click Check Status.
3. The app reads the latest result from Cashfree. If the payment is confirmed and the amount and currency match, the request is marked Paid and the Payment Entry is created.

You can use this button at any time.

Webshop Pay button

If the Webshop app is installed, customers can pay their own orders from the order page.

1. The customer logs in to your Webshop and opens the order.
2. They click Pay.
3. They complete payment on the Cashfree checkout.
4. The payment is verified and posted like any other Cashfree payment.

This works even when the original Webshop checkout used another method, such as Cash on Delivery. To hand the Pay button to another gateway app, turn off Use Cashfree for the Webshop Pay Button. [CHECK: where this setting is located]

Tips

• Test every path in Sandbox first: success, failure, closing the browser after paying, and opening an old emailed link.
• Keep the scheduler on. Without it, the hourly check does not run. If webhooks fail and the scheduler is off, paid orders stay unpaid until someone clicks Check Status.
• Set the fallback mobile number early. Payments can fail for customers without a mobile number on file.
• Keep Sandbox and Production keys separate. Confirm the mode in Cashfree Settings before going live, then run Test Connection again.
• Re-check the webhook after moving domains. If your site address changes, copy the new Webhook URL into the Cashfree dashboard.

Limitations

• ERPNext 16 only. Versions 15 and older are not supported.
• One Cashfree account per site.
• Refunds are made from the Cashfree dashboard, not from ERPNext.
• Cashfree needs a mobile number for every payment. Set a fallback number in Cashfree Settings.
• Currencies other than INR need international payments enabled on your Cashfree account.
• Customers do not choose between gateways. Each Payment Request uses one gateway.

Specifications

FAQ

Is it free?

Yes. The app is free and open source under the MIT licence. Cashfree charges its own transaction fees.

What if the customer closes the browser after paying?

The signed webhook records the payment. Without webhooks, the hourly check or the Check Status button picks it up.

Can I test without real money?

Yes. Use Sandbox keys from the Cashfree dashboard. Cashfree simulates successful and failed payments.

Does it work with another gateway app, such as PayU?

Yes. Both can be installed. Turn off Use Cashfree for the Webshop Pay Button to hand the Pay button to the other app.

Can it refund payments?

Not yet. Make refunds from the Cashfree dashboard.

Can I use more than one Cashfree account?

No. The app supports one Cashfree account per site.

Does it work on ERPNext 15?

No. The app supports ERPNext 16 only.

How KalvyAI can help

KalvyAI builds and connects Odoo, ERPNext and Shopify systems. We can install and configure Cashfree Payments for ERPNext, set up webhooks and the scheduler, test your payment flows in Sandbox, and help you move to Production. If you need payment collection connected to wider workflows, including AI agents that work inside ERPNext with human approvals, budgets and an audit trail, we can help with that too.

Get the app from the store page, or contact us to talk about your setup.