​
Install Bolt Connect SDK

Before you begin, install the SDK using one of the following methods:

​
Using npm

npm install @boltpay/bolt-connect-sdk

​
Using yarn

yarn add @boltpay/bolt-connect-sdk

​
Using pnpm

pnpm add @boltpay/bolt-connect-sdk

​
Using bun

bun add @boltpay/bolt-connect-sdk

​
Direct download from npm registry

Alternatively, you can download the package directly from the npm registry: Package info: https://registry.npmjs.org/@boltpay/bolt-connect-sdk

​
Quick Start

Follow these steps to onboard sellers using the Bolt Connect SDK.

​
Step 1: Import the SDK

import { Onboarding, CheckoutHelpers } from '@boltpay/bolt-connect-sdk'

​
Step 2: Configure Onboarding

​
API Reference

Onboarding.configure(clientProps, eventHandlers): void
Description
Set up the onboarding configuration with your credentials and event callbacks. Parameters
ParameterTypeRequiredDescription
clientProps (ClientProps)Object containing client-specific configuration parameters.
publishableKeystring✅Your Bolt publishable key. You can find this value in the Merchant Dashboard.
marketplaceSubMerchantIDstring✅The identifier of the seller in your platform.
isTestEnvboolean❌true for sandbox; false for production (default false).
eventHandlersObject containing optional callback functions.
onSuccess() => void❌Triggered when onboarding completes successfully.
onFailure(payload: { message: string }) => void❌Triggered when onboarding fails.
onNotify(payload: { message: string }) => void❌Triggered for status updates during onboarding.
Example 
Onboarding.configure(
  {
    publishableKey: 'your-publishable-key',
    marketplaceSubMerchantID: 'your-sub-merchant-id',
    isTestEnv: true, // Set to false for production
  },
  {
    onSuccess: () => {
      console.log('Onboarding completed successfully!')
      // Handle successful onboarding (e.g., redirect, show success message)
    },
    onFailure: payload => {
      console.error('Onboarding failed:', payload.message)
      // Handle onboarding failure (e.g., show error message)
    },
    onNotify: payload => {
      console.log('Onboarding notification:', payload.message)
      // Handle notifications during onboarding process
    },
  }
)

​
Step 3: Start Onboarding

​
API Reference

Onboarding.start(): Promise<void>
Description
Starts the onboarding form as a full-age iframe within your site. Example 
// Start the onboarding process
const startOnboarding = async () => {
  try {
    await Onboarding.start()
    // The iframe will be displayed full-screen
  } catch (error) {
    console.error('Failed to start onboarding:', error)
  }
}

// Attach to a button click
document
  .getElementById('onboarding-button')
  ?.addEventListener('click', startOnboarding)

​
Step 4: Get Seller Information and Onboarding Status

​
API Reference

CheckoutHelpers.getSellerInfo(params): Promise<SellerInfoResponse>
Description
Fetches seller information and current onboarding status. Parameters
ParameterTypeRequiredDescription
GetSellerInfoParamsParameters used to retrieve seller information.
publishableKeystring✅Your Bolt publishable key. You can find this value in the Merchant Dashboard.
marketplaceSubMerchantIDstring✅The identifier of the seller in your platform.
isTestEnvboolean❌true for sandbox; false for production (default false).
Returns
NameTypeDescription
SellerInfoResponseThe response object containing seller information.
publishableKeystringThe publishable key of the seller, to be used to initiate checkout.
onboardingStatusstringThe onboarding status: completed, unconfigured, under_review.
Example 
// Fetch seller information
const getSellerInfo = async () => {
  try {
    const sellerInfo = await CheckoutHelpers.getSellerInfo({
      publishableKey: 'your-publishable-key',
      marketplaceSubMerchantID: 'your-sub-merchant-id',
      isTestEnv: true // Set to false for production
    })

    console.log('Seller info:', sellerInfo)
    // sellerInfo.onboardingStatus: 'completed' | 'unconfigured' | 'under_review'
  } catch (error) {
    console.error('Failed to fetch seller info:', error)
  }
}

​
Caching

The SDK includes intelligent caching to improve performance:
  • Seller information is cached for improving performance.

​
Error Handling

The SDK provides comprehensive error handling: 
try {
  await Onboarding.start()
} catch (error) {
  console.error('Onboarding error:', error)
}

try {
  const sellerInfo = await CheckoutHelpers.getSellerInfo(params)
} catch (error) {
  console.error('API error:', error)
}

​
Browser Support

The SDK supports all modern browsers with ES6+ support:
  • Chrome 60+
  • Firefox 55+
  • Safari 12+
  • Edge 79+