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

# PayKitProvider — set up your global payment context

> Configure PayKitProvider with your API key, theme, environment, wallet callbacks, and global PayKitOptions to control the payment modal.

`PayKitProvider` is the top-level React context provider for the CoinVoyage PayKit SDK. Wrapping your application with it enables the `PayButton` component and the `usePayStatus` hook anywhere in the component tree. It connects to the CoinVoyage API using your `apiKey`, tracks pay order state, and exposes global configuration that applies to every payment flow on the page.

## Setup

Place `PayKitProvider` inside `WalletProvider` and `QueryClientProvider`. This nesting order is required.

```tsx theme={null}
"use client";

import { PayKitProvider, WalletProvider } from "@coin-voyage/paykit";
import { QueryClient, QueryClientProvider } from "@tanstack/react-query";

const queryClient = new QueryClient();

export function Providers({ children }: { children: React.ReactNode }) {
  return (
    <QueryClientProvider client={queryClient}>
      <WalletProvider>
        <PayKitProvider
          apiKey={process.env.NEXT_PUBLIC_COIN_VOYAGE_API_KEY!}
          debugMode={true}
          mode="light"
          onConnect={({ address, chainId, connectorId, type }) => {
            console.log(
              `Connected to ${chainId} with ${connectorId} (${type}) at ${address}`
            );
          }}
          environment="production"
        >
          {children}
        </PayKitProvider>
      </WalletProvider>
    </QueryClientProvider>
  );
}
```

<Tip>
  Set `debugMode={true}` while you are integrating to log detailed information about pay order lifecycle events to the browser console. Remove it before going to production.
</Tip>

## Configuration options

<ParamField path="apiKey" type="string" required>
  Your organization's API key, obtained from the **Developers** tab of the [CoinVoyage dashboard](https://dashboard.coinvoyage.io/developers). This key is safe to expose in client-side code — it identifies your organization but does not grant write access without a corresponding API secret.
</ParamField>

<ParamField path="environment" type="string" default="production">
  Environment to connect to. Accepted values:

  * `"production"` — connects to live chains and production APIs.
  * `"development"` — exposes additional testnet chains for integration testing.
</ParamField>

<ParamField path="mode" type="string" default="auto">
  Color scheme for the payment modal. Accepted values: `"light"`, `"dark"`, or `"auto"`. When set to `"auto"`, the modal follows the user's OS preference.
</ParamField>

<ParamField path="theme" type="string">
  Select a predefined visual style for the payment modal. Available themes:

  * `auto`
  * `web95`
  * `retro`
  * `soft`
  * `midnight`
  * `minimal`
  * `rounded`
  * `nouns`
</ParamField>

<ParamField path="customTheme" type="object">
  Override specific modal styles to match your branding. Accepts a theme object with CSS-style values. Takes precedence over the `theme` preset. Note that `embedGoogleFonts` in `options` does not apply to custom themes.
</ParamField>

<ParamField path="debugMode" type="boolean" default="false">
  When `true`, the SDK logs debug information to the browser console. Useful during development and integration testing.
</ParamField>

<ParamField path="onConnect" type="function">
  Callback invoked when a wallet connects. Receives an object with:

  * `address` (string) — the connected wallet address
  * `chainId` (number) — the chain the wallet connected to
  * `connectorId` (string) — identifier for the connector used
  * `type` (string) — wallet type (e.g., EVM, Solana)
</ParamField>

<ParamField path="onConnectValidation" type="function">
  Custom validation function run when a wallet connects. Use this to enforce additional requirements — for example, to block connections from addresses on a deny list — before the connection is accepted by the SDK.
</ParamField>

<ParamField path="onDisconnect" type="function">
  Callback invoked when a wallet disconnects.
</ParamField>

