SETUP GUIDE

CoinVoyage for React

Add PayKit and SwapKit to React and Next.js apps with the CoinVoyage SDK.

Requirements

Your app needs React 18 or 19; Next.js is supported. A CoinVoyage public API key connects the widgets to your account.

Get your CoinVoyage API key

Follow the API key setup guide to create your public API key.

PayKit supports crypto and eligible card payments. SwapKit is for token swaps.

Install the package

Add PayKit and the wallet libraries it builds on to your app.

Terminal

npm install @coin-voyage/paykit @bigmi/react @mysten/dapp-kit-react @solana/wallet-adapter-react @tanstack/react-query styled-components viem wagmi

Add a pay button

Wrap PayButton in the wallet and PayKit providers. Replace the API key and recipient address.

Checkout.tsx

"use client"

import { PayButton, PayKitProvider, WalletProvider } from "@coin-voyage/paykit"

export function Checkout() {
  return (
    <WalletProvider>
      <PayKitProvider apiKey="YOUR_PUBLIC_API_KEY">
        <PayButton
          intent="Pay now"
          toChain={1}
          toAmount={0.01}
          toAddress="YOUR_RECIPIENT_ADDRESS"
          onPaymentCompleted={(event) => console.log("Payment completed", event)}
        />
      </PayKitProvider>
    </WalletProvider>
  )
}

This is a deposit. It does not automatically verify a product purchase. In Next.js, keep the providers in a client component.

Have your own server? Start selling products now

Your server can create a new purchase order (called a SALE order in the API) for each checkout using your production API key and API secret. Validate the product, price, and recipient on your server, then return the order ID to your app and pass it to the pay button:

Copy and paste

<PayButton intent="Pay now" orderId={orderId} />

Create a new order for every purchase; do not reuse a single order for multiple buyers. Keep the API secret on your server and verify payment completion there before fulfillment.

Add a swap widget

Optional. SwapKit is a separate package that uses the same wallet libraries.

Terminal

npm install @coin-voyage/swapkit

SwapWidget.tsx

"use client"

import { Swap, SwapKitProvider, WalletProvider } from "@coin-voyage/swapkit"

export function SwapWidget() {
  return (
    <WalletProvider>
      <SwapKitProvider apiKey="YOUR_PUBLIC_API_KEY" mode="dark">
        <Swap />
      </SwapKitProvider>
    </WalletProvider>
  )
}

Match your site’s appearance

Choose a color mode on the provider. PayKit takes a customTheme object of theme variables and SwapKit takes a theme object. Leave them out to keep the defaults.

Copy and paste

<PayKitProvider
  apiKey="YOUR_PUBLIC_API_KEY"
  mode="dark"
  customTheme={{ "--ck-primary-button-background": "#d6296f", "--ck-primary-button-color": "#ffffff" }}
>

See the PayKit and SwapKit styling references. Custom colors apply in both light and dark modes, so choose matching background and text colors.

Test your setup

Open the page and test the wallets your customers use, including mobile. If you use WalletConnect, pass its project ID through the config prop of WalletProvider and add your site's origin to the project.

Before going live

Completion events in the browser are display notifications, not proof of payment. Verify payments on your server before fulfilling an order, and keep your API secret there.

Payment options

Open checkout on Pay with card

Set paymentMethod={PaymentMethod.CARD} on the pay button. Other methods are WALLET and DEPOSIT_ADDRESS. Omit the property to keep the normal starting screen.

Copy and paste

import { PayButton, PayKitProvider } from "@coin-voyage/paykit"
import { PaymentMethod } from "@coin-voyage/paykit/types"

// Place inside your existing WalletProvider.
<PayKitProvider
  apiKey="YOUR_PUBLIC_API_KEY"
  options={{ experimentalFeatures: { cardPayments: true } }}
>
  <PayButton
    orderId={orderId}
    paymentMethod={PaymentMethod.CARD}
    closeOnSuccess={true}
    resetOnSuccess={false}
  />
</PayKitProvider>

Card payments must be enabled and available for your account and order. If unavailable, PayKit shows payment method selection. Choosing a method selects the first screen when the modal opens. To open the modal automatically, also set defaultOpen={true}.

closeOnSuccess closes the modal after payment; resetOnSuccess clears the widget's payment state. Omit either property to keep SDK defaults. A new purchase still needs a fresh server-created order; resetting a widget does not create one.

Configure PayKit options and debug mode

Pass options and debugMode to PayKitProvider. Modal options such as paymentMethod stay on PayButton.

Copy and paste

<PayKitProvider
  apiKey="YOUR_PUBLIC_API_KEY"
  options={{ language: "de-DE", hideTooltips: true, overlayBlur: 4, experimentalFeatures: { cardPayments: true } }}
  debugMode={false}
>
  {/* Your PayButton */}
</PayKitProvider>

Option	Value
`language`	A supported locale, such as en-US, de-DE or fr-FR.
`hideTooltips, hideQuestionMarkCTA, hideRecentBadge`	true or false to hide each UI element.
`walletConnectCTA`	"link", "modal" or "both".
`disclaimer`	Plain text, or null to clear it. HTML is displayed as text.
`overlayBlur`	A finite number of zero or greater.
`optimisticConfirmation`	true or false. Browser completion still requires server verification.
`bufferPolyfill`	true or false. Leave unset unless you need to control the Buffer polyfill.
`experimentalFeatures.cardPayments`	true or false. An explicit card-payments setting takes precedence.

Omit options to keep SDK defaults. React also accepts a React element as the disclaimer. hideNoWalletCTA is accepted by PayKit but currently has no visible effect. Enabling cards requires options.experimentalFeatures.cardPayments, as in the card example above.