Bolt Connect SDK

The Bolt Connect SDK enables marketplaces to seamlessly onboard their sellers and integrate with Bolt Connect for seamless payment processing. This SDK provides two main functionalities:

1. Seller Onboarding: Streamlined iframe-based onboarding process for marketplace sellers
2. Seller Information Retrieval: API helpers to fetch onboarding status and merchant information for Bolt Connect integration

Features

• 🚀 Seamless Onboarding: Full-screen iframe integration for seller onboarding
• 🔒 Secure: Secure communication between SDK and Bolt's backend
• 💾 Caching: Intelligent caching for API responses to improve performance
• 🎯 TypeScript Support: Full TypeScript definitions included
• 🔧 Configurable: Flexible configuration for both production and sandbox environments

Installation

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

You can also download the package directly from the npm registry:

• Package info: https://registry.npmjs.org/@boltpay/bolt-connect-sdk

Quick Start

1. Import the SDK

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

2. Configure Onboarding

// Configure the onboarding with your credentials
Onboarding.configure(
  {
    publishableKey: 'your-publishable-key',
    marketplaceSubMerchantID: 'unique-seller-identifier-in-your-platform', // unique identifier for the seller in your platform
    isTestEnv: true, // (Optional) Set to true for sandbox
  },
  {
    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)
    },
    // optional
    onNotify: payload => {
      console.log('Onboarding notification:', payload.message)
      // Handle notifications during onboarding process
    },
  }
)

3. Start Onboarding

// Start the onboarding process
const startOnboarding = async () => {
  try {
    // you can start displaying loading animation of your own
    await Onboarding.start()
    // The iframe will be displayed full-screen
  } catch (error) {
    console.error('Failed to start onboarding:', error)
  } finally {
    // you can stop displaying loading animation
  }
}

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

4. Get Seller Information

// Fetch seller information
const getSellerInfo = async () => {
  try {
    const sellerInfo = await CheckoutHelpers.getSellerInfo({
      publishableKey: 'your-publishable-key',
      marketplaceSubMerchantID: 'unique-seller-identifier-in-your-platform',
      isTestEnv: true, // (Optional) Set to true for sandbox
    })
  } catch (error) {
    console.error('Failed to fetch seller info:', error)
  }
}

API Reference

Onboarding

Onboarding.configure(clientProps, eventHandlers)

Configures the onboarding process with your credentials and event handlers.

Parameters:

• clientProps (ClientProps):

  • publishableKey (string): Your Bolt publishable key
  • marketplaceSubMerchantID (string): Unique identifier of the seller in your platform
  • isTestEnv (boolean, optional): Set to true for sandbox environment, false for production (default: false)

• eventHandlers (OnboardingCallbacks):

  • onSuccess? (() => void): Called when onboarding completes successfully
  • onFailure? ((payload: { message: string }) => void): Called when onboarding fails
  • onNotify? ((payload: { message: string }) => void): Called for notifications during onboarding

Onboarding.start(): Promise<void>

Starts the onboarding process by displaying the iframe full-screen.

Onboarding.end(): void

Closes the onboarding iframe and cleans up resources. In general, sellers have the option to exit the onboarding, but marketplace can forcefully end the session using this function.

CheckoutHelpers

CheckoutHelpers.getSellerInfo(params): Promise<SellerInfoResponse>

Fetches seller information including onboarding status.

Parameters:

• params (GetSellerInfoParams):
  • publishableKey (string): Your Bolt publishable key
  • marketplaceSubMerchantID (string): Unique seller identifier in your platform
  • isTestEnv (boolean, optional): Set to true for sandbox environment (default: false)

Returns:

• SellerInfoResponse:
  • publishableKey (string): The publishable key of the seller
  • onboardingStatus ('completed' | 'unconfigured' | 'under_review'): Current onboarding status of the seller with Bolt Connect

Environment Configuration

Production Environment

const config = {
  publishableKey: 'your-production-publishable-key',
  marketplaceSubMerchantID: 'unique-seller-identifier-in-your-platform',
  isTestEnv: false, // Production environment
}

Sandbox Environment

const config = {
  publishableKey: 'your-sandbox-publishable-key',
  marketplaceSubMerchantID: 'unique-seller-identifier-in-your-platform',
  isTestEnv: true, // Sandbox environment
}

Error Handling

The SDK provides comprehensive error handling:

try {
  await Onboarding.start()
} catch (error) {
  // Handle iframe creation/display errors
  console.error('Onboarding error:', error)
}

try {
  const sellerInfo = await CheckoutHelpers.getSellerInfo(params)
} catch (error) {
  // Handle API errors (network, authentication, etc.)
  console.error('API error:', error)
}

Browser Support

The SDK supports all modern browsers with ES6+ support:

• Chrome 60+
• Firefox 55+
• Safari 12+
• Edge 79+

Support

For support and questions:

• 📧 Email: [email protected]
• 📚 Documentation: Bolt Connect Docs

Changelog

v1.0.0

• Stable Release: Production-ready marketplace SDK
• Seller Onboarding: Full-screen iframe integration with secure communication
• Seller Information Retrieval: API helpers for retrieving seller information
• TypeScript Support: Complete type definitions for all interfaces
• Environment Support: Production and sandbox environment configuration
• Error Handling: Comprehensive error handling and validation
• Performance: Caching for API responses
• Security: Origin validation and secure iframe communication