Skip to content

SwiftPayFi/sdk

BranchesTags

Repository files navigation

SwiftPay SDKs

Official SDKs for integrating SwiftPay payment infrastructure into your applications.

📦 Available SDKs

Checkout SDK (./checkout/)

Browser and React SDK for accepting stablecoin payments via popup, iframe, or redirect flows.

  • Package: @swiftpayfi/checkout-sdk
  • Platforms: Browser, React, vanilla JavaScript
  • Size: ~11 KB minified (IIFE)
  • Status: ✅ Production-ready
  • Documentation
import SwiftPayCheckout from '@swiftpayfi/checkout-sdk';

const checkout = new SwiftPayCheckout({ key: 'pk_live_...' });
const session = await checkout.createInvoice({ amount: 100, reference: 'order-123' });
await checkout.open();

Node.js SDK (./nodejs/)

Backend SDK for Node.js/TypeScript applications. Create invoices, manage webhooks, and handle payments server-side.

  • Package: @swiftpayfi/sdk
  • Platforms: Node.js 18+, TypeScript
  • Status: ✅ Production-ready
  • Documentation
import { SwiftPay } from '@swiftpayfi/sdk';

const client = new SwiftPay({ apiKey: 'sk_live_...' });
const invoice = await client.invoices.create({
  amount: 100,
  token: 'USDC',
  reference: 'order-123',
});

Python SDK (./python/)

Backend SDK for Python applications. Create invoices, manage webhooks, and handle payments server-side.

  • Package: swiftpay
  • Platforms: Python 3.8+
  • Status: ✅ Production-ready
  • Documentation
from swiftpay import SwiftPay

client = SwiftPay(api_key='sk_live_...')
invoice = client.invoices.create(
    amount=100,
    token='USDC',
    reference='order-123'
)

x402 Node Guard (./x402-node-guard/)

Express and Fastify middleware that enforces x402 payment-required responses, settling payments through the SwiftPay API before allowing access to protected routes.

  • Package: @swiftpayfi/x402-node-guard
  • Platforms: Node.js 18+, Express, Fastify
  • Status: ✅ Production-ready
  • Documentation
import { SwiftPay } from '@swiftpayfi/api-client';
import { x402Express } from '@swiftpayfi/x402-node-guard/express';

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

app.get('/v1/analyze', x402('https://api.example.com/v1/analyze'), (req, res) => {
  res.json({ sentiment: 'positive', score: 0.87 });
});

x402 FastAPI Guard (./x402-fastapi-guard/)

FastAPI middleware that enforces x402 payment-required responses, settling payments through the SwiftPay API before allowing access to protected routes.

  • Package: swiftpay-x402-fastapi-guard
  • Platforms: Python 3.8+, FastAPI
  • Status: ✅ Production-ready
  • Documentation
from fastapi import FastAPI
from swiftpay import AsyncSwiftPay
from swiftpay_x402_fastapi_guard import X402Guard

client = AsyncSwiftPay(secret_key="sk_live_...")

app = FastAPI()
app.add_middleware(
    X402Guard,
    client=client,
    routes={"/v1/analyze": "https://api.example.com/v1/analyze"},
)

🚀 Quick Start

Installation

# Checkout SDK (npm)
npm install @swiftpayfi/checkout-sdk

# Or use from CDN
<script src="https://cdn.swiftpay.finance/checkout@latest/index.iife.js"></script>

Basic Usage

// Initialize checkout
const checkout = new SwiftPayCheckout({
  key: 'pk_live_xxx',      // Your publishable key
  sandbox: false,          // Production API
  mode: 'iframe',          // popup | iframe | redirect
});

// Listen for payment completion
checkout.on('payment.completed', ({ invoice }) => {
  console.log('Payment received:', invoice.reference);
});

// Create an invoice
const session = await checkout.createInvoice({
  amount: 99.99,
  reference: 'order-12345',
});

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

Selecting the Right SDK

Use Case SDK Language
Browser/Frontend Checkout Checkout TypeScript/React
Backend Integration Node.js TypeScript/Node.js
Backend Integration Python Python
x402 Paywall (Express/Fastify) x402 Node Guard TypeScript/Node.js
x402 Paywall (FastAPI) x402 FastAPI Guard Python

