PayKitProvider — set up your global payment context

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.

"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 order lifecycle events to the browser console. Remove it before going to production.

Configuration options

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.

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.

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.

object

Override specific modal styles to match your branding. Accepts a CustomTheme object keyed by supported CSS custom properties.

boolean

default:"false"

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

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)

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.

function

Callback invoked when a wallet disconnects.

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, wallet-connect presentation, polyfills, confirmation behavior, and experimental features. Every field is optional.

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

Languages

default:"en-US"

Sets the display language for the payment modal.

boolean

When true, suppresses tooltip overlays throughout the modal.

boolean

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

boolean

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

boolean

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

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

ReactNode | string

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

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.

number

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

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.

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.

Example with options

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

Get started

Core concepts

Flows

Invoices

SDK

API

Webhooks

Dashboard

Guides

Resources

PayKitProvider — set up your global payment context

Setup

Configuration options

PayKitOptions

Example with options

​Setup

​Configuration options

​PayKitOptions

​Example with options

Setup

Configuration options

PayKitOptions

Example with options