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

# Checkout

Drop-in widgets for wallet connection, token swaps, bridging, fiat onramps, and primary sales.

<Card title="Sample App" icon="github" href="https://github.com/immutable/ts-immutable-sdk/tree/main/examples/checkout/commerce-widget-nextjs">
  View a complete working example
</Card>

## Why Use Checkout?

<AccordionGroup>
  <Accordion title="Fast Integration" icon="bolt">
    Mount pre-built widgets instead of building complex transaction UIs. Handle swaps, bridges, and payments with a few lines of code.
  </Accordion>

  <Accordion title="Abstracts Complexity" icon="wand-magic-sparkles">
    Users don't need to understand gas, bridges, or DEXs. The widget guides them through each flow with clear UI.
  </Accordion>

  <Accordion title="Customizable" icon="palette">
    Match your app's theme with built-in dark/light modes and language localization.
  </Accordion>

  <Accordion title="Passport + External Wallets" icon="wallet">
    Works with Passport, MetaMask, WalletConnect, and any EIP-1193 compatible wallet.
  </Accordion>
</AccordionGroup>

<Info>
  **Prerequisites:** Checkout requires wallet authentication. We recommend [Passport](/docs/products/passport/overview) for seamless wallet creation and login, but you can also use MetaMask, WalletConnect, or any EIP-1193 compatible wallet.
</Info>

## Wallet Funding: Which Flow to Use?

Choose the right funding method based on your users' starting point:

| User Has               | Best Flow                                | Why                                                |
| ---------------------- | ---------------------------------------- | -------------------------------------------------- |
| No crypto              | [Onramp](/docs/products/checkout/onramp) | Buy crypto with credit card, Apple Pay, Google Pay |
| Funds on Ethereum L1   | [Bridge](/docs/products/checkout/bridge) | Transfer tokens from Ethereum mainnet to zkEVM     |
| Wrong token on zkEVM   | [Swap](/docs/products/checkout/swap)     | Exchange tokens on Immutable Chain via QuickSwap   |
| Funds on another chain | [Fund](/docs/products/checkout/fund)     | Smart routing via swap/bridge/onramp               |

<Info>
  **Need help choosing?** See individual flow pages for detailed "when to use" guidance and platform-specific examples (TypeScript, Unity, Unreal).
</Info>

## Available Flows

| Flow                                       | Description                                         | Platforms                 |
| ------------------------------------------ | --------------------------------------------------- | ------------------------- |
| [Connect](/docs/products/checkout/connect) | Connect wallets (Passport, MetaMask, WalletConnect) | TypeScript                |
| [Wallet](/docs/products/checkout/wallet)   | View balances, access other flows                   | TypeScript                |
| [Onramp](/docs/products/checkout/onramp)   | Buy crypto with fiat currency                       | TypeScript, Unity, Unreal |
| [Swap](/docs/products/checkout/swap)       | Exchange tokens on Immutable Chain                  | TypeScript, Unity, Unreal |
| [Bridge](/docs/products/checkout/bridge)   | Move tokens between Ethereum and Immutable Chain    | TypeScript, Unity, Unreal |
| [Fund](/docs/products/checkout/fund)       | Smart token acquisition with automatic routing      | TypeScript                |
| [Sale](/docs/products/checkout/sale)       | Sell NFTs with integrated payment handling          | TypeScript                |

## Platform-Specific Implementation

<Tabs>
  <Tab title="TypeScript">
    **Full widget integration** - Mount widgets directly in your web application with React/Vue/vanilla JS.

    See individual flow pages ([Onramp](/docs/products/checkout/onramp), [Swap](/docs/products/checkout/swap), [Bridge](/docs/products/checkout/bridge)) for complete TypeScript examples with installation, code, and configuration.
  </Tab>

  <Tab title="Unity">
    **URL generation** - Generate URLs and open in system browser for security and compatibility.

    **Setup:** [Unity SDK – Marketplace package](/docs/sdks/unity/overview)

    **Implementation:** Each flow page has a dedicated Unity tab with C# examples and configuration options.
  </Tab>

  <Tab title="Unreal">
    **URL generation** - Generate URLs and open in system browser for security and compatibility.

    **Setup:** [Unreal SDK](/docs/sdks/unreal/overview)

    **Implementation:** Each flow page has a dedicated Unreal tab with C++ examples, Blueprint guidance, and configuration options.
  </Tab>
