npm package: @spiinlabs/merchant
Description: Checkout component for Spiin.gg
Author: Spiin
Latest version: 0.0.660

# Spiin SDK

A TypeScript React component library for seamless checkout integrations with Spiin's gaming platform.

## Description

The Spiin SDK provides React components that enable applications to integrate Spiin's checkout system through secure modal-based workflows.

## Installation

```bash
npm install @spiinlabs/merchant
```

## Quick Start

```tsx
import React from "react";
import { SpiinButton } from "@spiinlabs/merchant";

function App() {
    return (
        <SpiinButton
            apiKey="pk_test_your-api-key"
            merchantId="your-merchant-id"
            env="sandbox"
            order={{
                subTotal: 1000,
                title: "Demo Product",
                lineItems: [
                    {
                        title: "Demo Product",
                        value: 1000,
                        quantity: 1,
                    },
                ],
            }}
            onCheckoutSuccess={(data) => {
                console.log("success\n spinId:", data.spinId);
            }}
            size="md"
        />
    );
}
```

## Components

### SpiinButton

The main component that renders a customizable button and handles modal interactions.

#### Props

| Prop                | Type                                 | Default      | Description                                |
| ------------------- | ------------------------------------ | ------------ | ------------------------------------------ |
| `apiKey`            | `string`                             | **required** | Your Spiin API key for authentication      |
| `merchantId`        | `string`                             | **required** | Your Spiin merchant ID                     |
| `env`               | `'sandbox' \| 'production'`          | `'sandbox'`  | Environment (sandbox or production)        |
| `order`             | `Order`                              | **required** | Order details for the checkout             |
| `onCheckoutSuccess` | `(data: { spinId: string }) => void` | -            | Callback on successful checkout completion |
| `size`              | `'sm' \| 'md' \| 'lg'`               | `'md'`       | Button size                                |
| `className`         | `string`                             | `''`         | Additional CSS classes                     |
| `disabled`          | `boolean`                            | `false`      | Disable button interaction                 |

#### Example

```tsx
import { SpiinButton } from "@spiinlabs/merchant";

function MyComponent() {
    return (
        <>
            <SpiinButton
                apiKey="pk_test_your-api-key"
                merchantId="your-merchant-id"
                env="sandbox"
                order={{
                    subTotal: 10000,
                    title: "Test Order",
                    lineItems: [
                        {
                            title: "Test Item",
                            value: 10000,
                            quantity: 1,
                        },
                    ],
                }}
                onCheckoutSuccess={(data) => {
                    console.log("success\n spinId:", data.spinId);
                }}
                size="md"
            />
        </>
    );
}
```

## Spiin Checkout Verification Flow

You can use Spiin endpoints in your backend flow to verify the `spinId` from `onCheckoutSuccess` event.

#### Endpoints

Env: sandbox

```
https://spiin-frontend-git-dev-spiins-projects.vercel.app/api/checkout/verify/spin
```

Env: production

```
https://spiin.gg/api/checkout/verify/spin
```

#### Example

```ts
const res = await fetch(endpoint, {
    method: "POST",
    headers: {
        "Content-Type": "application/json",
        Authorization: `Bearer ${apiKey}`, // Merchant Api Key
    },
    body: {
        merchantId, // Merchant Id
        spinId, // spinId from onCheckoutSuccess event
    },
});

const {
    isWin,
    validSpin,
}: {
    isWin: boolean;
    validSpin: boolean;
} = await res.json();
```

## TypeScript Support

The SDK is built with TypeScript and provides comprehensive type definitions:

```tsx
import type { SpiinButtonProps } from "@spiinlabs/merchant";
```

## Browser Support

-   Chrome 88+
-   Firefox 85+
-   Safari 14+
-   Edge 88+

## Peer Dependencies

```json
{
    "react": ">=16.8.0",
    "react-dom": ">=16.8.0"
}
```

## Changelog

### [0.0.660] - 2025-09-03

#### Docs update

### [0.0.658] - 2025-07-30

#### Fixes

-   **Spiin Verification**: Security layer to verify the post success checkout metadata

### [0.0.657] - 2025-07-28

#### Fixes

-   **Body Scroll**: Parent body is not locked while modal is active
-   **Bug Fixes**: Bug fixes

### [0.0.653] - 2025-07-23

#### Changed

-   **Auth Rework**: Auth now works seamlessly without using 3rd-party cookies which gets blocked on safari

### [0.0.641] - 2025-07-22

#### Fixes

-   **Dynamic Height**: Fixed dynamic height issue with modal iframe on phones
-   **Iframe Clipboard**: Copy button now works for AMOE Codes

### [0.0.62] - 2025-07-18

#### Bug Fixes

### [0.0.5] - 2025-07-18

#### Fixed

-   **React 19 Compatibility**: Fixed `ReactCurrentDispatcher` error when using with React 19 and Next.js 15.3.3
-   **Bundle Optimization**: Switched to classic JSX transform to eliminate jsx-runtime dependencies
-   **External Dependencies**: Improved Vite configuration to properly externalize React and prevent version conflicts
-   **TypeScript Configuration**: Updated JSX transform settings to match build configuration

#### Changed

-   Updated peer dependencies to support React 19
-   Reduced bundle size by properly externalizing React dependencies
-   Improved build configuration for better compatibility across React versions

### [0.0.4] - 2025-07-18

#### Added

-   Initial release of Spiin SDK
-   `SpiinButton` component which triggers a checkout modal
-   Full TypeScript support with comprehensive type definitions
-   Event handling system for modal lifecycle

#### Features

-   Three button sizes: small, medium, large
-   Modal system with iframe integration
-   Success/error callback handling
-   Test mode indicator for development

## License

MIT

## Support

For questions, issues, or feature requests, please contact the Spiin team at team@spiin.gg