Discord bot and FastSpring embedded checkout integration

A Discord bot that brings your FastSpring web shop into your game's Discord server. Players run /store to see featured products (pulled live from FastSpring) and buy through an embedded FastSpring checkout; community managers run /announce to promote season updates and products to the whole server; and VIP members see exclusive items no one else does.

This page covers a working reference implementation from the FSBuilds GitHub repository, found in the fsbuilds-discord-store-bot folder of the FastSpring fsBuilds examples repo.

What it does

This section breaks down what the bot does for players and community managers, and where FastSpring stays the source of truth.

• /store: a single, branded message with featured product cards (image, description, price) and a buy button on each, plus a VIP Exclusives section for members and an Unlock VIP upsell for everyone else.
• /announce: community-manager-only. Posts a public web shop announcement with an optional custom banner and product cards chosen live from the catalog.
• VIP logic: a player is VIP by a Discord role or an active FastSpring subscription.
• Server-side checkout sessions: each Buy button creates a FastSpring Sessions API checkout on the server (product, buyer, and order tags), then shows it as an embedded checkout. Nothing editable rides in the URL.
• One-time account connect: players authorize once with Discord OAuth so the bot can give FastSpring their verified email (the Sessions API requires a buyer).
• Purchase confirmation and identity linking: a FastSpring webhook confirms purchases, DMs the buyer, and maps the Discord user to their FastSpring account.

Everything runs from one bot. Product data (names, prices, art, descriptions) lives in FastSpring and is fetched live, so updating the shop needs no code change.

How it works

This section gives a high-level view of how the player's Discord client, your server, and FastSpring coordinate during a purchase.

sequenceDiagram
    participant P as Player
    participant D as Discord Bot
    participant S as Your Server
    participant FS as FastSpring

    rect rgb(240, 253, 244)
        note over P,FS: 1. Browse
        P->>D: /store
        D->>FS: GET /products/{path}
        FS-->>D: Name, price, image, description
        D-->>P: Product cards and Buy button
    end

    rect rgb(255, 251, 235)
        note over P,S: 2. One-time connect (first purchase only)
        P->>S: Connect to buy
        S->>P: Discord OAuth prompt
        P->>S: Authorizes
        S-->>S: Save verified email
    end

    rect rgb(245, 243, 255)
        note over P,FS: 3. Checkout
        P->>S: Clicks Buy (signed token)
        S->>FS: POST /v2/checkouts/{path}/sessions
        FS-->>S: Session ID
        S-->>P: Embedded checkout (session ID)
        P->>FS: Completes purchase
    end

    rect rgb(254, 242, 242)
        note over FS,S: 4. Confirmation
        FS->>S: Webhook: order.completed (HMAC signed)
        S-->>S: Verify signature, link Discord and FastSpring account
        S-->>P: DM confirmation
    end

The player's client in Discord talks to your backend (Node and Express), which talks to FastSpring. The bot never handles payment; FastSpring does. The bot surfaces products, hands off to a FastSpring checkout, and listens for the result.

Prerequisites

Before you start building, make sure you have accounts and access set up on both the Discord and FastSpring side.

Project structure

This section maps out where each piece of the bot lives, so you know where to look when you want to customize something.

src/
├── index.js                 Entry point, starts the web server, then the bot
├── discord-client.js        The shared discord.js client
├── discord-oauth.js         One-time Discord OAuth (identify + email)
├── tokens.js                HMAC-signed, expiring tokens for buy/connect links
├── bot.js                   Registers commands, routes interactions
├── presentation.js          Branding, featured list, VIP list (edit this to reshape the shop)
├── roles.js                 hasRole() helper
├── vip.js                   checkVip(), role OR active subscription
├── commands/
│   ├── store.js             /store message (cards, buy buttons, VIP section)
│   └── announce.js          /announce (CM-only, product autocomplete, custom banner)
├── fastspring/
│   ├── api.js               FastSpring API client (Basic auth)
│   ├── catalog.js           Fetch products from FastSpring
│   ├── session.js           Build buy / connect / web-shop links
│   ├── sessions.js          createCheckout(), FastSpring Sessions API
│   └── accounts.js          Subscription lookup (VIP)
├── store/
│   └── repository.js        Discord to FastSpring link store (JSON file)
└── web/
    ├── server.js             Express server (captures raw body for HMAC)
    └── routes/
        ├── webhook.js        POST /webhook, verify, link, confirm
        ├── auth.js           GET /auth/discord (+ /callback), save email
        └── checkout.js       GET /checkout/:token, session, embedded checkout