<ParamField path="options" type="PayKitOptions">
  Global options applied across all `PayButton` components and payment flows managed by this provider. See [PayKitOptions](#paykitoptions) below.
</ParamField>

## PayKitOptions

The `options` prop accepts a `PayKitOptions` object that controls language, UI visibility, fonts, and experimental features. Every field is optional.

```typescript theme={null}
type PayKitOptions = {
  language?: Languages
  hideTooltips?: boolean
  hideQuestionMarkCTA?: boolean
  hideNoWalletCTA?: boolean
  hideRecentBadge?: boolean
  walletConnectCTA?: "link" | "modal" | "both"
  embedGoogleFonts?: boolean
  disclaimer?: ReactNode | string
  bufferPolyfill?: boolean
  overlayBlur?: number
  optimisticConfirmation?: boolean
  experimentalFeatures?: {
    cardPayments?: boolean
  }
}
```

<ParamField path="options.language" type="Languages">
  Sets the display language for the payment modal. Use a value from the exported `Languages` enum.
</ParamField>

<ParamField path="options.hideTooltips" type="boolean">
  When `true`, suppresses tooltip overlays throughout the modal.
</ParamField>

<ParamField path="options.hideQuestionMarkCTA" type="boolean">
  When `true`, hides the question mark help CTA inside the modal.
</ParamField>

<ParamField path="options.hideNoWalletCTA" type="boolean">
  When `true`, removes the "no wallet" call-to-action that appears when no wallet is connected.
</ParamField>

<ParamField path="options.hideRecentBadge" type="boolean">
  When `true`, hides the "Recent" badge shown next to recently used wallets.
</ParamField>

<ParamField path="options.walletConnectCTA" type="string" default="both">
  Controls how WalletConnect is presented. Accepted values:

  * `"link"` — show only a deep link
  * `"modal"` — show only the QR code modal
  * `"both"` — show both options
</ParamField>

<ParamField path="options.embedGoogleFonts" type="boolean">
  When `true`, automatically embeds the Google Font associated with the selected built-in `theme`. Has no effect when using a `customTheme`.
</ParamField>

<ParamField path="options.disclaimer" type="ReactNode | string">
  Adds a disclaimer message to the bottom of the payment modal. Accepts a plain string or a React node for richer formatting.
</ParamField>

<ParamField path="options.bufferPolyfill" type="boolean" default="true">
  Enables the Node.js `Buffer` polyfill for bundlers that do not provide Node polyfills by default (common in Vite and other non-Next.js setups). Defaults to `true`.
</ParamField>

<ParamField path="options.overlayBlur" type="number">
  Amount of background blur (in pixels) applied while the payment modal is open. Set to `0` to disable blur.
</ParamField>

<ParamField path="options.optimisticConfirmation" type="boolean" default="true">
  When `true`, the order is considered confirmed as soon as the user's transaction validates on-chain, before the destination transfer completes. This is not permitted for deposit pay orders, where confirmation requires destination finality.
</ParamField>

<ParamField path="options.experimentalFeatures.cardPayments" type="boolean" default="false">
  Opt in to card payment support inside the modal. This feature is disabled by default while CoinVoyage gathers feedback. Your organization must also be approved before card payments are available.
</ParamField>

## Example with options

```tsx theme={null}
<PayKitProvider
  apiKey={process.env.NEXT_PUBLIC_COIN_VOYAGE_API_KEY!}
  environment="production"
  mode="dark"
  theme="midnight"
  options={{
    language: "en",
    hideNoWalletCTA: true,
    walletConnectCTA: "modal",
    embedGoogleFonts: true,
    overlayBlur: 4,
    optimisticConfirmation: true,
    disclaimer: "Payments are processed by CoinVoyage. All sales are final.",
    experimentalFeatures: {
      cardPayments: true,
    },
  }}
  onConnect={({ address, chainId }) => {
    console.log(`Wallet ${address} connected on chain ${chainId}`);
  }}
  onDisconnect={() => {
    console.log("Wallet disconnected");
  }}
>
  {children}
</PayKitProvider>
```