> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tender.cash/llms.txt
> Use this file to discover all available pages before exploring further.

# JavaScript SDK

> Integrate Tender cryptocurrency payments in your JavaScript and React applications

## Overview

This page contains full documentation for both JavaScript SDK tracks:

* **Latest SDK**: `@tender-cash/js-sdk`
* **Legacy SDK (Old Version)**: `@tender-cash/agent-sdk-react`

<Tabs>
  <Tab title="Latest SDK">
    ## Package

    <Card title="@tender-cash/js-sdk" icon="js" href="https://www.npmjs.com/package/@tender-cash/js-sdk">
      Current JavaScript SDK package
    </Card>

    ***

    ## Installation

    <CodeGroup>
      ```bash npm theme={null}
      npm install @tender-cash/js-sdk
      ```

      ```bash yarn theme={null}
      yarn add @tender-cash/js-sdk
      ```

      ```bash pnpm theme={null}
      pnpm add @tender-cash/js-sdk
      ```
    </CodeGroup>

    ***

    ## Usage in React

    Use `TenderSdk` as the primary component.
    `TenderAgentSdk` is still exported as a backward-compatible alias.

    ```tsx theme={null}
    import { TenderSdk, onFinishResponse } from '@tender-cash/js-sdk';

    function PaymentComponent() {
      const handleEventResponse = (response: onFinishResponse) => {
        console.log('SDK Response:', response);
      };

      return (
        <TenderSdk
          accessId="YOUR_ACCESS_ID"
          fiatCurrency="USD"
          env="test"
          onEventResponse={handleEventResponse}
          amount={150}
          referenceId="unique-payment-reference-123"
          paymentExpirySeconds={1800}
        />
      );
    }
    ```

    <Info>
      When `referenceId` and `amount` are provided, the modal auto-opens on component mount.
    </Info>

    ***

    ## API Reference

    ### Component Props (`TenderAgentProps`)

    Applies to both `TenderSdk` and `TenderAgentSdk`.

    #### Required Props

    | Prop           | Type                              | Description                                |
    | -------------- | --------------------------------- | ------------------------------------------ |
    | `accessId`     | `string`                          | Your Tender merchant Access ID.            |
    | `fiatCurrency` | `string`                          | Fiat code, e.g. `"USD"`, `"EUR"`, `"NGN"`. |
    | `env`          | `"test"` \| `"live"` \| `"local"` | Target environment.                        |

    #### Optional Props

    | Prop                   | Type                               | Description                                          |
    | ---------------------- | ---------------------------------- | ---------------------------------------------------- |
    | `onEventResponse`      | `(data: onFinishResponse) => void` | Called when payment state changes.                   |
    | `referenceId`          | `string`                           | Payment reference. Required for auto-open mode.      |
    | `amount`               | `number`                           | Payment amount in fiat. Required for auto-open mode. |
    | `paymentExpirySeconds` | `number`                           | Payment expiration in seconds.                       |
    | `theme`                | `"light"` \| `"dark"`              | Modal theme.                                         |
    | `closeModal`           | `() => void`                       | Callback fired when modal closes.                    |

    ***

    ## Ref Usage

    ```tsx theme={null}
    import { useRef } from 'react';
    import { TenderSdk, TenderRef } from '@tender-cash/js-sdk';

    function PaymentComponent() {
      const tenderRef = useRef<TenderRef>(null);

      const openPayment = () => {
        tenderRef.current?.initiatePayment({
          amount: 150,
          referenceId: `order-${Date.now()}`,
          paymentExpirySeconds: 1800
        });
      };

      const closePayment = () => {
        tenderRef.current?.dismiss();
      };

      return (
        <>
          <button onClick={openPayment}>Open Payment</button>
          <button onClick={closePayment}>Close Modal</button>
          <TenderSdk ref={tenderRef} accessId="YOUR_ACCESS_ID" fiatCurrency="USD" env="test" />
        </>
      );
    }
    ```

    ### Ref Methods (`TenderRef`)

    | Method            | Description                                              |
    | ----------------- | -------------------------------------------------------- |
    | `initiatePayment` | Opens modal and starts payment with provided parameters. |
    | `dismiss`         | Closes the modal.                                        |

    ***

    ## Callback Data (`onFinishResponse`)

    ```typescript theme={null}
    interface onFinishResponse {
      status: "partial-payment" | "completed" | "overpayment" | "pending" | "error" | "cancelled";
      message: string;
      data: IPaymentData | undefined;
    }
    ```

    ***

    ## Features

    * Shadow DOM style isolation
    * Auto-open mode from props
    * Programmatic control with refs
    * TypeScript support
    * Works across desktop and mobile
  </Tab>

  <Tab title="Legacy SDK (Old Version)">
    <Warning>
      This is the old SDK version. New integrations should use `@tender-cash/js-sdk`.
    </Warning>

    ## Package

    <Card title="@tender-cash/agent-sdk-react" icon="clock-rotate-left" href="https://www.npmjs.com/package/@tender-cash/agent-sdk-react">
      Legacy package (previous SDK version)
    </Card>

    ***

    ## Installation

    <CodeGroup>
      ```bash npm theme={null}
      npm install @tender-cash/agent-sdk-react
      ```

      ```bash yarn theme={null}
      yarn add @tender-cash/agent-sdk-react
      ```

      ```bash pnpm theme={null}
      pnpm add @tender-cash/agent-sdk-react
      ```
    </CodeGroup>

    ***

    ## Usage in React

    ```jsx theme={null}
    import { TenderAgentSdk, onFinishResponse } from '@tender-cash/agent-sdk-react';

    function PaymentComponent() {
      const handleEventResponse = (response: onFinishResponse) => {
        console.log('SDK Response:', response);
      };

      return (
        <TenderAgentSdk
          accessId="YOUR_ACCESS_ID"
          fiatCurrency="USD"
          env="test"
          onEventResponse={handleEventResponse}
          amount={150.00}
          referenceId="unique-payment-reference-123"
          paymentExpirySeconds={1800}
        />
      );
    }
    ```

    ***

    ## API Reference

    ### Component Props (`TenderAgentProps`)

    #### Required Props

    | Prop           | Type                              | Description                                  |
    | -------------- | --------------------------------- | -------------------------------------------- |
    | `fiatCurrency` | `string`                          | Fiat currency code, e.g. `"USD"` or `"EUR"`. |
    | `accessId`     | `string`                          | Your Tender merchant Access ID.              |
    | `env`          | `"test"` \| `"live"` \| `"local"` | Target environment.                          |

    #### Optional Props

    | Prop                   | Type                               | Description                                          |
    | ---------------------- | ---------------------------------- | ---------------------------------------------------- |
    | `onEventResponse`      | `(data: onFinishResponse) => void` | Called when payment status updates.                  |
    | `referenceId`          | `string`                           | Payment reference. Required for auto-open mode.      |
    | `amount`               | `number`                           | Payment amount in fiat. Required for auto-open mode. |
    | `paymentExpirySeconds` | `number`                           | Payment expiration in seconds.                       |
    | `theme`                | `"light"` \| `"dark"`              | Modal theme.                                         |

    ***

    ## Ref Usage

    ```jsx theme={null}
    import { useRef } from 'react';
    import { TenderAgentSdk, TenderAgentRef } from '@tender-cash/agent-sdk-react';

    function PaymentComponent() {
      const tenderRef = useRef<TenderAgentRef>(null);

      const handleOpenPayment = () => {
        tenderRef.current?.initiatePayment({
          amount: 150.00,
          referenceId: "unique-payment-reference-123",
          paymentExpirySeconds: 1800
        });
      };

      const handleCloseModal = () => {
        tenderRef.current?.closeModal();
      };

      return (
        <>
          <button onClick={handleOpenPayment}>Open Payment</button>
          <button onClick={handleCloseModal}>Close Modal</button>
          <TenderAgentSdk ref={tenderRef} accessId="YOUR_ACCESS_ID" fiatCurrency="USD" env="test" />
        </>
      );
    }
    ```

    ### Ref Methods (`TenderAgentRef`)

    | Method            | Description                                              |
    | ----------------- | -------------------------------------------------------- |
    | `initiatePayment` | Opens modal and starts payment with provided parameters. |
    | `dismiss`         | Closes the modal.                                        |
    | `closeModal`      | Closes the modal from outside the widget.                |

    ***

    ## Callback Data (`onFinishResponse`)

    ```typescript theme={null}
    interface onFinishResponse {
      status: "partial-payment" | "completed" | "overpayment" | "pending" | "error" | "cancelled";
      message: string;
      data: IPaymentData | undefined;
    }
    ```

    ***

    ## Features

    * Shadow DOM style isolation
    * Auto-open modal flow
    * TypeScript support
    * Responsive payment UI
  </Tab>
</Tabs>

***

## Next Steps

<CardGroup cols={2}>
  <Card title="API Reference" icon="book" href="/api-reference/introduction">
    Explore the full API documentation
  </Card>

  <Card title="Webhooks" icon="webhook" href="/get-started/webhooks">
    Set up webhook notifications
  </Card>

  <Card title="GitHub" icon="github" href="https://github.com/tender-cash">
    View source repositories
  </Card>

  <Card title="Support" icon="envelope" href="mailto:support@tender.cash">
    Contact our support team
  </Card>
</CardGroup>