PayButton — ready-made crypto payment UI component

PayButton is a ready-made React component that renders a themed button and manages the full payment modal experience. When a user clicks it, a modal opens that lets them select a payment method, connect their wallet, and sign the transaction. The button handles quote fetching, transaction submission, and status polling internally — your application only needs to supply the payment parameters and react to the lifecycle callbacks.

Full example

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

<PayButton
  intent="Deposit"
  toAddress="0xYourWalletToDepositInto"
  toAmount={100}
  toChain={ChainId.ETH}
  toToken="0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48" // USDC

  mode="auto"
  style={{
    backgroundColor: "#CF276B",
    color: "white",
  }}

  onOpen={() => {
    console.log("Modal Opened");
  }}
  onClose={() => {
    console.log("Modal Closed");
  }}
  closeOnSuccess={true}
  paymentMethod={PaymentMethod.WALLET}

  onPaymentCreationError={(event) => {
    console.log(event.errorMessage);
  }}
  onAwaitingPayment={(event) => {
    console.log("Awaiting payment", event);
  }}
  onConfirmingPayment={(event) => {
    console.log("Payment confirming", event);
  }}
  onExecutingPayment={(event) => {
    console.log("Payment executing", event);
  }}
  onPaymentCompleted={() => {
    console.log("Payment Complete");
  }}
  onPaymentBounced={() => {
    console.error("Payment Bounced");
  }}
/>

Required parameters: You must provide either orderId or all three of toAddress, toChain, and toAmount. Mixing both approaches in the same button is not supported.

Use orderId for server-generated SALE orders created via ApiClient.createSaleOrder.
Use toAddress + toChain + toAmount for client-side deposit flows.

Props reference

Payment target

string

An order ID previously created on the server via the ApiClient. Use this for SALE orders or any flow where the server controls order creation. When orderId is set, omit toAddress, toChain, and toAmount.

ChainId

The destination chain ID to deposit to. Required when not using orderId.

string

The contract address of the destination token (ERC-20, SPL, or equivalent). Omit this prop (or pass undefined) to receive the chain’s native token (ETH, SOL, SUI, etc.).

number

The amount of the destination token the recipient should receive, in human-readable format (e.g., 100 for 100 USDC). Required when not using orderId.

string

The recipient address on the toChain. Must be a valid address for the destination chain. Required when not using orderId.

OrderMetadata

Metadata to attach to the order. Supports structured item details (name, description, image, quantity, price) and custom key-value fields.

string

The verb shown on the button label, such as "Pay", "Deposit", or "Purchase". Defaults to "Pay" when not set.

Appearance

React.CSSProperties

Inline style overrides applied to the button element. Use this for quick branding adjustments like background color and text color.

string

default:"auto"

Color scheme for the payment modal. Accepted values: "light", "dark", or "auto". Overrides the mode set on PayKitProvider for this button only.

object

Custom theme object for this button’s modal. Takes precedence over any customTheme set on PayKitProvider.

boolean

default:"false"

When true, the button is rendered in a disabled state and the modal cannot be opened.

boolean

default:"false"

When true, the payment modal opens automatically on mount without requiring a click.

PaymentMethod

Opens the modal directly on a specific payment path instead of first showing method selection. Accepted values are PaymentMethod.WALLET, PaymentMethod.DEPOSIT_ADDRESS, and PaymentMethod.CARD.

boolean

default:"false"

When true, the payment modal closes automatically after the payment completes successfully.

boolean

default:"false"

When true, PayKit resets the payment state after a successful payment once the modal closes.

function

Callback invoked when the payment modal opens.

function

Callback invoked when the payment modal closes, whether by the user or programmatically.

Payment lifecycle

function

Callback invoked when the order cannot be created due to invalid parameters. Receives an event object with an errorMessage string describing the failure.

function

Callback invoked when payment details are available and the order is awaiting payment.

function

Callback invoked when the user’s payment transaction is detected on-chain and awaiting confirmation.

function

Callback invoked when the payment is confirmed and CoinVoyage is executing the destination transfer or contract call.

function

Callback invoked when the destination transfer or contract call completes successfully. This is the appropriate place to trigger fulfillment logic or show a success message.

function

Callback invoked when the destination call reverts and the user’s funds are automatically refunded. Use this to notify the user of the failure.

Open a specific payment method

Use paymentMethod when your UI already knows which payment path the user selected.

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

<PayButton
  orderId={orderId}
  paymentMethod={PaymentMethod.CARD}
  closeOnSuccess
/>

PaymentMethod.CARD supports eligible USD- and EUR-denominated orders. It still requires options.experimentalFeatures.cardPayments and organization approval. If card payments are not available for the order, PayKit falls back to method selection instead of opening the card flow.

PayButton.Custom

PayButton.Custom is for situations where you need complete control over the button’s appearance — for example, when integrating with an existing design system or triggering the modal from multiple UI elements. It accepts a render prop as children that receives show and hide functions to control modal visibility. PayButton.Custom accepts the same payment props, modal options, and lifecycle callbacks as PayButton but replaces the styling props (style, mode, customTheme, disabled) with the children render prop.

Usage

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

<PayButton.Custom
  orderId={orderId}
  onAwaitingPayment={(event) => {
    console.log("Awaiting payment", event);
  }}
  onConfirmingPayment={(event) => {
    console.log("Payment confirming", event);
  }}
  onExecutingPayment={(event) => {
    console.log("Payment executing", event);
  }}
  onPaymentCompleted={(event) => {
    console.log("Payment completed", event);
  }}
>
  {({ show, hide }) => (
    <button
      onClick={show}
      className="w-full rounded-md border border-transparent bg-indigo-600 px-4 py-3 text-base font-medium text-white shadow-sm hover:bg-indigo-700 focus:outline-none focus:ring-2 focus:ring-indigo-500 focus:ring-offset-2 focus:ring-offset-gray-50"
    >
      Pay With Crypto
    </button>
  )}
</PayButton.Custom>

Render prop

The children function receives an object with two functions:

function

Opens the payment modal. Call this from your custom button’s onClick handler or any other event.

function

Closes the payment modal programmatically. Useful when you need to dismiss the modal in response to an external event.

Additional PayButton.Custom props

function

required

A render function that receives { show, hide }. Must return valid React elements.

boolean

default:"false"

When true, the payment modal opens automatically on mount.

When to use PayButton.Custom:

You need full styling control beyond what inline style provides.
You are integrating into an existing design system with strict component conventions.
You want to trigger the payment modal from multiple distinct UI elements on the same page.
You need to open or close the modal in response to programmatic events, not only user clicks.

Get started

Core concepts

Flows

Invoices

SDK

API

Webhooks

Dashboard

Guides

Resources

PayButton — ready-made crypto payment UI component

Full example

Props reference

Payment target

Appearance

Payment lifecycle

Open a specific payment method

PayButton.Custom

Usage

Render prop

Additional PayButton.Custom props

​Full example

​Props reference

​Payment target

​Appearance

​Modal lifecycle

​Payment lifecycle

​Open a specific payment method

​PayButton.Custom

​Usage

​Render prop

​Additional PayButton.Custom props

Full example

Props reference

Payment target

Appearance

Modal lifecycle

Payment lifecycle

Open a specific payment method

PayButton.Custom

Usage

Render prop

Additional PayButton.Custom props