JavaScript SDK quickstart

Install the SDK, open a payment link your backend created, and read the transaction reference the player's purchase returns.

Prerequisites

A web game or web app built with React, Vue, Angular, or plain JavaScript.
A backend server that can call the Bolt Gaming API with your secret API key.
A sandbox merchant account and API keys. Follow Checkout quickstart first if you do not have them.

1. Install the SDK

npm install @boltpay/bolt-js

Expected result: @boltpay/bolt-js appears in your dependencies. The package ships TypeScript definitions, so no separate types package is needed.

2. Create a payment link on your backend

The SDK opens a link; it does not create one. Your backend calls POST /v1/gaming/payment_links with your secret API key and returns the link value to your client. Never put the API key in browser code.

Request

curl --location 'https://api-sandbox.boltapp.com/v1/gaming/payment_links' \
--header 'X-API-KEY: YOUR_API_KEY' \
--header 'X-PUBLISHABLE-KEY: YOUR_PUBLISHABLE_KEY' \
--header 'Content-Type: application/json' \
--data '{
    "game_id": "YOUR_GAME_ID",
    "user_id": "USER_ID",
    "redirect_url": "yourgame://bolt-webcheckout/success",
    "item": {
        "price": 699,
        "name": "Gems Pack",
        "image_url": "https://yourcdn.example.com/gems.png",
        "currency": "USD"
    }
}'

The response carries the URL your client opens:

Response

{
  "id": "CyzZV9Zh45t2rLE3ubG75x",
  "link": "https://your-store.c-sandbox.boltapp.com/o?order_token=...&payment_link_id=...&publishable_key=..."
}

See Create payment link for every parameter.

3. Open checkout from your app

Initialize the SDK once when your app starts. gameId and publishableKey come from the sandbox dashboard:

TypeScript

import { BoltSDK } from '@boltpay/bolt-js'

await BoltSDK.initialize({
  gameId: 'YOUR_GAME_ID',
  publishableKey: 'YOUR_PUBLISHABLE_KEY',
  environment: 'sandbox',
})

Then pass the link value to BoltSDK.gaming.openCheckout(). It resolves with a PaymentLinkSession carrying the link's paymentLinkId and status.

import { BoltSDK } from '@boltpay/bolt-js'
import { useState } from 'react'

function CheckoutButton({ checkoutUrl }: { checkoutUrl: string }) {
  const [loading, setLoading] = useState(false)

  const handlePayment = async () => {
    setLoading(true)
    try {
      const session = await BoltSDK.gaming.openCheckout(checkoutUrl)
      console.log('Checkout session:', session?.paymentLinkId, session?.status)
    } finally {
      setLoading(false)
    }
  }

  return (
    <button onClick={handlePayment} disabled={loading}>
      {loading ? 'Processing...' : 'Pay with Bolt'}
    </button>
  )
}

Expected result: Bolt checkout opens over your game. On completion the promise resolves with a transaction object.

4. Grant the purchase from your backend

openCheckout() resolves with a PaymentLinkSession:

TypeScript

import type { PaymentLinkSession } from '@boltpay/bolt-js'

interface PaymentLinkSession {
  paymentLinkId: string
  paymentLinkUrl: string
  status: 'pending' | 'successful' | 'expired' | 'abandoned'
  createdAt: Date
  updatedAt: Date
  completedAt?: Date
}

Treat the session as a client-side record to display or log, not as proof of payment. Bolt sends a transaction webhook to your backend, so grant items there and have the client re-read the player's state. See Validate webhook authenticity.

5. Verify the flow

Run your app against a sandbox payment link and complete a purchase.

Expected result: The promise resolves and your console logs the payment link id and status.
Open Transactions in the sandbox Merchant Dashboard.

Expected result: The transaction appears with the item and amount from your payment link.
Confirm your backend received the transaction webhook and granted the item.

Show a reward ad

The SDK can also open an ad and tell you when the player claims the reward.

React

import { BoltSDK } from '@boltpay/bolt-js'

function AdButton() {
  const handleAdDisplay = async () => {
    await BoltSDK.gaming.openAd({
      onClaim: () => {
        console.log('Reward claimed')
      },
    })
  }

  return <button onClick={handleAdDisplay}>Watch ad</button>
}