@tender-cash/js-sdk

React SDK for integrating Tender Cash checkout in your app.

Installation

Using yarn:

yarn add @tender-cash/js-sdk

Using npm:

npm install @tender-cash/js-sdk

Exports

• TenderSdk (recommended component)
• TenderAgentSdk (deprecated alias of TenderSdk)
• TenderProps (recommended props type)
• TenderAgentProps (deprecated alias of TenderProps)
• TenderRef (recommended ref type)
• TenderAgentRef (deprecated alias of TenderRef)
• onFinishResponse

Quick Start

Use TenderSdk (recommended).
TenderAgentSdk is still exported as a backward-compatible alias.

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}
    />
  );
}

When referenceId and amount are provided as props, the modal auto-opens on mount.

API Reference

Component Props (TenderProps)

Applies to both TenderSdk and TenderAgentSdk.

Required Props

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

Optional Props

| Prop | Type | Description | |-----------------------|------------------------------------|-------------| | onEventResponse | (data: onFinishResponse) => void | Called when payment state updates. | | referenceId | string | Payment reference ID (required for auto-open mode). | | amount | number | Payment amount in fiat (required for auto-open mode). | | paymentExpirySeconds| number | Payment expiry in seconds. | | theme | "light" \| "dark" | Modal theme. | | closeModal | () => void | Callback fired when modal is closed. |

Ref Usage

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: "unique-payment-reference-123",
      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 the modal and initiates a payment. | | dismiss | Closes the modal. |

Callback Shape (onFinishResponse)

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

Features

• Shadow DOM style isolation
• Auto-open mode with direct props
• Programmatic control via ref
• Expiry countdown uses absolute timestamps for accurate background-tab behavior
• TypeScript support

Migration Notes

If you are upgrading from older naming:

• TenderAgentProps -> TenderProps
• TenderAgentRef -> TenderRef
• TenderAgentSdk -> TenderSdk (old name still works)

License

MIT