> ## 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] [Sample App](https://github.com/immutable/ts-immutable-sdk/tree/main/examples/checkout/commerce-widget-nextjs)
>
> View a complete working example

## Why Use Checkout?

> [accordion] Fast Integration
>
> Mount pre-built widgets instead of building complex transaction UIs. Handle swaps, bridges, and payments with a few lines of code.

> [accordion] Abstracts Complexity
>
> Users don't need to understand gas, bridges, or DEXs. The widget guides them through each flow with clear UI.

> [accordion] Customizable
>
> Match your app's theme with built-in dark/light modes and language localization.

> [accordion] Passport + External Wallets
>
> Works with Passport, MetaMask, WalletConnect, and any EIP-1193 compatible wallet.

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

## 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](https://docs.immutable.com/docs/products/checkout/onramp.md) | Buy crypto with credit card, Apple Pay, Google Pay |
| Funds on Ethereum L1 | [Bridge](https://docs.immutable.com/docs/products/checkout/bridge.md) | Transfer tokens from Ethereum mainnet to zkEVM |
| Wrong token on zkEVM | [Swap](https://docs.immutable.com/docs/products/checkout/swap.md) | Exchange tokens on Immutable Chain via QuickSwap |
| Funds on another chain | [Fund](https://docs.immutable.com/docs/products/checkout/fund.md) | Smart routing via swap/bridge/onramp |

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

## Available Flows

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

## Platform-Specific Implementation

> [tab] TypeScript
>
> **Full widget integration** - Mount widgets directly in your web application with React/Vue/vanilla JS.
>
> See individual flow pages ([Onramp](https://docs.immutable.com/docs/products/checkout/onramp.md), [Swap](https://docs.immutable.com/docs/products/checkout/swap.md), [Bridge](https://docs.immutable.com/docs/products/checkout/bridge.md)) for complete TypeScript examples with installation, code, and configuration.

> [tab] Unity
>
> **URL generation** - Generate URLs and open in system browser for security and compatibility.
>
> **Setup:** [Unity SDK – Marketplace package](https://docs.immutable.com/docs/sdks/unity/overview.md)
>
> **Implementation:** Each flow page has a dedicated Unity tab with C# examples and configuration options.

> [tab] Unreal
>
> **URL generation** - Generate URLs and open in system browser for security and compatibility.
>
> **Setup:** [Unreal SDK](https://docs.immutable.com/docs/sdks/unreal/overview.md)
>
> **Implementation:** Each flow page has a dedicated Unreal tab with C++ examples, Blueprint guidance, and configuration options.

## TypeScript Quick Start

### Installation

> [tab] npm
>
> ```bash theme={null}
> npm install @imtbl/sdk
> ```

> [tab] yarn
>
> ```bash theme={null}
> yarn add @imtbl/sdk
> ```

### 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.
});
```

> [!NOTE]
>
> For complete examples with event handling and configuration options, see individual flow pages.

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

> [card] [Build a Marketplace](https://docs.immutable.com/docs/guides/build-a-marketplace.md)
>
> Complete marketplace with wallet funding

> [card] [Build a Game](https://docs.immutable.com/docs/guides/build-a-game.md)
>
> Start with game basics first

> [card] [Passport Integration](https://docs.immutable.com/docs/products/passport/overview.md)
>
> Wallet creation and authentication

> [card] [Get API Keys](https://docs.immutable.com/docs/guides/advanced-setup/api-keys.md)
>
> Setup Hub credentials

## Next Steps

> [card] [Onramp](https://docs.immutable.com/docs/products/checkout/onramp.md)
>
> Buy crypto with fiat

> [card] [Swap](https://docs.immutable.com/docs/products/checkout/swap.md)
>
> Exchange tokens

> [card] [Bridge](https://docs.immutable.com/docs/products/checkout/bridge.md)
>
> Transfer from L1

> [card] [Primary Sales](https://docs.immutable.com/docs/products/checkout/sale.md)
>
> Sell NFTs to players

> [card] [Unity SDK](https://docs.immutable.com/docs/sdks/unity/overview.md)
>
> Unity implementation

> [card] [Unreal SDK](https://docs.immutable.com/docs/sdks/unreal/overview.md)
>
> Unreal implementation


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.