Skip to main content

Documentation Index

Fetch the complete documentation index at: https://www.cashfree.com/docs/llms.txt

Use this file to discover all available pages before exploring further.

Integrate Cashfree’s OAuth authentication to enable businesses using your partner platform to securely authorise payment processing through their Cashfree accounts. This integration allows businesses to offer payment capabilities to their customers without sharing sensitive credentials.
This integration uses OAuth 2.0. Cashfree handles authentication and issues access tokens that your platform uses to call Payment APIs on the business’s behalf no credential sharing required.

​
Prerequisites

Before integrating OAuth with Cashfree, complete the following requirements:
  • Become a software partner: Register your application as a software partner with Cashfree. Contact Cashfree support to initiate the partnership process.
  • Access Partner Dashboard: Log in to the Partner Dashboard and navigate to Developers to access OAuth configuration tools.
  • Obtain partner credentials: You will need:
    • Partner API Key: Private key for authenticating your platform’s API calls.
    • OAuth Client ID: Public identifier for your OAuth application.
  • Configure Webhook URL: Provide a valid webhook URL where Cashfree will send payment status updates and account linking events.

​
Integration flow

Use the following steps to complete the OAuth integeration of the partner platform:
  1. Create an OAuth application and collect credentials
  2. Implement OAuth authorisation and token exchange
  3. Refresh expired access tokens securely
  4. Create orders and process customer payments
  5. Track payment outcomes using API and webhooks

​
Key benefits

OAuth integration provides the following benefits:
  • Secure credential handling: Businesses never share passwords, OAuth tokens have limited scope.
  • Simple onboarding: Businesses link accounts in minutes without manual verification.
  • Account management: Businesses can unlink accounts anytime via Merchant Dashboard or API.
  • Real-time notifications: Webhooks provide immediate payment status updates.

​
Step 1: Create an OAuth application

Create an OAuth application in the Partner Dashboard to obtain your OAuth credentials, using the following steps:
1

Create the application

Navigate to Partner Dashboard > Developers > OAuth App and complete the application form with the following details:
FieldDescription
App NameInternal identifier for your application (for example, “partner platform”).
App Brand NameName shown to businesses during authorisation (for example, “Acme partner platform”).
LogoUpload a logo in PNG or JPG format (maximum 2 MB, square 1:1 aspect ratio recommended).
Redirect URLYour platform’s endpoint that receives the authorisation code after consent (for example, https://yourplatform.com/oauth/callback).
2

Retrieve your OAuth client ID

After creating the application, Cashfree displays your oauth-client-id in the response. Store this value securely, you will use it for all OAuth API requests.

​
Step 2: Implement the OAuth authorisation flow

Guide businesses through Cashfree’s authorisation flow to obtain merchant credentials.
1

Generate the authorisation link

Create an authorisation link that directs businesses to Cashfree’s consent screen. Your platform calls the authorisation endpoint with the business’s unique identifier.The request supports the following parameters:
ParameterTypeRequiredDescription
response_typestringYesAlways set to "code" for authorisation code flow.
scopestringYesSet to "read_write" to allow payment processing on behalf of the business.
statestringOptionalArbitrary string (8-64 characters) for CSRF protection; returned in redirect URL.
merchant_idstringOptionalYour internal reference ID for the business; helps track which business authorised the request.
The auth_link is valid for 1 hour. Redirect the business to this link to begin authorisation.
2

Business authorisation

The business logs in with their Cashfree credentials and reviews the permissions your platform is requesting:
  • Allowed: Manage payments (including refunds, settlements, disputes).
  • Allowed: View account information (basic details).
  • Not allowed: Modify sensitive information (bank account, email, phone number).
After authorisation, Cashfree redirects the business back to your configured redirect URL with an authorisation code.
3

Redirect URL format

Use the following redirect URL format to capture the authorisation response:
https://yourplatform.com/oauth/callback
  ?merchant_id=business_reference_id
  &code=auth_code_valid_for_5_minutes
  &state=secure_random_string
  &scope=read_write
4

Exchange authorisation code for access token

Immediately after receiving the authorisation code, exchange it for an access token. This token grants your platform the ability to call Cashfree APIs on the business’s behalf.Store the following credentials securely for subsequent API calls:
  • access_token: Use for Cashfree API calls, valid for 24 hours.
  • refresh_token: Use to obtain a new access token after expiry, valid for 90 days.
  • merchant_id: Your reference ID for the linked business.
The authorisation code is valid for only 5 minutes. If the code expires before you exchange it, the business must authorise again.

​
Step 3: Refresh expired access tokens

Access tokens expire after 24 hours. Use the refresh token to obtain a new access token without requiring the business to authorise again.
A new refresh token is generated with each access token refresh. The previous refresh token becomes invalid immediately. Always store the new refresh token to avoid losing access.

​
Step 4: Create orders and process payments

After obtaining the access token, use Cashfree’s payment APIs to create orders and process payments on behalf of the business.
1

Create an order

Create an order to represent a transaction the business wants to process using the Create Order API.Store the payment_session_id and cf_order_id you will need both to initiate payment.
2

Offer payment methods to customers

After creating an order, present payment options to the customer. Cashfree supports two payment flows:
Customers complete UPI payment directly within your platform without redirecting to Cashfree.Initiate UPI Intent payment using the Order Pay API:Display these UPI links to customers. They can click any link to open their preferred UPI app and complete payment.

​
Step 5: Check payment status

Retrieve payment status using either synchronous API queries or asynchronous webhooks. For production integrations, use webhooks for real-time updates. Query payment status using the Get Payments for Order API: Receive webhooks (asynchronous) using Payment Webhooks API. Cashfree sends webhook events to your configured webhook URL for payment status changes and account unlinking events. Configure your webhook URL in Partner Dashboard > Developers > Webhooks. Once configured, Cashfree sends the following webhook event types to your webhook URL:
  • payment.success: Payment completed successfully.
  • payment.failed: Payment declined or timed out.
  • merchant.unlinked: Business unlinked their account from your platform.
Verify webhook signatures using your partner API key before processing webhook events. This prevents unauthorised requests from external sources.

​
Manage account linking

Use the following endpoints to check account linking status and revoke access when needed. Unlinking can be initiated by the business via Merchant Dashboard or by your platform via API.

​
Check merchant status

Retrieve the linking status and onboarding details for a business using the Get Merchant Status API. Revoke your platform’s access to a business’s Cashfree account. This immediately invalidates all access tokens and refresh tokens for that merchant.
After unlinking, your platform cannot process payments for this business until they authorise again. Store previous access and refresh tokens securely if needed for compliance or audit purposes.

​
Production deployment

Update the following endpoints and credentials before deploying to production:
EnvironmentAPI endpoint
Sandboxhttps://api-sandbox.cashfree.com and https://sandbox.cashfree.com
Productionhttps://api.cashfree.com and https://cashfree.com
Replace your oauth-client-id, x-partner-apikey, and API endpoints with production credentials and URLs. Ensure you have configured your production webhook URL in the Partner Dashboard and successfully tested the entire authorisation and payment flow.

​
Support and resources

Use the resources below for OAuth implementation guidance and support:

Partner Dashboard

Access OAuth credentials and configure webhook settings.

Payment Gateway API Reference

Review endpoint details for creating orders and processing payments.

Request support

Get help with onboarding and technical issues from the Cashfree support team.