Install Bolt Connect SDK

For the complete integration, start with the Marketplace Connect quickstart. Use this page to look up SDK methods and options.

Install the SDK using one of the following methods:

npm install @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.

The SDK ships TypeScript definitions, so types resolve automatically in a TypeScript project. The examples below are plain JavaScript and run unchanged in both.

Step 1: Import the SDK

JavaScript

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

Step 2: Configure Onboarding

API Reference

Signature

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 platform.
`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

JavaScript

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

Signature

Onboarding.start(): Promise<void>

Description
Starts the onboarding form as a full-page iframe within your site.

Example

JavaScript

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

Signature

CheckoutHelpers.getSellerInfo(params): Promise<SellerInfoResponse>

Description
Fetches seller information and current onboarding status.

Parameters

Parameter	Type	Required	Description
GetSellerInfoParams			Parameters used to retrieve 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 platform.
`isTestEnv`	`boolean`	❌	`true` for sandbox; `false` for production (default `false`).

Returns

Name	Type	Description
SellerInfoResponse		The response object containing 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

JavaScript

// 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:

JavaScript

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+

Install Bolt Connect SDK

On this page