# Cashfree Payments

Cashfree is the payment gateway Connect's payment links are created through. Connect creates a link or order through Cashfree's API, the customer pays on Cashfree's page, and Cashfree reports the result in a signed webhook. Connect verifies that signature and the payment's state before recording anything as paid. A redirect or a customer's word is never enough.

- **Status:** Reference
- **Audience:** both, developer
- **Last verified:** 2026-11-02
- **Canonical:** https://connectbyjbrh.com/docs/technology/cashfree/

## What it is

Cashfree Payments is an Indian payments company offering a payment gateway, payment links, subscriptions and payouts through REST APIs. Each request carries an `x-api-version` header.

Connect's payment layer, `payment_providers.py`, is provider-neutral. Cashfree is the default, with adapters for Razorpay, Stripe and CCAvenue on the same interface: create, fetch and cancel a link, verify keys, verify a webhook.

**Category** — Payment gateway
**API version in the code** — `2025-01-01`
**Modules** — `backend/app/payment_providers.py`, `saas_billing.py`, the journey and deal-close modules
**Official site** — [cashfree.com/docs](https://www.cashfree.com/docs/)

## Where Connect uses it

| Place in Connect | What it does there |
|---|---|
| `payment_providers.py` | Links and orders; key verification; webhook signature verification |
| `saas_billing.py` | Plan payments and subscriptions for Connect's own services |
| Deal close and the customer journey | A quotation becomes a payment link; paid state comes only from verification |

## How it connects

1. Connect creates a payment link through Cashfree's API
2. The customer pays on Cashfree's hosted page
3. Cashfree posts a webhook with `x-webhook-signature` and `x-webhook-timestamp`
4. Connect computes base64(HMAC-SHA256(timestamp + raw body)) and compares in constant time
5. Only a verified, successful payment changes the record to Paid

## Benefits and limits

What it gives Connect:

- Indian payment methods (UPI, cards, net banking) on a hosted page, so card data never touches Connect.
- Signed webhooks make the provider's word verifiable.
- Sandbox and production endpoints let flows be tested without real money.

Where it stops, and what Connect does about it:

- A redirect back to Connect is not proof of payment. Only the verified webhook or a server-side fetch is.
- Large or manual payments (bank transfers) are outside the gateway and need their own authoritative verification before they count.
- Settlement timing, fees and refunds follow the merchant's Cashfree agreement.

## Security and privacy

- Card and bank details are entered on Cashfree's page and never reach Connect.
- API keys and webhook secrets are stored encrypted. A missing secret means the webhook is refused.
- The signature covers the timestamp, which limits the use of a captured old event.

## Licence, cost and versions

| Question | Answer |
|---|---|
| Licence | Commercial service under Cashfree's merchant terms |
| Cost | Per the merchant's agreement. See [Cashfree pricing](https://www.cashfree.com/payment-gateway-charges/) |
| Version | `x-api-version: 2025-01-01` |
| Compatibility | Sandbox at `sandbox.cashfree.com`; production at `api.cashfree.com` |

## Troubleshooting

**A payment shows paid at Cashfree but not in Connect** — The webhook was refused or never arrived. Check the signing secret and the webhook URL in Cashfree's dashboard; Connect can fetch the link's state.
**Key verification fails** — Sandbox keys used against production, or the reverse.
**Signature mismatch** — Something altered the body before verification. The check runs on the raw bytes.

## Official references

- [Cashfree documentation](https://www.cashfree.com/docs/)
- [Payment links API](https://www.cashfree.com/docs/api-reference/payments/latest/payment-links/create)
- [Webhook signature verification](https://www.cashfree.com/docs/payments/online/webhooks/signature-verification)

## Questions

### When does Connect mark an invoice as paid?

Only after the payment is verified with the provider: a signed webhook or a server-side fetch of the link's state. A manual payment needs its own authoritative verification.

### Does Connect store card numbers?

No. Payment details are entered on the gateway's page. Connect stores the link, the reference and the verified result.

## Related

- [Provider webhook signatures](https://connectbyjbrh.com/docs/technology/webhook-signature/)
- [Idempotency](https://connectbyjbrh.com/docs/technology/idempotency/)
- [Webhooks](https://connectbyjbrh.com/docs/technology/webhook/)
- [Audit logs](https://connectbyjbrh.com/docs/technology/audit-log/)

## What this page is based on

- `backend/app/payment_providers.py`
- `backend/app/saas_billing.py`
- https://www.cashfree.com/docs/
