Cashfree Payments

Cashfree Payment Gateway API

Cashfree PG (2026-01-01): orders, UPI Order Pay, sandbox simulation, payments, refunds, settlements and payment links.

PaymentsGuided#payments#upi#india#refunds#settlements#payment-links

Fork copies the collection into your workspace, without the publisher's secrets, so you can add your own key and send requests. Star saves it to your starred APIs (Account › Marketplace) and helps others find it.

Overview

Cashfree Payments is an Indian payment gateway (cards, UPI, net banking, wallets, EMI, Pay Later) with a REST API that is versioned by date. This guided collection covers the PG API version 2026-01-01: orders, Order Pay (UPI collect and QR on your own UI), sandbox payment simulation, payments, refunds, settlements and payment links. It starts in the sandbox.

Get credentials

  1. Sign up or log in at the Cashfree Merchant Dashboard and choose Payment Gateway.
  2. Click Switch to Test (yellow banner = test environment). Open Developers > API Keys; test keys are generated for you. Click the icon next to each key and View API Key.
  3. Copy the App ID into clientId and the Secret Key into clientSecret (both secret variables). Production keys need account activation and 2FA, and are separate from Payouts or Secure ID keys.

Authentication

Every server call sends three headers: x-client-id (App ID), x-client-secret (Secret Key) and x-api-version (a date such as 2026-01-01; the collection sets it from apiVersion). Never call these APIs from a browser or app. The exception is Order Pay (POST /orders/sessions), which is authorised by the order's payment_session_id alone. Optional x-request-id and x-idempotency-key headers help with tracing and safe retries.

Base URLs (sandbox first)

EnvironmentbaseUrl
Sandboxhttps://sandbox.cashfree.com/pg
Productionhttps://api.cashfree.com/pg

Run order

  1. 1. Start here: Create an order (saves orderId and paymentSessionId), then Get an order.
  2. 2. Collect the payment: Order Pay with the sandbox UPI ID testsuccess@gocash (or testfailure@gocash), or open the hosted checkout with the JS SDK and test cards (OTP 111000); optionally force a result with Simulate.
  3. 3. Payments, 4. Refunds (in sandbox, refund_note SUCCESS / FAILED / PENDING simulates the outcome), 5. Settlements, 6. Payment links.

Test data: Data to test integration.

Limits and pricing

Rate limits are per API and per account; responses carry x-ratelimit-limit, x-ratelimit-remaining and x-ratelimit-retry, and a breach returns 429. Pricing (MDR) depends on the payment method and your plan; see cashfree.com/payment-gateway-charges.

Webhooks

Set order_meta.notify_url per order or configure webhooks in the dashboard. Verify the x-webhook-signature header: Base64 of HMAC-SHA256, keyed with your secret key, over the x-webhook-timestamp value followed by the raw body before trusting a webhook, and always re-check with Get an order.

Common errors

StatusMeaning / fix
401Wrong x-client-id / x-client-secret, or test keys on the production URL
400Missing or invalid field (see message, code)
404Unknown order, payment, refund or link ID
409Duplicate order_id, refund_id or link_id
422Valid JSON but the action is not allowed (for example refunding an unpaid order)
429Rate limit hit; wait x-ratelimit-retry seconds

Links

Endpoints 19

1. Start here

  • POSTCreate an order/ordersCreates an order on your server and returns the payment_session_id that the Cashfree checkout (JS SDK, mobile SDKs or Order Pay below) needs. The pre-request…
  • GETGet an order/orders/{{orderId}}Fetches an order by your order_id. Check order_status on your server before fulfilling: PAID means one successful payment; ACTIVE means not paid yet; EXPIRED…
  • POSTList eligible payment methods/eligibility/payment_methodsReturns the payment methods (cards, UPI, net banking, wallets, EMI and so on) your account can offer for an amount or an existing order. Send queries.order_id…

2. Collect the payment

  • POSTPay by UPI collect (Order Pay)/orders/sessionsStarts a payment for the order with the payment_session_id from Create an order. It is the one PG call that needs no client ID or secret, so a browser or app…
  • POSTPay by UPI QR (Order Pay)/orders/sessionsSame Order Pay call with upi.channel: qrcode. The response data.payload.qrcode holds a base64 image of a dynamic UPI QR to show on your own page. Each call…
  • POSTSimulate a payment result (sandbox)/simulateSandbox testing tool: forces the outcome of a payment you started with Order Pay (entity_id = cf_payment_id). Set payment_status to SUCCESS, FAILED, PENDING…
  • GETFetch a simulation/simulate/{{simulationId}}Returns a simulation created by Simulate a payment result, by its simulation_id (saved automatically), so you can confirm which status was applied to which…