SDK Comparison

Feature Checkout Node.js Python x402 Node Guard x402 FastAPI Guard
Invoice Creation ❌ Backend API ✅ ✅ ❌ ❌
Payment Detection ✅ Polling/SSE ✅ Webhooks ✅ Webhooks ✅ Auto-settle ✅ Auto-settle
Checkout UI ✅ ❌ ❌ ❌ ❌
Webhook Management ❌ ✅ ✅ ❌ ❌
x402 Paywall ❌ ❌ ❌ ✅ ✅
Type Safety ✅ TypeScript ✅ TypeScript ✅ Type hints ✅ TypeScript ✅ Type hints

🚀 Getting Started by Use Case

Frontend Checkout

  1. Install: npm install @swiftpayfi/checkout-sdk
  2. Read: Checkout SDK Docs
  3. Integrate: Use popup, iframe, or redirect mode

Backend Server (Node.js)

  1. Install: npm install @swiftpayfi/sdk
  2. Read: Node.js SDK Docs
  3. Integrate: Create invoices, handle webhooks

Backend Server (Python)

  1. Install: pip install swiftpay
  2. Read: Python SDK Docs
  3. Integrate: Create invoices, handle webhooks

x402 API Paywall (Node.js)

  1. Install: npm install @swiftpayfi/x402-node-guard @swiftpayfi/api-client
  2. Read: x402 Node Guard Docs
  3. Integrate: Add middleware to Express or Fastify routes

x402 API Paywall (Python)

  1. Install: pip install swiftpay-x402-fastapi-guard
  2. Read: x402 FastAPI Guard Docs
  3. Integrate: Add middleware to FastAPI routes

📂 Repository Structure

sdk/
├── checkout/                      # Browser/React checkout SDK (TypeScript)
│   ├── src/
│   │   ├── index.ts              # Main SDK class
│   │   └── react.ts              # React hook
│   ├── dist/                      # Compiled & minified output
│   ├── package.json
│   ├── README.md                  # Complete documentation
│   └── .gitignore
│
├── nodejs/                        # Backend SDK (Node.js/TypeScript)
│   ├── src/
│   ├── dist/
│   ├── test/
│   ├── package.json
│   ├── README.md                  # Complete documentation
│   └── vitest.config.ts           # Testing configuration
│
├── python/                        # Backend SDK (Python)
│   ├── src/
│   ├── tests/
│   ├── pyproject.toml
│   ├── README.md                  # Complete documentation
│   └── .python-version
│
├── x402-node-guard/               # x402 payment middleware (Express/Fastify)
│   ├── src/
│   ├── test/
│   ├── package.json
│   └── README.md                  # Complete documentation
│
├── x402-fastapi-guard/            # x402 payment middleware (FastAPI)
│   ├── src/
│   ├── tests/
│   ├── pyproject.toml
│   └── README.md                  # Complete documentation
│
├── .github/workflows/
│   ├── checkout-ci.yml            # Checkout SDK CI
│   ├── checkout-release.yml       # Checkout SDK release
│   ├── nodejs-ci.yml              # Node.js SDK CI
│   ├── nodejs-release.yml         # Node.js SDK release
│   ├── python-ci.yml              # Python SDK CI
│   └── python-release.yml         # Python SDK release
│
├── .changeset/
│   ├── config.json                # Changesets configuration
│   └── README.md                  # Version management guide
│
├── LICENSE                        # Apache 2.0 (applies to all SDKs)
├── .gitignore
└── README.md                      # This file

🛠️ Development

Local Setup

cd checkout

# Install dependencies
npm install

# Development mode (watch TypeScript compilation)
npm run dev

# Build all formats
npm run build

# Build specific formats
npm run build:types    # TypeScript declarations
npm run build:esm      # ES modules for npm
npm run build:iife     # Standalone browser script

Making Changes

  1. Create feature branch from dev or main:

    git checkout -b feat/my-feature dev

  2. Make your changes to the SDK

  3. Document the change with a changeset:

    npx changeset add
