Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.swiftpay.finance/llms.txt

Use this file to discover all available pages before exploring further.

The Checkout SDK is a lightweight (~11 KB minified), type-safe JavaScript library for integrating SwiftPay’s payment UI into your web application. It supports popup, iframe, and redirect checkout flows with real-time payment status tracking.

​
Features

  • Multiple checkout modes — Popup, iframe, or redirect
  • Real-time updates — SSE + polling for payment status
  • Marketplace-friendly — Create multiple invoices with one instance
  • Type-safe — Full TypeScript support
  • Lightweight — ~11 KB minified (IIFE)
  • Multi-chain — Ethereum, Polygon, Solana, Tron support
  • Sandbox mode — Built-in sandbox/production switching

​
Installation

npm install @swiftpayfi/checkout-sdk

​
Quick Start

​
Vanilla JavaScript

import SwiftPayCheckout from '@swiftpayfi/checkout-sdk';

// 1. Initialize once per page
const checkout = new SwiftPayCheckout({
  key: 'pk_live_xxx',           // Your publishable key
  token: 'USDC',                 // Default asset (can override per invoice)
  chains: ['ethereum'],          // Supported chains
  mode: 'iframe',                // popup | iframe | redirect
  sandbox: false,                // Use sandbox API
});

// 2. Listen for payment events
checkout.on('payment.completed', ({ invoice }) => {
  console.log('✅ Payment completed:', invoice.reference);
  // Update your backend/UI
});

// 3. Create invoice for a product
async function buyProduct(productId, price) {
  const session = await checkout.createInvoice({
    amount: price,
    reference: productId,
    metadata: { productId, userId: currentUser.id },
  });

  if (session) {
    // 4. Open checkout UI
    await checkout.open();
  }
}

​
React Hook

import { useSwiftPayCheckout } from '@swiftpayfi/checkout-sdk/react';

function CheckoutButton({ product }) {
  const {
    createInvoice,
    open,
    isLoading,
    session,
    error,
  } = useSwiftPayCheckout({
    key: 'pk_live_xxx',
    token: 'USDC',
    chains: ['ethereum'],
    sandbox: false,
    onSuccess: ({ invoice }) => {
      console.log('Payment complete:', invoice);
      // Fulfill order
    },
  });

  const handleCheckout = async () => {
    const session = await createInvoice({
      amount: product.price,
      reference: product.id,
    });
    if (session) {
      await open();
    }
  };

  return (
    <button onClick={handleCheckout} disabled={isLoading}>
      {isLoading ? 'Processing...' : `Pay $${product.price}`}
    </button>
  );
}

​
Configuration

new SwiftPayCheckout({
  key: string;                    // Required: Your publishable key (pk_live_*)
  token?: string;                 // Default asset: USDC, USDT, etc (can override per invoice)
  chains?: string[];              // Networks: ethereum, polygon, solana, tron
  mode?: 'popup' | 'iframe' | 'redirect';  // Default: 'popup'
  sandbox?: boolean;              // Default: false
})

​
Event Types

Listen for payment lifecycle events: 
checkout.on('ready', () => {
  console.log('Checkout loaded and ready');
});

checkout.on('status', ({ status, invoice }) => {
  // status: 'pending' | 'partial' | 'paid' | 'completed'
  console.log(`Payment ${status}:`, invoice.id);
});

checkout.on('payment.pending', ({ invoice }) => {
  console.log('Payment initiated:', invoice.id);
});

checkout.on('payment.completed', ({ invoice }) => {
  console.log('Payment completed:', invoice.id);
});

checkout.on('error', ({ error, invoice }) => {
  console.error('Checkout error:', error.message);
});

checkout.on('cancel', () => {
  console.log('User closed checkout');
});

​
Checkout Modes Comparison

ModeBest ForUser Flow
PopupSingle paymentModal overlay, user stays on page
iFrameEmbedded checkoutSeamless page integration
RedirectMobile-firstFull-screen experience, redirects to pay.swiftpay.finance

​
Creating Invoices

The checkout SDK doesn’t create invoices directly — invoices are created on your backend using the Node.js or Python SDK, then opened in the checkout UI: 
import { SwiftPay } from '@swiftpayfi/api-client';

const client = new SwiftPay({
  secretKey: process.env.SWIFTPAY_SECRET_KEY,
});

const { invoice } = await client.invoices.create({
  amount: '100.00',
  token: 'USDC',
  network: 'ethereum',
  recipients: { evm: '0xYourWallet...' },
  externalRef: 'order_12345',
});

​
Environment Switching

const checkout = new SwiftPayCheckout({
  key: process.env.NODE_ENV === 'production' 
    ? 'pk_live_xxx'      // Production key
    : 'pk_test_xxx',     // Sandbox key
  sandbox: process.env.NODE_ENV !== 'production',
});

​
Marketplace Pattern

Create and manage multiple invoices with one checkout instance: 
async function openCheckoutForItem(item) {
  const session = await checkout.createInvoice({
    amount: item.price,
    reference: item.id,
    metadata: { itemId: item.id, sellerId: item.seller },
  });
  
  if (session) {
    await checkout.open();
  }
}

// Each item has its own invoice; SDK manages the state
await openCheckoutForItem(item1);
// ... later ...
await openCheckoutForItem(item2);

​
Full API Reference

For complete API documentation, type definitions, and advanced patterns, see the official Checkout SDK on NPM.