Cashfree Payment Links — setup and reference

Module and release scope

This guide covers Cashfree Payment Links 1.0.0, Extension API 1, from the reviewed product source. Its declared core range is 1.3.6–1.3.99. Use the matching released core and signed provider package; a version label alone does not install the required contracts. Source availability does not mean the module is bundled in every currently downloadable product, installed on your server, enabled or certified for your merchant/server account. Nothing in this guide enables a provider or changes your existing connections.

Open System → Payment gateways (newer source may group these as Payments, Domain services or Hosting services). Install the reviewed signed package through Modules & addons or the integration workspace's Install tab, enable the module separately, add an account/connection, save its own credentials, run its stated Test and explicitly enable the connection. Saving or retesting disables the connection until you enable it again. Start with the provider's test environment where supported; otherwise use an isolated account or server.

Exact connection fields

These are the fields declared by this module. Secret values are entered privately and encrypted by the application. Defaults are configuration hints, not approved live merchant settings. Internal fields are populated by the module and are not operator-editable.

Key / label	Type	Required	Default / guidance
mode — Environment	select	Yes	Default: "sandbox" Choices: sandbox = Sandbox, live = Live
client_id — Payment Gateway client ID	secret	Yes	Use the account-specific value described below.
client_secret — Payment Gateway secret key	secret	Yes	Use the account-specific value described below.
verification_link_id — Existing payment link ID for connection test	text	Yes	Create one link in the matching Cashfree dashboard, then enter its Link ID. Test only reads that link; it never creates or charges a payment.
currencies — Approved invoice currencies	text	Yes	Comma-separated currencies approved for this merchant. No currency conversion is performed.

Uses Payment Gateway Payment Links with partial payments and automatic reminders disabled. This version supports INR invoices for India merchants. The customer must have a real billing name and valid Indian mobile number in their billing profile; missing contact details are rejected before a payment attempt is submitted.

Configure

1. Obtain Payment Gateway client ID and secret from the matching Cashfree sandbox or production merchant dashboard. Do not use payout or Secure ID credentials. Enable Payment Links create/read, linked Orders read, Payments read and order-refund read. This package pins Payment Gateway API version 2026-01-01.
2. Create one verification link in the matching provider dashboard, and enter its merchant Link ID under Existing payment link ID for connection test. It may be an unpaid sandbox link; Test only retrieves it. This avoids creating an order just to test credentials.
3. Add the saved application webhook URL to Cashfree’s Payment Links webhook configuration. Subscribe to the payment-link payment event (payment_link_payment; API notifications may identify it as PAYMENT_LINK_EVENT). The module verifies x-webhook-signature using base64 HMAC-SHA256 of x-webhook-timestamp concatenated with the exact raw body, signed with your PG secret. There is no separate invented webhook secret field.
4. Set Approved invoice currencies to INR and Test. Sandbox uses sandbox.cashfree.com/pg and payments-test.cashfree.com; production uses api.cashfree.com/pg and payments.cashfree.com. Custom vanity payment-link domains are deliberately not accepted by this release.

To confirm payment, the module reads the paid link, its linked orders and successful order payments. Exactly one fully paid order and one successful full payment must match the original attempt metadata; aggregated partial payments remain under review.

Installation and activation

The package contains generic product code only. Installation leaves the module disabled and does not create, enable or populate a merchant account. In System → Payments → Provider library, enable the module only when ready, add a connection, enter your own credentials, run Test and explicitly enable that connection. Keep sandbox and live accounts separate. Existing enabled gateways are unaffected.

Use the exact HTTPS webhook URL displayed on that saved connection; do not enter the storefront home page. One connection endpoint can serve invoices across storefront domains because payment attempts retain their connection and invoice identity. Keep it reachable without login or a browser challenge. Return URLs are generated and signed by the application per invoice; do not replace them with a static merchant callback.

The module never collects PAN, CVV or customer wallet credentials. Checkout creation is submitted once, with a unique attempt reference; a timeout requires reconciliation, not an automatic second charge. Browser success parameters never prove payment. Final amount, currency, checkout identity and application metadata are checked against authenticated provider reads. Notifications use stable payment IDs for duplicate protection. A partial or ambiguous payment stays under billing review.

No currency conversion is performed. Only the listed two-decimal invoice currencies are accepted, and only those explicitly entered under Approved invoice currencies are offered. Availability of cards, wallets and local methods remains subject to the merchant account, shopper location and provider checkout; installing a module does not enable provider payment products. Refund creation, recurring billing and token charging operations are not implemented. A read-only refund query prevents a previously refunded transaction from being newly allocated; any refund record keeps the checkout under billing review.

Validation

Run php tests/gateway-growth.php for isolated HTTP fixtures covering checkout creation, server verification, signed notifications, exact amounts, identity mismatches, invalid URLs, incomplete billing profiles and no checkout POST retries. These checks do not certify credentials, merchant underwriting or a live payment. Complete a provider sandbox checkout and callback test before enabling live traffic.

Official implementation references

Reviewed 2026-10-21. Provider contracts may change; recheck these sources before changing API versions.

• https://www.cashfree.com/docs/api-reference/payments/latest/payment-links/create-payment-link
• https://www.cashfree.com/docs/api-reference/payments/latest/payment-links/fetch-payment-link-details
• https://www.cashfree.com/docs/api-reference/payments/latest/payment-links/get-orders-for-a-payment-link
• https://www.cashfree.com/docs/payments/no-code/customize/webhooks
• https://www.cashfree.com/docs/payments/online/webhooks/signature-verification
• https://www.cashfree.com/docs/api-reference/payments/latest/refunds/get-all-refunds-for-an-order