> ## 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.

# Partner Platform OAuth Integration

> Enable businesses to securely connect their Cashfree payment accounts to your partner platform using OAuth and process payments on their behalf.

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.

<Note>
  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.
</Note>

## 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](https://merchant.cashfree.com/merchants/landing?env=prod\&raise_issue=1) to initiate the partnership process.
* **Access Partner Dashboard**: Log in to the [Partner Dashboard](https://partner.cashfree.com/auth/login) 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 integration of the partner platform:

1. [Create an OAuth application and collect credentials](#step-1-create-an-oauth-application)
2. [Implement OAuth authorisation and token exchange](#step-2-implement-the-oauth-authorisation-flow)
3. [Refresh expired access tokens securely](#step-3-refresh-expired-access-tokens)
4. [Create orders and process customer payments](#step-4-process-payments)
5. [Track payment outcomes using API and webhooks](#step-5-check-payment-status)

## 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](https://merchant.cashfree.com/auth/login) 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:

<Steps>
  <Step title="Create the application">
    Navigate to **[Partner Dashboard](https://partner.cashfree.com/auth/login) > Developers > OAuth App** and complete the application form with the following details:

    | Field              | Description                                                                                                                           |
    | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------- |
    | **App Name**       | Internal identifier for your application (for example, "partner platform").                                                           |
    | **App Brand Name** | Name shown to businesses during authorisation (for example, "Acme partner platform").                                                 |
    | **Logo**           | Upload a logo in PNG or JPG format (maximum 2 MB, square 1:1 aspect ratio recommended).                                               |
    | **Redirect URL**   | Your platform's endpoint that receives the authorisation code after consent (for example, `https://yourplatform.com/oauth/callback`). |
  </Step>

  <Step title="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>
</Steps>

## Step 2: Implement the OAuth authorisation flow

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

<Steps>
  <Step title="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.

    <AccordionGroup>
      <Accordion title="Sample request">
        <CodeBlock language="bash">
          {`curl --location 'https://api-sandbox.cashfree.com/partners/oauth/auth_link' \\
                    --header 'x-partner-apikey: <partner-api-key>' \\
                    --header 'oauth-client-id: <oauth-client-id>' \\
                    --header 'Content-Type: application/json' \\
                    --data '{
                      "response_type": "code",
                      "scope": "read_write",
                      "state": "secure_random_string_8_to_64_chars",
                      "merchant_id": "unique_business_reference_id"
                    }'`}
        </CodeBlock>
      </Accordion>

      <Accordion title="Sample response">
        <CodeBlock language="json">
          {`{
                    "created_at": "2023-07-24T12:24:44+0530",
                    "expires_at": "2023-07-24T13:24:44+0530",
                    "auth_link": "https://auth.cashfree.com/..token.."
                    }`}
        </CodeBlock>
      </Accordion>
    </AccordionGroup>

    The request supports the following parameters:

    | Parameter       | Type   | Required | Description                                                                                     |
    | --------------- | ------ | -------- | ----------------------------------------------------------------------------------------------- |
    | `response_type` | string | Yes      | Always set to `"code"` for authorisation code flow.                                             |
    | `scope`         | string | Yes      | Set to `"read_write"` to allow payment processing on behalf of the business.                    |
    | `state`         | string | Optional | Arbitrary string (8-64 characters) for CSRF protection; returned in redirect URL.               |
    | `merchant_id`   | string | Optional | Your internal reference ID for the business; helps track which business authorised the request. |

    <Note>The `auth_link` is valid for 1 hour. Redirect the business to this link to begin authorisation.</Note>
  </Step>

  <Step title="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.
  </Step>

  <Step title="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
    ```
  </Step>

  <Step title="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.

    <AccordionGroup>
      <Accordion title="Sample request">
        <CodeBlock language="bash">
          {`curl --location 'https://api-sandbox.cashfree.com/partners/oauth/token' \\
                    --header 'x-partner-apikey: <partner-api-key>' \\
                    --header 'oauth-client-id: <oauth-client-id>' \\
                    --header 'Content-Type: application/json' \\
                    --data '{
                      "grant_type": "authorization_code",
                      "code": "auth_code_from_redirect"
                    }'`}
        </CodeBlock>
      </Accordion>

      <Accordion title="Sample response">
        <CodeBlock language="json">
          {`{
                    "merchant_id": "business_reference_id",
                    "connection_status": "Linked",
                    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
                    "refresh_token": "refresh_token_valid_for_90_days",
                    "token_type": "bearer",
                    "expires_in": 86400
                    }`}
        </CodeBlock>
      </Accordion>
    </AccordionGroup>

    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.

    <Info>The authorisation code is valid for only 5 minutes. If the code expires before you exchange it, the business must authorise again.</Info>
  </Step>
</Steps>

## 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.

<AccordionGroup>
  <Accordion title="Sample request">
    <CodeBlock language="bash">
      {`curl --location --request POST 'https://api-sandbox.cashfree.com/partners/oauth/token' \\
            --header 'x-partner-apikey: <partner-api-key>' \\
            --header 'oauth-client-id: <oauth-client-id>' \\
            --header 'Content-Type: application/json' \\
            --data-raw '{
              "grant_type": "refresh_token",
              "refresh_token": "refresh_token_from_previous_response"
            }'`}
    </CodeBlock>
  </Accordion>

  <Accordion title="Sample response">
    <CodeBlock language="json">
      {`{
            "merchant_id": "business_reference_id",
            "connection_status": "Linked",
            "access_token": "new_access_token",
            "refresh_token": "new_refresh_token",
            "token_type": "bearer",
            "expires_in": 86400
            }`}
    </CodeBlock>
  </Accordion>
</AccordionGroup>

<Warning>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.</Warning>

## 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.

<Steps>
  <Step title="Create an order">
    Create an order to represent a transaction the business wants to process using the [Create Order API](/api-reference/payments/latest/orders/create).

    <AccordionGroup>
      <Accordion title="Sample request">
        <CodeBlock language="bash">
          {`curl --request POST 'https://sandbox.cashfree.com/pg/orders' \\
                    --header 'accept: application/json' \\
                    --header 'content-type: application/json' \\
                    --header 'x-api-version: 2023-08-01' \\
                    --header 'Authorization: Bearer <access_token>' \\
                    --data '{
                      "customer_details": {
                        "customer_id": "unique_customer_id",
                        "customer_phone": "9898989898",
                        "customer_email": "customer@example.com"
                      },
                      "order_amount": 100.00,
                      "order_currency": "INR",
                      "order_id": "unique_order_reference_id",
                      "order_meta": {
                        "return_url": "https://yourplatform.com/order/completion"
                      }
                    }'`}
        </CodeBlock>
      </Accordion>

      <Accordion title="Sample response">
        <CodeBlock language="json">
          {`{
                    "cf_order_id": "2149460581",
                    "order_id": "unique_order_reference_id",
                    "order_amount": 100.00,
                    "order_currency": "INR",
                    "order_status": "ACTIVE",
                    "payment_session_id": "session_a1VXIPJo8kh7IBigVXX8LgTMupQW...",
                    "order_expiry_time": "2023-09-09T18:02:46+05:30",
                    "created_at": "2023-08-11T18:02:46+05:30"
                    }`}
        </CodeBlock>
      </Accordion>
    </AccordionGroup>

    Store the `payment_session_id` and `cf_order_id` you will need both to initiate payment.
  </Step>

  <Step title="Offer payment methods to customers">
    After creating an order, present payment options to the customer. Cashfree supports two payment flows:

    <Tabs>
      <Tab title="UPI Intent (Seamless)">
        Customers complete UPI payment directly within your platform without redirecting to Cashfree.

        Initiate UPI Intent payment using the [Order Pay API](/api-reference/payments/latest/payments/pay):

        <AccordionGroup>
          <Accordion title="Sample request">
            <CodeBlock language="bash">
              {`curl --request POST 'https://sandbox.cashfree.com/pg/orders/sessions' \\
                            --header 'accept: application/json' \\
                            --header 'content-type: application/json' \\
                            --header 'x-api-version: 2023-08-01' \\
                            --header 'Authorization: Bearer <access_token>' \\
                            --data '{
                              "payment_session_id": "session_from_create_order_response",
                              "payment_method": {
                                "upi": {
                                  "channel": "link"
                                }
                              }
                            }'`}
            </CodeBlock>
          </Accordion>

          <Accordion title="Sample response">
            <CodeBlock language="json">
              {`{
                            "cf_payment_id": "14934109132",
                            "payment_method": "upi",
                            "channel": "link",
                            "action": "custom",
                            "data": {
                              "payload": {
                                "default": "upi://pay?pa=...",
                                "gpay": "upi://pay?pa=...",
                                "phonepe": "upi://pay?pa=...",
                                "paytm": "upi://pay?pa=...",
                                "bhim": "upi://pay?pa=...",
                                "web": "https://..."
                              }
                            }
                            }`}
            </CodeBlock>
          </Accordion>
        </AccordionGroup>

        Display these UPI links to customers. They can click any link to open their preferred UPI app and complete payment.
      </Tab>

      <Tab title="Hosted Checkout (Flexible)">
        Customers are redirected to Cashfree's secure checkout page, which supports cards, net banking, wallets, and UPI.

        **Include Cashfree SDK**

        <CodeBlock language="html">
          {`<script src="https://sdk.cashfree.com/js/v3/cashfree.js"></script>`}
        </CodeBlock>

        **Initialise and open checkout**

        <CodeBlock language="javascript">
          {`const cashfree = Cashfree({ mode: "sandbox" }); // or "production"

                    let checkoutOptions = {
                    paymentSessionId: "session_from_create_order_response",
                    redirectTarget: "_self" // or "_blank" to open in new tab
                    };

                    cashfree.checkout(checkoutOptions);`}
        </CodeBlock>

        Cashfree displays the checkout page with all available payment options. After payment, the customer is redirected to your `return_url` (configured during order creation).
      </Tab>
    </Tabs>
  </Step>
</Steps>

## 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](/api-reference/payments/latest/payments/get-payments-for-order):

<AccordionGroup>
  <Accordion title="Sample request">
    <CodeBlock language="bash">
      {`curl --request GET 'https://sandbox.cashfree.com/pg/orders/<order-id>/payments' \\
            --header 'accept: application/json' \\
            --header 'x-api-version: 2023-08-01' \\
            --header 'Authorization: Bearer <access_token>'`}
    </CodeBlock>
  </Accordion>

  <Accordion title="Sample response">
    <CodeBlock language="json">
      {`[
            {
              "cf_payment_id": "12376123",
              "order_id": "order_8123",
              "payment_status": "SUCCESS",
              "payment_message": "Transaction successful",
              "payment_amount": 100.00,
              "payment_time": "2021-07-23T12:15:06+05:30",
              "payment_method": {
                "upi": {
                  "channel": "collect",
                  "upi_id": "customer@bank"
                }
              },
              "bank_reference": "P78112898712",
              "auth_id": "A898101"
            }
            ]`}
    </CodeBlock>
  </Accordion>
</AccordionGroup>

Receive webhooks (asynchronous) using [Payment Webhooks API](/api-reference/payments/latest/payments/webhooks). Cashfree sends webhook events to your configured webhook URL for payment status changes and account unlinking events. Configure your webhook URL in **[Partner Dashboard](https://partner.cashfree.com/auth/login) > 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.

<Info>Verify webhook signatures using your partner API key before processing webhook events. This prevents unauthorised requests from external sources.</Info>

## 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](https://merchant.cashfree.com/auth/login) 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](/api-reference/platforms/latest/merchant-onboarding/get-merchant-status).

<AccordionGroup>
  <Accordion title="Sample request">
    <CodeBlock language="bash">
      {`curl --request GET 'https://api-sandbox.cashfree.com/partners/merchants/<merchant-id>' \\
            --header 'x-partner-apikey: <partner-api-key>' \\
            --header 'x-api-version: 2023-01-01'`}
    </CodeBlock>
  </Accordion>

  <Accordion title="Sample response">
    <CodeBlock language="json">
      {`{
            "merchant_id": "business_reference_id",
            "merchant_name": "Business Name",
            "merchant_email": "business@example.com",
            "created_at": "2024-10-23T12:25:49+05:30",
            "onboarding_status": "ACTIVE",
            "product_status": [
              {
                "product_name": "PG",
                "activation_status": "ACTIVE",
                "product_min_kyc_status": "MIN_KYC_APPROVED",
                "product_full_kyc_status": "FULL_KYC_PENDING"
              }
            ]
            }`}
    </CodeBlock>
  </Accordion>
</AccordionGroup>

### Unlink a business account

Revoke your platform's access to a business's Cashfree account. This immediately invalidates all access tokens and refresh tokens for that merchant.

<AccordionGroup>
  <Accordion title="Sample request">
    <CodeBlock language="bash">
      {`curl --location --request POST 'https://api-sandbox.cashfree.com/partners/oauth/<merchant-id>/revoke' \\
            --header 'oauth-client-id: <oauth-client-id>' \\
            --header 'x-partner-apikey: <partner-api-key>' \\
            --header 'Content-Type: application/json'`}
    </CodeBlock>
  </Accordion>

  <Accordion title="Sample response">
    <CodeBlock language="json">
      {`{
            "merchant_id": "business_reference_id",
            "connection_status": "Unlinked"
            }`}
    </CodeBlock>
  </Accordion>
</AccordionGroup>

<Warning>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.</Warning>

## Production deployment

Update the following endpoints and credentials before deploying to production:

| Environment    | API endpoint                                                          |
| -------------- | --------------------------------------------------------------------- |
| **Sandbox**    | `https://api-sandbox.cashfree.com` and `https://sandbox.cashfree.com` |
| **Production** | `https://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](https://partner.cashfree.com/auth/login) and successfully tested the entire authorisation and payment flow.

## Support and resources

Use the resources below for OAuth implementation guidance and support:

<CardGroup cols={2}>
  <Card title="Partner Dashboard" icon="grid-2" href="https://partner.cashfree.com/auth/login">
    Access OAuth credentials and configure webhook settings.
  </Card>

  <Card title="Payment Gateway API Reference" icon="book-open" href="/api-reference/payments/latest/orders/create">
    Review endpoint details for creating orders and processing payments.
  </Card>

  <Card title="Request support" icon="headset" href="https://merchant.cashfree.com/merchants/landing?env=prod&raise_issue=1">
    Get help with onboarding and technical issues from the Cashfree support team.
  </Card>
</CardGroup>

<div class="hidden" data-table-of-contents="bottom">
  <p class="mt-4 font-medium flex items-center gap-2 related-docs-heading">
    <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true" class="w-4 h-4">
      <path d="M3 4h7a2 2 0 0 1 2 2v13a2 2 0 0 0-2-2H3z" />

      <path d="M21 4h-7a2 2 0 0 0-2 2v13a2 2 0 0 1 2-2h7z" />
    </svg>

    <span>Related Topics</span>
  </p>

  <ul>
    <li><a href="/docs/partners/embedded/embedded-merchant-onboarding">Merchant Onboarding for Platforms</a></li>
    <li><a href="/docs/partners/embedded/overview">Embedded Payments Overview</a></li>
    <li><a href="/docs/partners/embedded/commissions-and-invoices">Commissions and Invoices</a></li>
    <li><a href="/docs/api-reference/payments/latest/orders/create">Payment Gateway API </a></li>
  </ul>
</div>