</Tabs>

## TypeScript Quick Start

### Installation

<Tabs>
  <Tab title="npm">
    ```bash theme={null}
    npm install @imtbl/sdk
    ```
  </Tab>

  <Tab title="yarn">
    ```bash theme={null}
    yarn add @imtbl/sdk
    ```
  </Tab>
</Tabs>

### Initialize Checkout

```typescript theme={null}
import { checkout } from '@imtbl/sdk';
import { Environment } from '@imtbl/sdk/config';

const { Checkout, WidgetType, WidgetTheme } = checkout;

const checkoutSDK = new Checkout({
  baseConfig: {
    environment: Environment.SANDBOX, // or Environment.PRODUCTION
    publishableKey: 'YOUR_PUBLISHABLE_KEY',
  },
});
```

```typescript theme={null}
// Create widgets factory
const widgets = await checkoutSDK.widgets({
  config: {
    theme: WidgetTheme.DARK, // or LIGHT
  },
});

// Create and mount a widget
const widget = widgets.create(WidgetType.IMMUTABLE_COMMERCE);
widget.mount('widget-root', {
  flow: 'ONRAMP' // or 'SWAP', 'BRIDGE', 'SALE', etc.
});
```

<Info>
  For complete examples with event handling and configuration options, see individual flow pages.
</Info>

## Configuration Options

### Widget Configuration

| Option     | Values                         | Description                 |
| ---------- | ------------------------------ | --------------------------- |
| `theme`    | `'dark'`, `'light'`            | Widget color theme          |
| `language` | `'en'`, `'ja'`, `'ko'`, `'zh'` | UI language                 |
| `version`  | `{ major, minor, patch }`      | Pin to specific SDK version |

### Widget Methods

All commerce widgets share these methods:

| Method                         | Description                 |
| ------------------------------ | --------------------------- |
| `mount(elementId, params)`     | Mount widget to DOM element |
| `update(config)`               | Update widget configuration |
| `addListener(event, callback)` | Listen to events            |
| `removeListener(event)`        | Remove event listener       |
| `unmount()`                    | Clean up widget             |

### Common Events

All flows emit these events:

| Event              | Description                 | Payload            |
| ------------------ | --------------------------- | ------------------ |
| `INITIALISED`      | Widget loaded and ready     | —                  |
| `CLOSE`            | User clicked close button   | —                  |
| `SUCCESS`          | Flow completed successfully | Flow-specific data |
| `FAILURE`          | Error occurred              | `{ error }`        |
| `PROVIDER_UPDATED` | Wallet provider changed     | `{ provider }`     |

## Integration Guides

<CardGroup cols={2}>
  <Card title="Build a Marketplace" icon="store" href="/docs/guides/build-a-marketplace">
    Complete marketplace with wallet funding
  </Card>

  <Card title="Build a Game" icon="gamepad" href="/docs/guides/build-a-game">
    Start with game basics first
  </Card>

  <Card title="Passport Integration" icon="passport" href="/docs/products/passport/overview">
    Wallet creation and authentication
  </Card>

  <Card title="Get API Keys" icon="key" href="/docs/products/hub/api-keys">
    Setup Hub credentials
  </Card>
</CardGroup>

## Next Steps

<CardGroup cols={3}>
  <Card title="Onramp" icon="credit-card" href="/docs/products/checkout/onramp">
    Buy crypto with fiat
  </Card>

  <Card title="Swap" icon="arrow-right-arrow-left" href="/docs/products/checkout/swap">
    Exchange tokens
  </Card>

  <Card title="Bridge" icon="bridge" href="/docs/products/checkout/bridge">
    Transfer from L1
  </Card>

  <Card title="Primary Sales" icon="tag" href="/docs/products/checkout/sale">
    Sell NFTs to players
  </Card>

  <Card title="Unity SDK" icon="gamepad" href="/docs/sdks/unity/overview">
    Unity implementation
  </Card>

  <Card title="Unreal SDK" icon="gamepad" href="/docs/sdks/unreal/overview">
    Unreal implementation
  </Card>
</CardGroup>