PayKitProvider — set up your global payment context

Configure PayKitProvider with your API key, theme, environment, wallet callbacks, and global PayKitOptions to control every aspect of 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.

"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>
  );
}

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.

Configuration options

apiKey · string · required

Your organization’s API key, obtained from the Developers tab of the CoinVoyage dashboard. 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.

environment · 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.

mode · 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.

theme · string

Select a predefined visual style for the payment modal. Available themes:

• auto
• web95
• retro
• soft
• midnight
• minimal
• rounded
• nouns

customTheme · 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.

debugMode · boolean · default: "false"

When true, the SDK logs debug information to the browser console. Useful during development and integration testing.

onConnect · 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)

onConnectValidation · 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.

onDisconnect · function

Callback invoked when a wallet disconnects.

options · PayKitOptions

Global options applied across all PayButton components and payment flows managed by this provider. See PayKitOptions below.

PayKitOptions

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

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

options.language · Languages

Sets the display language for the payment modal. Use a value from the exported Languages enum.

options.hideTooltips · boolean

When true, suppresses tooltip overlays throughout the modal.

options.hideQuestionMarkCTA · boolean

When true, hides the question mark help CTA inside the modal.

options.hideNoWalletCTA · boolean

When true, removes the “no wallet” call-to-action that appears when no wallet is connected.

options.hideRecentBadge · boolean

When true, hides the “Recent” badge shown next to recently used wallets.

options.walletConnectCTA · 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

options.embedGoogleFonts · boolean

When true, automatically embeds the Google Font associated with the selected built-in theme. Has no effect when using a customTheme.

options.disclaimer · ReactNode | string

Adds a disclaimer message to the bottom of the payment modal. Accepts a plain string or a React node for richer formatting.

options.bufferPolyfill · 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.

options.overlayBlur · number

Amount of background blur (in pixels) applied while the payment modal is open. Set to 0 to disable blur.

options.optimisticConfirmation · 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.

options.experimentalFeatures.cardPayments · 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.

Example with options

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