Quickstart: install CoinVoyage and accept payments

This guide walks you through installing @coin-voyage/paykit, wiring up the required providers, and rendering a PayButton that launches the CoinVoyage payment modal — all in under five minutes.

Prerequisites

A React application (Next.js, Vite, Create React App, etc.)
Node.js 18 or later
A CoinVoyage account

Steps

Install the SDK

Install @coin-voyage/paykit and its required peer dependency @tanstack/react-query.

npm i @coin-voyage/paykit @tanstack/react-query@^5.90.6

pnpm add @coin-voyage/paykit @tanstack/react-query@^5.90.6

yarn add @coin-voyage/paykit @tanstack/react-query@^5.90.6

bun add @coin-voyage/paykit @tanstack/react-query@^5.90.6

Create an API key

Open the CoinVoyage Dashboard and create an organization if you haven’t already. Then navigate to Developers and create an API key.You will receive two values:

API Key (public) — safe to use in client-side code. Expose as NEXT_PUBLIC_COIN_VOYAGE_API_KEY.
API Secret — server-side only. Never expose this in client-side code.

Keep your API secret on the server at all times. Only the public API key belongs in client-side code.

Add the providers

Wrap your app with QueryClientProvider, WalletProvider, and PayKitProvider. In a Next.js app, create a providers.tsx file:

providers.tsx

"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 }) {
  if (!process.env.NEXT_PUBLIC_COIN_VOYAGE_API_KEY) {
    throw new Error("NEXT_PUBLIC_COIN_VOYAGE_API_KEY is required");
  }

  return (
    <QueryClientProvider client={queryClient}>
      <WalletProvider>
        <PayKitProvider apiKey={process.env.NEXT_PUBLIC_COIN_VOYAGE_API_KEY}>
          {children}
        </PayKitProvider>
      </WalletProvider>
    </QueryClientProvider>
  );
}

Then import and use <Providers> in your root layout:

app/layout.tsx

import { Providers } from "./providers";

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        <Providers>{children}</Providers>
      </body>
    </html>
  );
}

Render a PayButton

Add <PayButton> anywhere in your app to launch the CoinVoyage payment modal. The example below creates a deposit button that settles 10 SUI to your specified wallet:

components/deposit-button.tsx

"use client";

import { PayButton } from "@coin-voyage/paykit";
import { ChainId } from "@coin-voyage/paykit/server";

export function DepositButton() {
  return (
    <PayButton
      intent="Deposit"
      toChain={ChainId.SUI}
      toAddress="0xYourSUIWalletAddress"
      toAmount={10}
      toToken={undefined}
      style={{ width: "100%", borderRadius: "0.375rem" }}
      onAwaitingPayment={() => console.log("Awaiting payment")}
      onConfirmingPayment={() => console.log("Payment confirming")}
      onExecutingPayment={() => console.log("Payment executing")}
      onPaymentCompleted={() => console.log("Payment completed")}
    />
  );
}

When a user clicks the button, CoinVoyage opens a modal where they can select their preferred chain and token to pay with.

Next steps

SDK reference

Explore all provider options, PayButton props, and the ApiClient.

How it works

Understand the full payment lifecycle from order creation to settlement.

Webhooks

Receive real-time notifications when payments complete or fail.

Dashboard

Monitor transactions, configure settlement, and manage your API keys.

Get started

Core concepts

Flows

Invoices

SDK

API

Webhooks

Dashboard

Guides

Resources

Quickstart: install CoinVoyage and accept payments

Prerequisites

Steps

Next steps

SDK reference

How it works

Webhooks

Dashboard

​Prerequisites

​Steps

​Next steps

SDK reference

How it works

Webhooks

Dashboard

Prerequisites

Steps

Next steps