Skip to main content

Documentation Index

Fetch the complete documentation index at: https://coinvoyage-3c99945b.mintlify.app/llms.txt

Use this file to discover all available pages before exploring further.

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>