Cashfree integration in Go

What it does

Configuration

Two settings are required: the App ID and the secret key. There is no separate webhook secret, because Cashfree signs its webhooks with the secret key. Set them in Config from your own main(), or leave Config empty and type them under Settings › Payment methods in the admin.

The module reads its Config struct, not the environment. The variable names are the ones the package’s own example or the reference binary uses; in your own main() you choose where each value comes from. Where a setting has a panel label, the admin’s settings drawer can hold it too, and a value typed there wins over Config.

Setting it up

1. Set the webhook in CashfreeIn the Cashfree dashboard, under Developers, Webhooks, point the payment events at https://your-api-host/api/checkout/cashfree/webhook, webhook version 2023-08-01.
2. Install the modulePass cashfree.New to gocommerce.New, as below, or run the reference binary with -gateways, which installs every payment module idle.
3. Give it the keysApp ID, secret key and environment, in Config or under Settings › Payment methods. A key typed into the panel counts on the next request, with no restart.
4. Take a paymentPOST /api/checkout/cashfree answers with payment_session_id, the Cashfree order id and the environment for Cashfree’s checkout. The webhook marks the order paid.

import (
	"os"

	"github.com/itswadesh/gocommerce/core"
	cashfree "github.com/itswadesh/gocommerce/ext/payments-cashfree"
)

app, err := gocommerce.New(cfg,
	cashfree.New(cashfree.Config{
		AppID:     os.Getenv("CASHFREE_APP_ID"),
		SecretKey: os.Getenv("CASHFREE_SECRET_KEY"),
	}),
)

How it works

• One webhook route, owned by the engine

  Cashfree calls POST /api/checkout/cashfree/webhook. The engine hands the module the body untouched, because the signature is over the exact bytes Cashfree sent. Until the module is switched on and configured, every webhook is refused with a 503.

• Signed and timed

  x-webhook-signature is checked as the base64 HMAC-SHA256, keyed on the secret key, of x-webhook-timestamp followed by the raw body, in constant time. A timestamp more than five minutes from now is refused, as is a missing or wrong signature (400).

• Each outcome once

  A failure and then a success can arrive for one Cashfree order, so the claim is on the event type and the payment id, in the module’s own table with ON CONFLICT DO NOTHING. A redelivery is answered 200 and changes nothing; a failure arriving after the order is paid leaves it paid.

• The amount asked is the check

  A success settles the order only when the Cashfree order’s amount matches what the module asked for, and that still matches the order’s total, in INR. An offer can make the payment itself smaller, so it is the Cashfree order’s amount that is compared.

• A failed update is retried

  If marking the order paid or failed does not go through, the module releases its claim and answers 500, so Cashfree’s retry finds work to do.

• Refunds, whole or in part

  A refund from the admin goes to Cashfree against the Cashfree order the money was taken on, never for more than Cashfree captured. Its refund id is built from the order, the refunds before it and the amount, so a retry after a lost answer is refused by Cashfree as a duplicate rather than paid twice.

• The return check is rationed

  The verify route answers a paid order from the store, and asks Cashfree about one Cashfree order at most once every 15 seconds, so a page reloaded in a loop cannot spend the merchant’s API allowance. It answers with the order number and payment status, nothing more.

What it does not do

Read these before an order depends on it. No store is known to run GoCommerce in production yet, so these come from the code, not from anyone’s experience.

• Rupees onlyAn order in any currency but INR is refused before a Cashfree order is made. The store’s settlement currency has to be the rupee.
• A phone number is requiredCashfree needs the shopper’s phone. An order with none, on the order or its address, is refused at checkout.
• Ten tries per orderAn order may collect at most 10 Cashfree orders through retried checkouts. After that the shopper is told to place a new order.
• A changed total waits for a personA success for a Cashfree order whose amount no longer matches the order is logged as an error, acknowledged and not applied. The order stays unpaid until an operator reconciles it.
• Money for a cancelled orderA payment that arrives after the order was cancelled does not settle it. It goes on the store’s Errors screen, and the refund is made by hand in Cashfree’s dashboard.
• Payment events onlyOnly PAYMENT_SUCCESS_WEBHOOK and PAYMENT_FAILED_WEBHOOK are acted on. A refund made in Cashfree’s dashboard, a dropped-out shopper or any other event is acknowledged and does not change the GoCommerce order.
• The rationing is per processThe verify route’s 15-second spacing is kept in memory. After a restart, or on another instance, the first call asks Cashfree again.

Related modules

Each is a directory under ext/, imported the same way. Where this one fits in the store: Checkout and payments in GoCommerce.

• Clover integration in Go Take card payments through Clover’s Hosted Checkout in a GoCommerce store: three keys, the webhook URL, refunds, USD or CAD, and what the module leaves out.
• Creem integration in Go Sell through Creem as merchant of record from a GoCommerce store: the placeholder product, keys, webhook URL, full-only refunds and the module’s limits.
• Helcim integration in Go Take card payments through Helcim’s HelcimPay.js in a GoCommerce store: API token, verifier token, webhook URL, refunds, and what the module leaves out.
• Hyperswitch integration in Go Route payments through Hyperswitch, the open-source payments router, from a GoCommerce store: keys, payment links, webhook URL, refunds and limits.