Developer guide

Add one-tap USDC payments to your app, API, or agent with the Checkout Widget on the frontend and the BeepClient on the backend. Payments settle directly between non-custodial vaults and produce machine-verifiable receipts.

Installation

npm install @beep-it/checkout-widget @beep-it/sdk-core

Quick Start

import React from 'react';
import { CheckoutWidget } from '@beep-it/checkout-widget';

function App() {
  return (
    <CheckoutWidget
      publishableKey="your-publishable-key"
      primaryColor="#007bff"
      labels={{
        scanQr: 'Scan QR Code to Pay',
        paymentLabel: 'My Store Checkout',
      }}
      assets={[
        {
          assetId: 'product-uuid-123',
          quantity: 2,
          name: 'Premium Coffee',
          description: 'Fresh roasted arabica beans',
        },
      ]}
      serverUrl="https://your-beep-server.com" // optional
    />
  );
}

Asset Types

The widget supports two types of assets:

1. Existing Product References (BeepPurchaseAsset)

Reference pre-created products by their ID:

const assets = [
  {
    assetId: 'product-uuid-123',
    quantity: 1,
    name: 'Coffee', // optional override
    description: 'Premium blend', // optional override
  },
];

2. On-the-Fly Product Creation (CreateProductPayload)

Create products dynamically during checkout. These items are created as products in your merchant account on the server (persisted for audit and reuse). They may be hidden from public listings by default.

const assets = [
  {
    name: 'Custom Item',
    price: '25.50',
    quantity: 2,
    description: 'Custom product description',
  },
];

Props

Prop	Type	Required	Description
publishableKey	string	✅	BEEP publishable key for browser-safe authentication
primaryColor	string	❌	Primary color for styling (hex format, e.g., "#007bff")
labels	object	✅	Customizable text labels
labels.scanQr	string	✅	Text shown above QR code
labels.paymentLabel	string	❌	Label displayed in Solana Pay wallets (default: "Beep Checkout")
assets	(BeepPurchaseAsset | CreateProductPayload)[]	✅	Items to purchase
serverUrl	string	❌	Custom BEEP server URL (defaults to production)

Asset Props

BeepPurchaseAsset

Prop	Type	Required	Description
assetId	string	✅	UUID of existing product
quantity	number	✅	Number of items
name	string	❌	Override product name
description	string	❌	Override product description

CreateProductPayload

Prop	Type	Required	Description
name	string	✅	Product display name
price	string	✅	Price in decimal format (e.g., "25.50")
quantity	number	❌	Number of items (default: 1)
description	string	❌	Product description

Features

Core Functionality

• Sui Network Integration: Generates native Sui USDC payment requests

• Real-time Status Polling: Verifies payment confirmation directly from the Sui RPC

• Flexible Asset Support: Mix existing products with on-the-fly product creation (persisted)

• Payment Label Support: Custom labels appear in wallet interfaces

• Wallet Address Display: Shows copyable recipient address for desktop users

User Experience

• Loading States: Smooth loading indicators during setup and polling

• Error Handling: Comprehensive error boundaries and user-friendly error messages

• Success Animation: Clear payment confirmation state

• Responsive Design: Works on desktop and mobile devices

• Customizable Theming: Primary color theming throughout the widget

Developer Experience

• TypeScript Support: Full type safety with comprehensive interfaces

• Zero CSS Dependencies: Inline styles prevent conflicts with host applications

• Error Boundaries: Isolated error handling prevents widget crashes from affecting host app

• Comprehensive Logging: Detailed console logging for debugging

Usage Examples

Simple Single Product

<CheckoutWidget
  publishableKey="your-publishable-key"
  primaryColor="#10b981"
  labels={{ scanQr: 'Pay with Crypto' }}
  assets={[
    {
      assetId: 'coffee-product-uuid',
      quantity: 1,
    },
  ]}
/>

Multiple Products with Custom Labels

<CheckoutWidget
  publishableKey="your-publishable-key"
  primaryColor="#3b82f6"
  labels={{
    scanQr: 'Scan to complete your order',
    paymentLabel: 'Coffee Shop - Downtown',
  }}
  assets={[
    {
      assetId: 'coffee-uuid',
      quantity: 2,
      name: 'Espresso',
    },
    {
      assetId: 'pastry-uuid',
      quantity: 1,
      name: 'Croissant',
    },
  ]}
/>

Dynamic Product Creation

<CheckoutWidget
  publishableKey="your-publishable-key"
  primaryColor="#ef4444"
  labels={{
    scanQr: 'Pay for custom service',
    paymentLabel: 'Consulting Services',
  }}
  assets={[
    {
      name: '1-Hour Consultation',
      price: '150.00',
      quantity: 1,
      description: 'Professional consulting session',
    },
  ]}
/>

Mixed Asset Types

<CheckoutWidget
  apiKey="your-api-key"
  primaryColor="#8b5cf6"
  labels={{ scanQr: 'Complete your purchase' }}
  assets={[
    // Existing product
    {
      assetId: 'existing-product-uuid',
      quantity: 1,
    },
    // Dynamic product
    {
      name: 'Rush Delivery',
      price: '15.00',
      quantity: 1,
    },
  ]}
/>

Payment Flow

1. Initialization Phase: The widget prepares a signed USDC-on-Sui payment request.

2. Display Phase: Shows QR code and total amount to user

3. Polling Phase: Automatically checks transaction finality via Sui RPC

4. Completion: Displays success state when payment is confirmed on-chain

Error Handling

The widget includes comprehensive error handling:

• Configuration Errors: Invalid API keys, missing assets

• Network Errors: API connection issues, timeouts

• Payment Errors: Failed transactions, expired payments

• Component Errors: Isolated error boundaries prevent crashes

Sui Payment Integration

The widget generates Sui-native Payment URLs with:

• Recipient: Developer's Sui wallet address

• Amount: Total calculated from all assets in USDC

• SPL Token: Token address for payment

• Reference: Unique tracking identifier

• Label: Custom payment label for wallet display

• Message: Descriptive payment message

Development

# Install dependencies
pnpm install

# Run tests
pnpm test

# Build the package
pnpm build

# Run tests in watch mode
pnpm test:watch

# Run development showcase
pnpm dev

Environment Variables

The widget respects these environment variables:

• REACT_APP_BEEP_SERVER_URL: Default server URL if not provided via props

TypeScript Support

Full TypeScript support with exported interfaces:

import { CheckoutWidget, MerchantWidgetProps, MerchantWidgetState } from '@beep-it/checkout-widget';

import { BeepPurchaseAsset, CreateProductPayload } from '@beep-it/sdk-core';