assets/                       Branding images (hero banner + logo)
data/                         Link store (gitignored, contains email PII)

Set up the bot

Follow these steps in order to get the bot installed, connected to Discord and FastSpring, and running in your server.

This project lives inside FastSpring's shared fastspring-fsBuilds-examples repository, alongside other FSBuilds projects. Download the fsbuilds-discord-store-bot folder from GitHub, then open a terminal inside it for the steps below.

npm install
cp .env.example .env

https://discord.com/api/oauth2/authorize?client_id=<CLIENT_ID>&permissions=2147567616&scope=bot%20applications.commands

// src/fastspring/api.js
const fsApi = axios.create({
  baseURL: 'https://api.fastspring.com',
  auth: { username: process.env.FS_API_USERNAME, password: process.env.FS_API_PASSWORD },
  headers: { 'Content-Type': 'application/json' },
});

node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

DISCORD_VIP_ROLE_ID=<vip role id>
DISCORD_CM_ROLE_ID=<community manager role id>

// src/commands/announce.js
function isCommunityManager(interaction) {
  const cmRoleId = process.env.DISCORD_CM_ROLE_ID;
  return cmRoleId
    ? hasRole(interaction, cmRoleId)
    : interaction.memberPermissions?.has(PermissionFlagsBits.ManageGuild);
}

// Featured products (everyone). Array order = display order.
const FEATURED_PRODUCTS = ['100-coins', 'battle-pass', 'venomtail-egg', 'lavablast-egg'];

// VIP-only products.
const VIP_PRODUCTS = ['500-coins', 'mega-pack'];

// The subscription a non-VIP is nudged to buy to unlock VIP perks.
const VIP_UPSELL_PRODUCT = 'battle-pass';

npm start

Environment variables

This table lists every variable the bot reads from .env and where each value comes from.

Commands

This section documents what each slash command does, along with the code behind it.

/store

Ephemeral (only the player sees it). Shows the branded header and browse button, the VIP section (or upsell), and the featured items, each product with its own buy button. Until a player connects (once, via Discord OAuth), buttons read "Connect to buy." After that, each Buy link carries only a signed, expiring token:

// src/fastspring/session.js (per-player buy link)
function buildBuyLink(productPath, discordUserId, discordUsername) {
  const token = tokens.sign({ productPath, discordUserId, discordUsername }, 900);
  return `${serverBase()}/checkout/${token}`;
}

Clicking it creates the FastSpring session server-side and renders it embedded:

// src/web/routes/checkout.js
const { id: sessionId } = await createCheckout({
  productPath: claims.productPath,
  accountId: link.fsAccountId || undefined,          // returning buyer
  contact: link.email ? { email: link.email } : undefined, // first purchase (OAuth email)
  tags: { discordUserId: claims.discordUserId, discordUsername: claims.discordUsername || '' },
});
// serves a page that calls fastspring.builder.checkout(sessionId)

/announce

Community-manager-only. Posts a public web shop message.

The product options autocomplete straight from your catalog, so a manager curates each announcement with no code:

