Quickstart

From API keys to first virtual account in 15 minutes.

Follow these steps to create your first sandbox virtual account using the Mainstreetspine API.

Prerequisites

To follow this quickstart, you'll need:

A Mainstreetspine sandbox API key (request via pilot access form)
Node.js 18+ or Python 3.9+ or Ruby 3.0+
Basic familiarity with REST APIs

Install the SDK

npm install mainstreetspine-node
# or
pip install mainstreetspine
# or
gem install mainstreetspine

Create a Platform

Every virtual account belongs to a Platform entity. Register your SaaS product as a platform first.

const mss = require('mainstreetspine-node');
const client = new mss.Client({
  apiKey: process.env.MSS_API_KEY,
  environment: 'sandbox'
});

const platform = await client.platforms.create({
  name: 'My Fitness SaaS',
  vertical: 'fitness_wellness',
  webhook_url: 'https://your-app.com/webhooks/mss'
});
// platform.id → 'plt_8xHQ2mNk'

Create a Virtual Account

Provision a virtual account for each SMB entity on your platform.

const account = await client.virtualAccounts.create({
  platform_id: platform.id,
  entity_ref: 'studio-123',
  type: 'checking',
  metadata: {
    studio_name: 'Oakwood Yoga Studio'
  }
});

console.log(account.account_number); // 826041200412
console.log(account.routing_number); // 021000021

Submit a KYB Request

Before a virtual account can receive or send funds, the business entity must pass KYB verification.

const kyb = await client.kyb.create({
  virtual_account_id: account.id,
  business: {
    name: 'Oakwood Yoga Studio LLC',
    ein: '12-3456789',
    address: {
      line1: '822 Oakwood Ave SE',
      city: 'Atlanta',
      state: 'GA',
      zip: '30316'
    }
  }
});
// kyb.status → 'pending' | 'approved' | 'pending_review'

Initiate a Payment

Once KYB is approved, initiate ACH or RTP payments from the virtual account.

const payment = await client.payments.create({
  virtual_account_id: account.id,
  amount: 42500, // cents
  rail: 'rtp',
  destination: {
    account_number: '123456789',
    routing_number: '021000021',
    name: 'Instructor Jane Smith'
  },
  idempotency_key: 'payout-2025-04-14-jane'
});

Sandbox Note

In sandbox mode, all payments are simulated. KYB always returns approved for test EINs ending in -0000. ACH settlements simulate T+1 overnight. RTP settlements respond instantly.

When you're ready to go live, swap your environment to 'production' and use your live API key. Contact [email protected] to request live environment access.