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

# Cashfree Agent Toolkit

> Build AI-powered payment agents with the Cashfree Agent Toolkit for LangChain, Vercel AI SDK, and OpenAI Agents SDK, exposing Cashfree APIs as tool calls.

The Cashfree Payments Agent Toolkit enables popular agent frameworks including LangChain, Vercel's AI SDK, and OpenAI's Agents SDK to integrate with Cashfree APIs through function calling. Build AI-powered payment agents that can create orders, process refunds, and manage customers programmatically.

## Pre-requisites

Ensure you meet the following requirements to get started with the Cashfree Agent Toolkit:

* Create a [Cashfree Merchant Account](https://merchant.cashfree.com/merchants/signup).
* Log in to the [Merchant Dashboard](https://merchant.cashfree.com/merchants/pg/developers/api-keys) and generate **App ID** and **Secret Key**. Learn how to [generate API keys](/api-reference/authentication#generate-api-keys).
* Ensure Node.js version 18 or later is installed.

## Installation

Install the toolkit using your preferred package manager:

<CodeGroup>
  ```bash npm theme={"dark"}
  npm install @cashfreepayments/agent-toolkit
  ```

  ```bash yarn theme={"dark"}
  yarn add @cashfreepayments/agent-toolkit
  ```

  ```bash pnpm theme={"dark"}
  pnpm add @cashfreepayments/agent-toolkit
  ```
</CodeGroup>

## Framework support

The toolkit supports multiple frameworks, exposed through sub-paths:

| Framework     | Import path                                 | Description                             |
| ------------- | ------------------------------------------- | --------------------------------------- |
| OpenAI        | `@cashfreepayments/agent-toolkit/openai`    | For Chat Completions API and Agents SDK |
| LangChain     | `@cashfreepayments/agent-toolkit/langchain` | For LangChain agents                    |
| Vercel AI SDK | `@cashfreepayments/agent-toolkit/ai-sdk`    | For Vercel's AI SDK                     |

## Usage

Each toolkit is initialised with your Cashfree credentials and environment configuration.

<CodeGroup>
  ```javascript OpenAI theme={"dark"}
  import {
    CashfreeAgentToolkit,
    CFEnvironment,
  } from '@cashfreepayments/agent-toolkit/openai';

  const environment = CFEnvironment.SANDBOX; // or PRODUCTION
  const clientId = process.env.CASHFREE_CLIENT_ID;
  const clientSecret = process.env.CASHFREE_CLIENT_SECRET;

  const cashfree = new CashfreeAgentToolkit(environment, clientId, clientSecret);
  ```

  ```javascript LangChain theme={"dark"}
  import {
    CashfreeAgentToolkit,
    CFEnvironment,
  } from '@cashfreepayments/agent-toolkit/langchain';

  const environment = CFEnvironment.SANDBOX; // or PRODUCTION
  const clientId = process.env.CASHFREE_CLIENT_ID;
  const clientSecret = process.env.CASHFREE_CLIENT_SECRET;

  const cashfree = new CashfreeAgentToolkit(environment, clientId, clientSecret);
  ```

  ```javascript Vercel AI SDK theme={"dark"}
  import {
    CashfreeAISDKToolkit,
    CFEnvironment,
  } from '@cashfreepayments/agent-toolkit/ai-sdk';

  const environment = CFEnvironment.SANDBOX; // or PRODUCTION
  const clientId = process.env.CASHFREE_CLIENT_ID;
  const clientSecret = process.env.CASHFREE_CLIENT_SECRET;

  const cashfree = new CashfreeAISDKToolkit(environment, clientId, clientSecret);
  ```
</CodeGroup>

## Available tools

The toolkit provides the following tools for payment operations:

| Tool                       | Description                                    |
| -------------------------- | ---------------------------------------------- |
| `createOrder`              | Create a new order                             |
| `getOrder`                 | Retrieve details of an existing order          |
| `terminateOrder`           | Terminate or cancel an order                   |
| `createRefund`             | Initiate a refund for an order                 |
| `getAllRefunds`            | List all refunds for an order                  |
| `getRefund`                | Retrieve details of a specific refund          |
| `orderPayUsingUpi`         | Pay for an order using UPI                     |
| `orderPayUsingNetbanking`  | Pay for an order using Netbanking              |
| `orderPayUsingApp`         | Pay for an order using a payment app           |
| `orderPayUsingPlainCard`   | Pay for an order using a plain card            |
| `orderPayUsingSavedCard`   | Pay for an order using a saved card            |
| `createCustomer`           | Create a new customer in Cashfree              |
| `fetchCustomerInstruments` | Fetch saved payment instruments for a customer |

## Framework-specific examples

The following examples demonstrate how to use the toolkit with each supported framework.

<Tabs>
  <Tab title="OpenAI">
    The OpenAI integration works with both Chat Completions API and the Agents SDK.

    ### Initialise the toolkit

    Set up the Cashfree Agent Toolkit with your credentials and environment configuration.

    <CodeGroup>
      ```javascript Initialisation theme={"dark"}
      import {
        CashfreeAgentToolkit,
        CFEnvironment,
      } from "@cashfreepayments/agent-toolkit/openai";

      const cashfreeToolkit = new CashfreeAgentToolkit(
        CFEnvironment.SANDBOX,
        process.env.CASHFREE_CLIENT_ID,
        process.env.CASHFREE_CLIENT_SECRET,
      );
      ```
    </CodeGroup>

    ### With Chat Completions API

    Use the toolkit with OpenAI's Chat Completions API by passing the tools as JSON schema.

    <CodeGroup>
      ```javascript Chat Completions theme={"dark"}
      const completion = await openai.chat.completions.create({
        model: 'gpt-4o',
        messages: [...],
        tools: cashfreeToolkit.getTools(), // Returns JSON schema
      });
      ```

      ```javascript Access individual tools theme={"dark"}
      const tool = cashfreeToolkit.tools.createOrder;
      // Execute manually if needed
      const result = await tool.execute({...});
      ```
    </CodeGroup>

    ### With OpenAI Agents SDK

    Integrate the toolkit with OpenAI's Agents SDK for building autonomous payment agents.

    <CodeGroup>
      ```javascript All tools theme={"dark"}
      import { Agent } from "@openai/agents";

      const agent = new Agent({
        model: "gpt-4o",
        tools: cashfreeToolkit.getAgentTools(),
      });
      ```

      ```javascript Specific tools theme={"dark"}
      import { Agent, run } from "@openai/agents";

      const agent = new Agent({
        name: "Order Details Fetching Agent",
        instructions: "You are a helpful assistant that fetches and returns order details",
        model: "gpt-4o",
        tools: [cashfreeToolkit.tools.createOrder, cashfreeToolkit.tools.getOrder],
      });

      const result = await run(agent, "Get details of order: order_12345678");
      ```
    </CodeGroup>

    For detailed OpenAI documentation, see the [OpenAI integration guide](https://github.com/cashfree/agent-tools-js/blob/main/src/openai/README.md).
  </Tab>

  <Tab title="LangChain">
    The LangChain integration enables LangChain agents to integrate with Cashfree APIs.

    ### Initialise the toolkit

    Set up the Cashfree Agent Toolkit with your credentials and environment configuration.

    <CodeGroup>
      ```javascript Initialisation theme={"dark"}
      import {
        CashfreeAgentToolkit,
        CFEnvironment,
      } from "@cashfreepayments/agent-toolkit/langchain";

      const cashfreeToolkit = new CashfreeAgentToolkit(
        CFEnvironment.SANDBOX,
        process.env.CASHFREE_CLIENT_ID,
        process.env.CASHFREE_CLIENT_SECRET,
      );
      ```
    </CodeGroup>

    ### Load tools into an agent

    Load all available Cashfree payment tools into your LangChain agent or select specific tools your agent needs for more focused functionality.

    <CodeGroup>
      ```javascript All tools theme={"dark"}
      import { createAgent } from "langchain";

      const tools = cashfreeToolkit.getTools();
      const agent = createAgent({ model, tools });
      ```

      ```javascript Specific tools theme={"dark"}
      const tools = [
        cashfreeToolkit.toolsMap.createOrder,
        cashfreeToolkit.toolsMap.getOrder,
      ];
      const agent = createAgent({ model, tools });
      ```
    </CodeGroup>

    For detailed LangChain documentation, see the [LangChain integration guide](https://github.com/cashfree/agent-tools-js/blob/main/src/langchain/README.md).
  </Tab>

  <Tab title="Vercel AI SDK">
    The Vercel AI SDK integration enables Vercel's AI SDK to integrate with Cashfree APIs through function calling.

    ### Initialise the toolkit

    Set up the Cashfree AI SDK Toolkit with your credentials and environment configuration.

    <CodeGroup>
      ```javascript Initialisation theme={"dark"}
      import {
        CashfreeAISDKToolkit,
        CFEnvironment,
      } from "@cashfreepayments/agent-toolkit/ai-sdk";

      const cashfreeToolkit = new CashfreeAISDKToolkit(
        CFEnvironment.SANDBOX,
        process.env.CASHFREE_CLIENT_ID,
        process.env.CASHFREE_CLIENT_SECRET,
      );
      ```
    </CodeGroup>

    ### Use tools with generateText

    Load all available Cashfree payment tools for comprehensive functionality or select specific tools your application needs for more focused functionality.

    <CodeGroup>
      ```javascript Specific tools theme={"dark"}
      import { generateText } from "ai";
      import { openai } from "@ai-sdk/openai";

      const result = await generateText({
        model: openai("gpt-4o"),
        tools: {
          createOrder: cashfreeToolkit.tools.createOrder,
          getOrder: cashfreeToolkit.tools.getOrder,
        },
        prompt: "Create an order for Rs. 500",
      });
      ```

      ```javascript All tools theme={"dark"}
      import { generateText } from "ai";
      import { openai } from "@ai-sdk/openai";

      const result = await generateText({
        model: openai("gpt-4o"),
        tools: cashfreeToolkit.getTools(),
        prompt: "Create an order for Rs. 500",
      });
      ```
    </CodeGroup>

    For detailed Vercel AI SDK documentation, see the [AI SDK integration guide](https://github.com/cashfree/agent-tools-js/blob/main/src/ai-sdk/README.md).
  </Tab>
</Tabs>

## Example payment agent

The following example demonstrates a complete payment agent using the OpenAI Agents SDK:

<CodeGroup>
  ```javascript Payment agent theme={"dark"}
  import { Agent, run } from '@openai/agents';
  import {
    CashfreeAgentToolkit,
    CFEnvironment,
  } from '@cashfreepayments/agent-toolkit/openai';

  // Initialize the toolkit
  const cashfree = new CashfreeAgentToolkit(
    CFEnvironment.SANDBOX,
    process.env.CASHFREE_CLIENT_ID,
    process.env.CASHFREE_CLIENT_SECRET
  );

  // Create an agent with all payment tools
  const agent = new Agent({
    name: 'Payment Agent',
    instructions: 'You are a helpful payment assistant.',
    model: 'gpt-4o',
    tools: cashfree.getAgentTools(),
  });

  // Run the agent
  const result = await run(
    agent,
    'Look up customer cust_123 and create an order for Rs. 500'
  );
  ```
</CodeGroup>

## Resources

Explore additional resources to help you get started with the Cashfree Agent Toolkit.

<CardGroup cols={2}>
  <Card title="GitHub Repository" icon="github" href="https://github.com/cashfree/agent-tools-js">
    View the source code, report issues, and contribute to the toolkit.
  </Card>

  <Card title="npm Package" icon="npm" href="https://www.npmjs.com/package/@cashfreepayments/agent-toolkit">
    View the package on npm for installation and version details.
  </Card>
</CardGroup>