kirapay-merchant-sdk

v1.1.9

Published

24 days ago

KiraPay JavaScript SDK for payment integration

0High
0Medium
0Low

simon_td

payment kirapay sdk javascript react nextjs typescript

KiraPay JavaScript SDK

A lightweight, framework-agnostic JavaScript SDK for integrating KiraPay payments into any website, including React, Next.js, and plain HTML applications.

Features

🚀 Universal compatibility: Works with React, Next.js, Vue, Angular, and plain HTML
📦 Multiple build formats: ESM, CommonJS, and UMD
🎨 Fully customizable: Style buttons with CSS classes or inline styles
📱 Responsive modal: Beautiful payment modal with iframe integration
🔒 Secure: API key-based authentication
📝 TypeScript support: Full type definitions included
🔄 Dynamic imports: Support for lazy loading and module imports
⚡ Performance optimized: Load SDK only when needed
🌐 SSR Support: Works with Next.js server-side rendering

Installation

NPM/Yarn (React, Next.js, etc.)

npm install kirapay-merchant-sdk
# or
yarn add kirapay-merchant-sdk

CDN (Plain HTML)

<!-- UMD Version -->
<script src="https://unpkg.com/kirapay-merchant-sdk"></script>

<!-- ES Module Version -->
<script type="module">
  import { ButtonDynamicPrice } from 'https://unpkg.com/kirapay-merchant-sdk?module';
</script>

Usage

1. Static Import (Traditional)

<!DOCTYPE html>
<html>
<head>
    <title>KiraPay Integration</title>
</head>
<body>
    <div id="payment-button"></div>

    <!-- Static Import -->
    <script src="https://unpkg.com/kirapay-merchant-sdk"></script>
    <script>
        const button = new kirapay.ButtonDynamicPrice({
            price: 100,
            apiKey: "your-api-key",
            title: "Pay Now"
        });
        document.getElementById('payment-button').appendChild(button.render());
    </script>
</body>
</html>

2. Dynamic Import (Lazy Loading)

<script>
    // Load SDK dynamically
    function loadSDK() {
        return new Promise((resolve, reject) => {
            const script = document.createElement('script');
            script.src = 'https://unpkg.com/kirapay-merchant-sdk';
            script.onload = () => resolve(window.kirapay);
            script.onerror = reject;
            document.body.appendChild(script);
        });
    }

    // Use when needed
    async function initializePayment() {
        try {
            const kirapay = await loadSDK();
            const button = new kirapay.ButtonDynamicPrice({
                price: 100,
                apiKey: "your-api-key"
            });
            document.getElementById('payment-button').appendChild(button.render());
        } catch (error) {
            console.error('Failed to load SDK:', error);
        }
    }
</script>

3. ES Module Import (Modern)

<script type="module">
    import { ButtonDynamicPrice } from 'https://unpkg.com/kirapay-merchant-sdk?module';

    const button = new ButtonDynamicPrice({
        price: 100,
        apiKey: "your-api-key"
    });
    document.getElementById('payment-button').appendChild(button.render());
</script>

4. React Integration

Static Import (Build Time)

import React, { useState, useEffect, useRef } from 'react';
import { ButtonDynamicPrice } from 'kirapay-merchant-sdk';

function PaymentComponent() {
  const [price, setPrice] = useState(100);
  const buttonRef = useRef(null);
  const buttonInstance = useRef(null);

  useEffect(() => {
    // Create button instance
    buttonInstance.current = new ButtonDynamicPrice({
      price: price,
      apiKey: "your-api-key",
      title: `Pay $${price}`,
      style: {
        backgroundColor: '#007bff',
        borderRadius: '8px'
      }
    });

    // Render button
    if (buttonRef.current) {
      buttonRef.current.appendChild(buttonInstance.current.render());
    }

    // Cleanup on unmount
    return () => {
      if (buttonInstance.current) {
        buttonInstance.current.destroy();
      }
    };
  }, []);

  // Update price dynamically
  const handlePriceChange = (newPrice) => {
    setPrice(newPrice);
    if (buttonInstance.current) {
      buttonInstance.current.updatePrice(newPrice);
    }
  };

  return (
    <div>
      <input 
        type="number" 
        value={price} 
        onChange={(e) => handlePriceChange(+e.target.value)}
      />
      <div ref={buttonRef}></div>
    </div>
  );
}

Dynamic Import (Runtime)

import React, { useState, useEffect, useRef } from 'react';

function PaymentComponent() {
  const [price, setPrice] = useState(100);
  const [isLoading, setIsLoading] = useState(false);
  const [error, setError] = useState(null);
  const buttonRef = useRef(null);
  const buttonInstance = useRef(null);

  // Dynamic import function
  const loadSDK = async () => {
    try {
      const { ButtonDynamicPrice } = await import('kirapay-merchant-sdk');
      return ButtonDynamicPrice;
    } catch (err) {
      throw new Error('Failed to load KiraPay SDK');
    }
  };

  // Initialize button
  const initializeButton = async () => {
    setIsLoading(true);
    setError(null);

    try {
      const ButtonDynamicPrice = await loadSDK();
      
      // Create button instance
      buttonInstance.current = new ButtonDynamicPrice({
        price: price,
        apiKey: "your-api-key",
        title: `Pay $${price}`,
        style: {
          backgroundColor: '#28a745',
          borderRadius: '8px'
        }
      });

      // Render button
      if (buttonRef.current) {
        buttonRef.current.appendChild(buttonInstance.current.render());
      }
    } catch (err) {
      setError(err.message);
    } finally {
      setIsLoading(false);
    }
  };

  // Handle price change
  const handlePriceChange = (e) => {
    const newPrice = +e.target.value;
    setPrice(newPrice);
    if (buttonInstance.current) {
      buttonInstance.current.updatePrice(newPrice);
    }
  };

  // Cleanup on unmount
  useEffect(() => {
    return () => {
      if (buttonInstance.current) {
        buttonInstance.current.destroy();
      }
    };
  }, []);

  return (
    <div>
      <input 
        type="number" 
        value={price} 
        onChange={handlePriceChange}
      />
      <button 
        onClick={initializeButton}
        disabled={isLoading}
      >
        {isLoading ? 'Loading SDK...' : 'Load SDK & Show Button'}
      </button>
      {error && <div style={{ color: 'red' }}>Error: {error}</div>}
      <div ref={buttonRef}></div>
    </div>
  );
}