# Interactive prompt guides you through:
# - Which package changed
# - Bump type (major/minor/patch)
# - Change description

  4. Commit and push:

    git add .changeset/*.md checkout/
git commit -m "feat: add new capability"
git push origin feat/my-feature

  5. Open a pull request on GitHub — CI runs automatically

Development Branches

Branch Purpose Auto-publishes
main Production releases ✅ Latest to npm + CDN
dev Beta/pre-release testing ✅ Beta versions to npm
feat/* Feature branches ❌ Only for CI verification

📦 Releases & Versions

Version Numbering

  • Production: 1.0.0, 1.1.0, 2.0.0 (semantic versioning)
  • Beta: 1.0.0-beta.1, 1.0.0-beta.2 (on dev branch)

Accessing Releases

# Latest production version
npm install @swiftpayfi/checkout-sdk

# Specific version
npm install @swiftpayfi/checkout-sdk@1.0.0

# Latest beta (pre-release)
npm install @swiftpayfi/checkout-sdk@beta

# Browser CDN (production)
<script src="https://cdn.swiftpay.finance/checkout@latest/index.iife.js"></script>

# Browser CDN (specific version)
<script src="https://cdn.swiftpay.finance/checkout@1.0.0/index.iife.js"></script>

# Browser CDN (beta)
<script src="https://cdn.swiftpay.finance/checkout@beta/index.iife.js"></script>

Version Management

This project uses Changesets for automated version management. When you add a changeset, the version bump and changelog are generated automatically during release.

For detailed information, see Changesets Guide.

🛠️ System Requirements

  • Node.js: 20.0.0 or higher
  • npm: 10.0.0 or higher

Build Dependencies

  • TypeScript (5.9+) — Type checking
  • esbuild (0.21+) — Bundling and minification
  • Changesets (2.31+) — Version management
  • React (18+) — Peer dependency for React hook

🧪 Testing

Manual Testing Checklist

  • ✅ SDK initialization with different options
  • ✅ Invoice creation and checkout flows
  • ✅ All checkout modes (popup, iframe, redirect)
  • ✅ Event emission and callbacks
  • ✅ Error handling and edge cases
  • ✅ Cross-browser compatibility (Chrome, Firefox, Safari, Edge)
  • ✅ Mobile responsiveness

Automated CI

Pull requests and pushes to main, dev, and feat/* branches automatically run:

  • TypeScript type checking
  • Bundle generation (ESM + IIFE)
  • Package integrity verification

🔐 Security

API Endpoints

Environment Endpoint
Production https://api.swiftpay.finance
Sandbox https://sandbox-api.swiftpay.finance

The SDK automatically selects the correct endpoint based on the sandbox option.

Best Practices

  • ✅ Use publishable keys only (pk_*) in client code
  • ✅ Never commit or expose secret keys (sk_*)
  • ✅ Always use HTTPS in production
  • ✅ Validate origin in iframe integrations
  • ✅ Keep SDKs updated for security patches
  • ✅ Never log sensitive data (tokens, keys, card numbers)

📖 Documentation

🤝 Contributing

We welcome contributions! Here's how to get started:

  1. Review the development section above
  2. Create a feature branch from dev or main
  3. Make your changes and add a changeset
  4. Submit a pull request with a clear description
  5. Ensure CI passes and request review
  6. Once approved, merge your PR

Contribution Guidelines

  • Code style: Follow existing patterns in the codebase
  • TypeScript: Use strict type checking
  • Documentation: Update README.md if adding public APIs
  • Testing: Add manual test cases for new features
  • Commits: Write clear, descriptive commit messages
  • Changesets: Document all user-facing changes

📞 Support & Feedback

📄 License

Licensed under the Apache License, Version 2.0.

Summary:

  • ✅ Free to use, modify, and distribute
  • ✅ Commercial use allowed
  • ✅ Patent protection included
  • ✅ Must include license and copyright notice
  • ✅ No warranty or liability

Copyright © 2026 SwiftPay Finance

See LICENSE for full details.

Last Updated: May 2026
Latest Release: Check releases page
API Version: v1

About

Official SDKs for integrating SwiftPay payment infrastructure into your applications.

Resources

Readme

License

View license

Security policy

Security policy
Activity
Custom properties

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages