Cashfree Payment Gateway Integration

Collecting payment outside the ERP means the payment and the document it belongs to are connected by hand. Someone reads the payment from the gateway dashboard, finds the matching order or invoice and marks it paid and until that happens the order sits unconfirmed and the customer waits. Reconciliation done this way is slow at the best of times and unreliable when volume rises, because a payment that arrives without a clear reference has to be traced back to its order by amount and by timing.

With the integration the payment is initiated from the order itself and carries the order reference to the gateway, so the confirmation that comes back identifies exactly what was paid. The transaction is created in Odoo before the customer is sent to Cashfree, the state of that transaction follows the state of the payment at the gateway and the sale order or the invoice is settled by Odoo the moment the payment succeeds. Nothing is copied from a dashboard and a payment that fails or is abandoned is visible in Odoo with the reason rather than as an order that simply never progressed.

The connection to the gateway is configured on the payment provider record, which holds the App ID and the Secret Key issued from the Cashfree merchant dashboard. The Secret Key is stored as a password field so it is not displayed once saved and it serves two purposes, authenticating the outgoing API calls and verifying the signature on the notifications that Cashfree sends back.

The state of the provider selects the environment. Test Mode sends every call to the Cashfree sandbox and opens the checkout in sandbox mode and Enabled sends the same calls to production, so the implementation is validated against test credentials and moved to live credentials without a code change. The provider cannot be taken out of Disabled until both credentials are present, which prevents a half configured acquirer from being offered at checkout. The webhook endpoint that has to be registered in the Cashfree dashboard is shown on the form itself, so the person setting up the account does not have to be given the URL separately.

The payment methods offered at checkout are the ones Cashfree supports for the merchant account, covering cards, UPI, net banking, wallets, pay later and cardless EMI and they are activated on the provider when the module is installed so the acquirer is usable without each method being added by hand. The currency is restricted to the Indian rupee, which is what the gateway settles in and an order in any other currency does not offer Cashfree at checkout rather than failing after the customer has committed to pay.

The method the customer actually used is not assumed at the point of payment and is instead read from the gateway response, so a transaction paid by UPI is recorded as UPI and one paid by card is recorded as a card payment. This keeps the reporting on payment methods accurate without the customer being asked to declare in advance how they intend to pay.

When the customer chooses Cashfree and confirms, Odoo creates the transaction, then creates the corresponding order at Cashfree with the amount, the currency, the customer name, the email and the phone number and receives a payment session in return. The customer is taken to the Cashfree checkout for that session, completes the payment by whichever method they prefer and is returned to Odoo afterwards.

The transaction reference is used as the order identifier at the gateway, which is what ties the two records together for the whole of the payment life. Because Cashfree accepts only letters, digits, underscores and hyphens in that identifier and requires it to be unique for the merchant account, the reference is normalised before it is sent, so a payment raised from an invoice whose number contains slashes is accepted rather than rejected at creation and a repeated attempt on the same document does not collide with the earlier one.

The payment is confirmed in two independent ways, because neither on its own is sufficient. On return from the checkout, Odoo queries the gateway for the payments made against the order and settles the transaction from the answer, which is what allows the customer to be shown the result immediately instead of a page that says the payment is being processed. The status is taken from the gateway rather than from anything the browser carries back, so the confirmation cannot be influenced by the customer.

The webhook covers the case where the customer closes the browser, loses the connection or never returns. Cashfree posts the outcome of the payment to the endpoint configured on the merchant account and Odoo settles the transaction from that notification exactly as it would have on return. Every notification is checked against its signature before it is acted on, computed from the timestamp and the raw body with the Secret Key, so a request that does not carry a valid signature is rejected and cannot mark an order paid. A payment that succeeds after the customer has left is therefore still recognised and the two paths do not conflict because both act on the same transaction and the same gateway status.

A refund is issued from the payment in Odoo rather than from the gateway dashboard, in full or in part and is sent to Cashfree against the original order. Odoo creates the refund transaction, sends it with its own identifier so the outcome can be matched when it comes back and follows the refund through its states until the gateway reports it as settled. A refund started directly in the Cashfree dashboard is picked up from the refund notification and recorded in Odoo against the original payment, so the ledger reflects money returned to the customer whichever side the refund was raised from.

The sequence starts with the credentials. The App ID and the Secret Key are entered on the provider, the state is set to Test Mode for the sandbox and the webhook endpoint shown on the form is registered in the Cashfree merchant dashboard against the payment and refund events. A test payment is then taken end to end, which confirms that the order is created, that the checkout opens, that the return settles the transaction and that the notification arrives and is accepted. The state is moved to Enabled and the production credentials are entered once that is verified.

From that point the payment happens inside the normal sale flow. The customer reaches the checkout on the website or opens the invoice in the portal, chooses Cashfree and is taken to the gateway with the amount and the reference already set. On success the transaction is confirmed, the payment is registered and reconciled against the sale order or the invoice and the order proceeds without anyone acting on it. On failure or abandonment the transaction carries the reason returned by the gateway and the customer can attempt the payment again on the same document without the earlier attempt being lost.

Every attempt is kept as a payment transaction in Odoo with its reference, the amount, the payment method, the state and the identifier the gateway assigned to it and it stays linked to the sale order or the invoice it was raised from. This gives a single place to look when a payment is disputed and it separates an attempt the customer abandoned from one the gateway declined and from one that succeeded but was queried later. Because the gateway identifier is stored on the transaction, an entry in Odoo and an entry in the Cashfree dashboard can be matched to each other directly and the notifications received for a payment are logged so the sequence of events can be reviewed long after it happened.