5. Next.js Integration

import React, { useState, useEffect, useRef } from 'react';

function NextJSPaymentComponent() {
  const [price, setPrice] = useState(100);
  const [isClient, setIsClient] = useState(false);
  const buttonRef = useRef(null);
  const buttonInstance = useRef(null);

  useEffect(() => {
    setIsClient(true);
  }, []);

  useEffect(() => {
    if (!isClient) return;

    // Import SDK dynamically
    import('kirapay-merchant-sdk').then(({ ButtonDynamicPrice }) => {
      // Create button instance
      buttonInstance.current = new ButtonDynamicPrice({
        price: price,
        apiKey: "your-api-key",
        title: `Pay $${price}`,
        style: {
          backgroundColor: "#007bff",
          borderRadius: "8px"
        }
      });

      // Render button
      if (buttonRef.current) {
        buttonRef.current.appendChild(buttonInstance.current.render());
      }
    }).catch(error => {
      console.error('Failed to load KiraPay SDK:', error);
    });

    // Cleanup
    return () => {
      if (buttonInstance.current) {
        buttonInstance.current.destroy();
      }
    };
  }, [isClient, price]);

  // Handle price change
  const handlePriceChange = (e) => {
    const newPrice = +e.target.value;
    setPrice(newPrice);
    if (buttonInstance.current) {
      buttonInstance.current.updatePrice(newPrice);
    }
  };

  if (!isClient) {
    return <div>Loading...</div>;
  }

  return (
    <div>
      <input 
        type="number" 
        value={price} 
        onChange={handlePriceChange}
      />
      <div ref={buttonRef}></div>
    </div>
  );
}

API Reference

ButtonDynamicPrice

Creates a payment button that generates checkout URLs dynamically based on price.

Constructor Options

interface ButtonDynamicPriceConfig {
  price: number;                    // Payment amount
  apiKey: string;                  // Your KiraPay API key
  customOrderId?: string;          // Custom order ID (optional)
  title?: string;                  // Button text (default: "Pay with KiraPay")
  className?: string;              // CSS class name
  style?: object;                  // Inline styles
  loading?: boolean;               // Initial loading state
}

new ButtonDynamicPrice(config: ButtonDynamicPriceConfig)

Methods

render(): Returns the DOM element to insert into your page
destroy(): Cleans up the button and closes any open modals
setLoading(loading: boolean): Updates the loading state
updatePrice(price: number): Updates the payment amount

Example Implementations

We provide several example implementations in the /examples directory:

Basic Integration:
- /examples/static-import.html: Traditional script tag import
- /examples/dynamic-import.html: Lazy loading examples
- /examples/module-import.html: ES Module import
React Examples:
- /examples/react-static-import.jsx: React with static import
- /examples/react-dynamic-import.jsx: React with dynamic import
Next.js Examples:
- /examples/nextjs-example.jsx: Next.js integration with SSR support
E-commerce Examples:
- /src/example.html: Complete e-commerce checkout page with:
  - Product selection
  - Dynamic pricing
  - Shopping cart
  - Custom styling

To run the examples:

python3 -m http.server 8000

# Then open in browser:
# http://localhost:8000/examples/static-import.html
# http://localhost:8000/examples/dynamic-import.html
# http://localhost:8000/examples/module-import.html
# http://localhost:8000/src/example.html

Styling

Default Styling

The SDK comes with default styling that you can override:

.kirapay-button {
  padding: 12px 24px;
  background-color: #007bff;
  color: white;
  border: none;
  border-radius: 8px;
  font-size: 16px;
  font-weight: 600;
  cursor: pointer;
  transition: all 0.2s ease;
}

Custom Styling

You can customize the button in two ways:

Using inline styles:

const button = new ButtonDynamicPrice({
  // ... other options
  style: {
    backgroundColor: '#28a745',
    color: 'white',
    padding: '15px 30px',
    fontSize: '18px',
    borderRadius: '12px',
    border: '2px solid #28a745'
  }
});

Using CSS classes:

const button = new ButtonDynamicPrice({
  // ... other options
  className: 'my-custom-button'
});

Development

# Install dependencies
npm install

# Build the SDK
npm run build

# Watch for changes during development
npm run dev

# Run examples
python3 -m http.server 8000

Publishing

# Update version
npm version patch  # for bug fixes (1.0.0 -> 1.0.1)
npm version minor  # for new features (1.0.0 -> 1.1.0)
npm version major  # for breaking changes (1.0.0 -> 2.0.0)

# Build and publish
npm run build
npm publish

Browser Support

Chrome 60+
Firefox 55+
Safari 12+
Edge 79+

TypeScript Support

The SDK includes built-in TypeScript definitions. No need to install additional @types packages.

import { ButtonDynamicPrice } from 'kirapay-merchant-sdk';

const button = new ButtonDynamicPrice({
  price: 100,
  apiKey: "your-api-key"
});

License

MIT License - see LICENSE file for details.

Support

For support and questions:

Documentation: https://docs.kirapay.com
GitHub Issues: https://github.com/kirapay/kirapay-merchant-sdk/issues