3. Payments and orders

  • GETGet payments for an order/orders/{{orderId}}/paymentsLists every payment attempt on an order with payment_status (SUCCESS, FAILED, PENDING, USER_DROPPED, NOT_ATTEMPTED, VOID, CANCELLED), payment_group,…
  • GETGet a payment by ID/orders/{{orderId}}/payments/{{cfPaymentId}}Fetches one payment attempt of an order by cf_payment_id. Same fields as an element of Get payments for an order; use it when a webhook gives you a payment ID…
  • PATCHTerminate an order/orders/{{orderId}}Stops an unpaid order so no further payment can be made on it, for example when the cart changes. Send order_status: TERMINATED. The order may first move to…

4. Refunds

  • POSTCreate a refund/orders/{{orderId}}/refundsRefunds all or part of a paid order. The pre-request script sets a new refundId. What comes back: the refund with cf_refund_id, refund_status and, once…
  • GETGet a refund/orders/{{orderId}}/refunds/{{refundId}}Returns one refund by your refund_id, with refund_status (SUCCESS, PENDING, PENDING_APPROVAL, CANCELLED, ONHOLD, REJECTED), status_description, refund_arn…
  • GETGet all refunds for an order/orders/{{orderId}}/refundsLists every refund raised against an order, newest details included. Handy for showing a refund history on an order page or reconciling partial refunds that…

5. Settlements

  • GETGet settlements for an order/orders/{{orderId}}/settlementsShows how a paid order was settled to your bank account: cf_settlement_id, transfer_utr, transfer_time, order_amount, service_charge, service_tax and the net…
  • POSTGet all settlements/settlementsLists settlements to your bank account for a date range or by settlement IDs, UTRs or status. pagination.limit up to 1000; pass back the returned cursor to…

6. Payment links

  • POSTCreate a payment link/linksCreates a hosted payment link you can share by SMS, email or chat. The pre-request script sets a new linkId. What comes back: link_url, link_status: ACTIVE…
  • GETFetch a payment link/links/{{linkId}}Returns a link's details, its link_status (ACTIVE until it is paid, expires or is cancelled) and link_amount_paid. Use it to show whether a shared link has…
  • GETGet orders for a payment link/links/{{linkId}}/ordersLists the orders created when customers paid (or tried to pay) through a link. The optional status query (PAID, the default, or ALL) filters them; each order…
  • POSTCancel a payment link/links/{{linkId}}/cancelCancels an active link so it can no longer be paid. Only links that have not been paid can be cancelled; the response is the link with link_status: CANCELLED.

API details

Base URL
https://sandbox.cashfree.com/pg
https://api.cashfree.com/pg
Authentication
An API key in the x-client-id header
An API key in the x-client-secret header
Operations
19 operations on 19 pathsGET 9POST 9PATCH 1
Main resources
1. Start here 32. Collect the payment 43. Payments and orders 34. Refunds 35. Settlements 26. Payment links 4
Description format
Swastik Codes guided collection, API version checked against the docs on 2026-11-18

How to test the Cashfree Payment Gateway API in Swastik Codes

  1. Open the APISelect “Fork & run in Swastik Codes” on this page. Sign in or create a free account if asked.
  2. Fork it into your workspaceChoose a workspace. You get your own copy of the Cashfree Payment Gateway API collection, without the publisher's secrets.
  3. Add your credentialsThis API uses an API key in the x-client-id header. Add yours in the collection's variables or an environment; the requests already reference it.
  4. Send a requestPick an endpoint, for example “Create an order” (POST /orders), and press Send. Check the response, add tests and run the whole collection with the runner.

Frequently asked questions

What is the Cashfree Payment Gateway API?

Cashfree PG (2026-01-01): orders, UPI Order Pay, sandbox simulation, payments, refunds, settlements and payment links. It is listed under Payments and has 19 endpoints.

Who publishes the Cashfree Payment Gateway API?

It is listed from Cashfree Payments's public API description (an OpenAPI document), not published by Cashfree Payments on Swastik Codes. Anyone who controls cashfree.com can claim the profile by adding a DNS TXT record.

What is the base URL of the Cashfree Payment Gateway API?

Its description lists 2 base URLs: https://sandbox.cashfree.com/pg, https://api.cashfree.com/pg. The first is the usual one; the others are typically sandbox or regional servers.

How do I authenticate with the Cashfree Payment Gateway API?

It accepts 2 methods: an API key in the x-client-id header; an API key in the x-client-secret header.

How many endpoints does the Cashfree Payment Gateway API have?

19 operations on 19 paths (9 GET, 9 POST, 1 PATCH). The largest groups are 1. Start here, 2. Collect the payment, 3. Payments and orders, 4. Refunds.

Is forking the Cashfree Payment Gateway API free?

Yes. Forking copies the collection into your workspace for free. It has been starred 0 times and forked 0 times.

Suggest an API

Tell us which public API is missing. We check it, then add it here with its endpoints when it has an OpenAPI (Swagger) description.