> ## 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, environment, visual mode, 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 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 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"` — connects to the acceptance API.
  * `"local"` — connects to a locally running API at `http://localhost:8000/v3`.
</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="customTheme" type="object">
  Override specific modal styles to match your branding. Accepts a `CustomTheme` object keyed by supported CSS custom properties.
</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, wallet-connect presentation, polyfills, confirmation behavior, 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"
  disclaimer?: ReactNode | string
  bufferPolyfill?: boolean
  overlayBlur?: number
  optimisticConfirmation?: boolean
  experimentalFeatures?: {
    cardPayments?: boolean
  }
}
```

<ParamField path="options.language" type="Languages" default="en-US">
  Sets the display language for the payment modal.
</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="link">
  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.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 orders, where confirmation requires destination finality.
</ParamField>

<ParamField path="options.experimentalFeatures.cardPayments" type="boolean" default="false">
  Opt in to the gated Stripe Link on-ramp option inside the modal. When your organization is approved, PayKit can show USD and EUR Card Payments as an additional payment path alongside **Pay to Address** and **Pay with Wallet**. CoinVoyage coordinates Link authentication, customer status checks, payment method collection, on-ramp session creation, and checkout. Contact the CoinVoyage team before enabling this option in production.
</ParamField>

## Example with options

```tsx theme={null}
<PayKitProvider
  apiKey={process.env.NEXT_PUBLIC_COIN_VOYAGE_API_KEY!}
  environment="production"
  mode="dark"
  customTheme={{
    "--ck-primary-button-background": "#d6296f",
    "--ck-primary-button-color": "#ffffff",
  }}
  options={{
    language: "en-US",
    hideNoWalletCTA: true,
    walletConnectCTA: "modal",
    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>
```