@codefly2026/checkout-sdk

A lightweight, embeddable payment checkout SDK with iframe isolation and dynamic form rendering.

Features

• 🔒 Iframe Isolation - Secure payment form in isolated iframe
• 🎨 Customizable Theme - Full theme customization (colors, fonts, logo)
• 📝 Dynamic Forms - JSON-driven form rendering with validation
• 💳 Multiple Payment Methods - Credit cards, wallets, bank transfers
• 📱 Responsive Design - Works on all screen sizes
• 🔌 Easy Integration - Simple API with TypeScript support

Installation

npm install @codefly2026/checkout-sdk
# or
yarn add @codefly2026/checkout-sdk
# or
pnpm add @codefly2026/checkout-sdk

Quick Start

1. Add a container element

<div id="checkout-container"></div>

2. Initialize the SDK

import PaySDK from '@codefly2026/checkout-sdk';

const checkout = PaySDK.createCheckout(
  {
    container: '#checkout-container',
    payment: {
      orderId: 'ORDER_123456',
      amount: 199.99,
      currency: 'USD',
    },
    theme: {
      primaryColor: '#1677ff',
      fontFamily: 'Inter, sans-serif',
      borderRadius: 8,
    },
    onSuccess: (result) => {
      console.log('Payment successful:', result);
      // { orderId, transactionId, amount, currency }
    },
    onFail: (error) => {
      console.error('Payment failed:', error);
      // { code, message }
    },
    onClose: () => {
      console.log('Checkout closed');
    },
  },
  'https://checkout.your-domain.com' // Your checkout app URL
);

// Open the checkout
checkout.open();

API Reference

PaySDK.createCheckout(options, iframeUrl)

Creates a new checkout instance.

Parameters

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | options | CheckoutOptions | Yes | Configuration options | | iframeUrl | string | Yes | URL of the checkout iframe application |

CheckoutOptions

| Property | Type | Required | Description | |----------|------|----------|-------------| | container | string \| HTMLElement | Yes | Container selector or DOM element | | width | number \| string | No | Iframe width (default: '100%') | | height | number \| string | No | Iframe height (default: '100%') | | payment | PaymentConfig | Yes | Payment parameters | | theme | ThemeConfig | No | Theme customization | | onSuccess | (result: PaymentResult) => void | No | Success callback | | onFail | (error: PaymentError) => void | No | Failure callback | | onClose | () => void | No | Close callback |

PaymentConfig

| Property | Type | Required | Description | |----------|------|----------|-------------| | orderId | string | Yes | Order ID | | amount | number | Yes | Payment amount | | currency | string | Yes | Currency code (USD, EUR, CNY, etc.) |

ThemeConfig

| Property | Type | Description | |----------|------|-------------| | primaryColor | string | Primary color (e.g., '#1677ff') | | primaryHoverColor | string | Primary hover color | | fontFamily | string | Font family | | logo | string | Logo URL | | borderRadius | number | Border radius in pixels | | backgroundColor | string | Background color | | cardBackgroundColor | string | Card background color | | textColor | string | Text color | | borderColor | string | Border color |

Checkout Instance Methods

checkout.open()

Opens the checkout and displays the payment form.

checkout.update(options)

Updates the checkout configuration.

checkout.update({
  payment: {
    orderId: 'ORDER_123456',
    amount: 299.99,
    currency: 'USD',
  },
  theme: {
    primaryColor: '#ff4d4f',
  },
});

checkout.close()

Closes and removes the checkout from the DOM.

checkout.destroy()

Destroys the checkout instance and cleans up resources.

Browser Support

• Chrome (latest)
• Firefox (latest)
• Safari (latest)
• Edge (latest)

TypeScript

This package includes TypeScript definitions out of the box.

import PaySDK, { 
  Checkout, 
  CheckoutOptions, 
  PaymentResult, 
  PaymentError,
  ThemeConfig 
} from '@codefly2026/checkout-sdk';

Security

• Payment forms are rendered in an isolated iframe
• Cross-origin communication via postMessage with origin validation
• No sensitive data is exposed to the parent page
• All financial data should be validated on your backend

License

MIT © codefly2026