// src/commands/announce.js (live product autocomplete)
async function autocomplete(interaction) {
  const focused = (interaction.options.getFocused() || '').toLowerCase();
  const paths = await fetchAllProductPaths();          // GET /products
  await interaction.respond(
    paths.filter((p) => p.toLowerCase().includes(focused)).slice(0, 25).map((p) => ({ name: p, value: p }))
  );
}

Public announcements use an identity-free product link, since there's no single buyer to tag:

// src/fastspring/session.js
function featureUrl(productPath) {
  const base = process.env.WEBSHOP_URL || DEFAULT_WEBSHOP_URL;
  const sep = base.includes('?') ? '&' : '?';
  return `${base}${sep}prod=${encodeURIComponent(productPath)}`;
}

How the key pieces work

This section walks through the core logic behind the bot, from fetching live product data to verifying webhooks.

Live product data from FastSpring

The bot fetches only the products it needs and normalizes them for display. FastSpring is the source of truth for name, price, image, and description:

// src/fastspring/catalog.js
async function fetchProducts(paths) {
  const list = (paths || []).slice(0, 25);
  const results = await Promise.all(
    list.map((path) =>
      fsApi.get(`/products/${path}`).then((r) => r.data.products?.[0] || null).catch(() => null)
    )
  );
  return results.filter(Boolean).map(normalizeProduct); // { path, displayName, price, imageUrl, description }
}

The single /store message (Components V2)

/store renders one cohesive message: a hero banner, a browse button, then a card and buy button per product, grouped into VIP Exclusives and Featured Items sections with dividers.

VIP validation

A player is VIP by role or active subscription:

// src/vip.js
async function checkVip(interaction) {
  const viaRole = hasRole(interaction, process.env.DISCORD_VIP_ROLE_ID);
  let viaSubscription = false;
  const link = playerLinks.getByDiscordId(interaction.user.id);   // Discord to FastSpring account
  if (link?.fsAccountId) {
    viaSubscription = await accounts.hasActiveSubscription(link.fsAccountId); // GET /accounts?subscriptions=active
  }
  return { vip: viaRole || viaSubscription, viaSubscription, viaRole };
}

Two things to know about the subscription path, also noted in the code:

• It requires the Discord to FastSpring account ID, which is saved from the first order.completed webhook (the session's discordUserId order tag). Before a player's first purchase, VIP is role-only.
• It matches any active subscription. To gate on a specific product, check the subscription's product path.

The webhook: verify, link, confirm

FastSpring signs each webhook with your HMAC secret. The handler verifies it before trusting anything, then links the account and DMs the buyer:

// src/web/routes/webhook.js (signature check)
function verifySignature(rawBody, signature) {
  if (!rawBody || !signature) return false;
  const computed = crypto.createHmac('sha256', process.env.FS_WEBHOOK_SECRET).update(rawBody).digest('base64');
  try {
    return crypto.timingSafeEqual(Buffer.from(computed), Buffer.from(signature));
  } catch {
    return false;
  }
}

// passive identity link: a completed purchase proves the buyer controls both IDs
const fsAccountId = data?.account;
const email = data?.customer?.email;
if (discordUserId && fsAccountId) {
  playerLinks.upsert({ discordUserId, fsAccountId, email, linkSource: 'purchase' });
}

Privacy and data

This section covers what player data the bot stores and how it's kept out of version control.

• data/links.json stores customer email addresses, which is personal data. It's gitignored and must never be committed.
• The link store is a single JSON file (src/store/repository.js) behind a small interface, so you can swap it for a database without touching callers.

Before you go live

Before rolling this out to a live server, address these three gaps in the reference implementation.

Troubleshooting

Use this table to diagnose the most common issues when the bot isn't behaving as expected.

Related resources

These are the FastSpring and Discord references used throughout this guide.

• FastSpring API overview
• FastSpring Sessions API reference
• FastSpring Webhooks reference
• FastSpring Store Builder Library reference
• FastSpring embedded checkout setup
• List all subscriptions
• Discord Developer Portal
• FSBuilds GitHub repository