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 end 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

Parameter	Type	Required	Description
clientProps (ClientProps)			Object containing client-specific configuration parameters.
`publishableKey`	`string`	✅	Your Bolt publishable key. You can find this value in the Merchant Dashboard.
`marketplaceSubMerchantID`	`string`	✅	The identifier of the seller in your marketplace.
`isTestEnv`	`boolean`	❌	`true` for sandbox; `false` for production (default `false`).
eventHandlers			Object 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 End Seller Information and Onboarding Status

API Reference

CheckoutHelpers.getEndSellerInfo(params): Promise<EndSellerInfoResponse>

Description
Fetches end seller information and current onboarding status.

Parameters

Parameter	Type	Required	Description
GetEndSellerInfoParams			Parameters used to retrieve end seller information.
`publishableKey`	`string`	✅	Your Bolt publishable key. You can find this value in the Merchant Dashboard.
`marketplaceSubMerchantID`	`string`	✅	The identifier of the seller in your marketplace.
`isTestEnv`	`boolean`	❌	`true` for sandbox; `false` for production (default `false`).
`skipCache`	`boolean`	❌	`true` to bypass cache; `false` to use cache (default `false`).

Returns

Name	Type	Description
EndSellerInfoResponse		The response object containing end seller information.
`publishableKey`	`string`	The publishable key of the seller, to be used to initiate checkout.
`onboardingStatus`	`string`	The onboarding status: `completed`, `unconfigured`, `under_review`.

Example

// Fetch end seller information
const getSellerInfo = async () => {
  try {
    const sellerInfo = await CheckoutHelpers.getEndSellerInfo({
      publishableKey: 'your-publishable-key',
      marketplaceSubMerchantID: 'your-sub-merchant-id',
      isTestEnv: true, // Set to false for production
      skipCache: false, // Set to true to bypass cache
    })

    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:

End seller information is cached using the key: ${publishableKey}_${marketplaceSubMerchantID}
Use skipCache: true to bypass the cache when needed
Cache is stored in memory and persists for the session

Error Handling

The SDK provides comprehensive error handling:

try {
  await Onboarding.start()
} catch (error) {
  console.error('Onboarding error:', error)
}

try {
  const sellerInfo = await CheckoutHelpers.getEndSellerInfo(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+