Cashfree One-Time Payments Integration Docs

Use this docs as a friendly reference for creating payment orders, payment links, webhooks, and payment lookup endpoints.

What we supports

We supports two common one-time payment entry points:

1. Direct one-time orders usingcreate-orderwithtype: one_time.
2. Shareable payment links usingcreate-payment-link.

It also supports:

• Cancelling payment links.
• Listing payment records.
• Handling payment webhooks.

Base Contract

All routes are tenant-scoped:

/tenant/:tenantId/customer/...

Most endpoints require a bearer token in theAuthorizationheader.

Authorization: Bearer <token>
Content-Type: application/json

1) Create a One-Time Order

Usecreate-orderwhen you want to collect a direct one-time payment.

Endpoint

POST /tenant/:tenantId/customer/create-order

Check Here

Example request

curl -X POST "https://your-api/tenant/123/customer/create-order" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "one_time",
    "amount": 500,
    "currency": "INR",
    "leadId": "lead_001",
    "customerId": "cust_001",
    "name": "John Doe",
    "email": "john@example.com",
    "contact": "9876543210",
    "notes": {
      "purpose": "Monthly fee"
    },
    "notify": true,
    "returnUrl": "https://your-app.com/payments/success",
    "notifyUrl": "https://your-api/tenant/123/customer/webhook"
  }'

Notes

• typemust beone_time.
• amountis required and must be greater than0.
• contactis required.
• emailis optional for one-time payments.

2) Create a Payment Link

Usecreate-payment-linkwhen you want Cashfree to generate a reusable payment link for collecting a one-time payment.

Endpoint

POST /tenant/:tenantId/customer/create-payment-link

Check Here

Example request

curl -X POST "https://your-api/tenant/123/customer/create-payment-link" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "leadId": "lead_001",
    "amount": 500,
    "currency": "INR",
    "customerName": "John Doe",
    "customerEmail": "john@example.com",
    "customerPhone": "9876543210",
    "purpose": "Monthly fee",
    "returnUrl": "https://your-app.com/payments/success",
    "notifyUrl": "https://your-api/tenant/123/customer/webhook"
  }'

Notes

• Use this when you want to send a link instead of opening checkout immediately.
• The response contains the Cashfree payment link data and the stored payment record.

3) Webhooks

Use your tenant webhook endpoint to receive payment status updates from Cashfree.

Endpoint

POST /tenant/:tenantId/customer/webhook

Check Here

Payment webhook events

• PAYMENT_LINK_EVENT
• PAYMENT_SUCCESS_WEBHOOK
• PAYMENT_FAILED_WEBHOOK

Important

• Keep the raw request body available for signature verification.
• Persist webhook results so you can reconcile payment state.

4) Read and Manage Payments

List payments

GET /tenant/:tenantId/customer/get-payments

Check Here

Useful query params:

• leadId
• type(one_time,payment_link,subscription_auth,subscription_link,subscription-charged,transfer)
• page
• limit
• status
• subscriptionId
• planId
• beneficiaryId
• all
• from
• to
• filter

Cancel a payment link

POST /tenant/:tenantId/customer/cancel-payment-link/:id

Check Here

Use this to cancel an unpaid payment link by database ID.

Integration Checklist

1. Choose direct order or payment link.
2. Create the one-time payment.
3. Send the customer to the returned checkout or payment link.
4. Handle payment webhooks.
5. Query payment records withget-payments.
6. Cancel unpaid links when needed.