Paypercut Checkout JavaScript SDK

A lightweight, framework-agnostic JavaScript SDK for embedding Paypercut Checkout into your web application. Works seamlessly with vanilla JavaScript, TypeScript, React, Vue, Angular, and other modern frameworks.

Table of Contents

• Features
• How It Works
• Installation
• Quick Start
• API Reference
• Events
• Usage Examples
  • Vanilla JavaScript
  • TypeScript / ESM
  • React
• Security
• Troubleshooting
• Performance Optimization
• Best Practices
• FAQ
• Support

Installation

Via NPM

npm install @paypercut/checkout-js

Via Yarn

yarn add @paypercut/checkout-js

Via PNPM

pnpm add @paypercut/checkout-js

Via CDN

<!-- jsDelivr (recommended with SRI) -->
<script src="https://cdn.jsdelivr.net/npm/@paypercut/checkout-js@1.0.7/dist/paypercut-checkout.iife.min.js"
        integrity="sha384-..."
        crossorigin="anonymous"></script>

<!-- or UNPKG -->
<script src="https://unpkg.com/@paypercut/checkout-js@1.0.7/dist/paypercut-checkout.iife.min.js"></script>

Quick Start

This returns a checkout session ID like CHK_12345.

1. Embed the Checkout

Use the checkout ID to initialize the checkout on your frontend:

import { PaypercutCheckout } from '@paypercut/checkout-js';

// Initialize the checkout
const checkout = PaypercutCheckout({
  id: 'CHK_12345',              // Your checkout session ID from step 1
  containerId: '#checkout'       // CSS selector or HTMLElement
});

// Listen for payment events
checkout.on('success', () => {
  console.log('Payment successful!');
});

checkout.on('error', () => {
  console.error('Payment failed');
});

// Optional: Listen for when iframe finishes loading (useful for modal implementations)
checkout.on('loaded', () => {
  console.log('Checkout loaded and ready');
});

// Render the checkout
checkout.render();

That's it! The checkout is now embedded in your page.

2. Display Mode

The SDK supports one display mode:

API Reference

PaypercutCheckout(options)

Creates a new checkout instance.

Options

Example

const checkout = PaypercutCheckout({
  id: 'CHK_12345',
  containerId: '#checkout-container'
});

Instance Methods

render()

Mounts and displays the checkout iframe.

checkout.render();

destroy()

Destroys the instance and cleans up all event listeners. Call this when you're done with the checkout instance.

checkout.destroy();

on(event, handler)

Subscribes to checkout events. Returns an unsubscribe function.

const unsubscribe = checkout.on('success', () => {
  console.log('Payment successful!');
});

// Later, to unsubscribe
unsubscribe();

once(event, handler)

Subscribes to a checkout event that automatically unsubscribes after the first emission. Returns an unsubscribe function.

checkout.once('loaded', () => {
  console.log('Checkout loaded - this will only fire once');
});

off(event, handler)

Unsubscribes from checkout events.

const handler = () => console.log('Payment successful!');
checkout.on('success', handler);
checkout.off('success', handler);

isMounted()

Returns whether the checkout is currently mounted.

if (checkout.isMounted()) {
  console.log('Checkout is visible');
}

Events

Subscribe to events using the on() method:

3DS Events (enum usage recommended)

You can subscribe using string event names or the SdkEvent enum:

import { PaypercutCheckout, SdkEvent } from '@paypercut/checkout-js';

const checkout = PaypercutCheckout({ id: 'CHK_12345', containerId: '#checkout' });

checkout.on(SdkEvent.ThreeDSStarted, (ctx) => {
  // e.g., show your own UI indicator or log ctx
});

checkout.on(SdkEvent.ThreeDSComplete, (payload) => {
  // 3DS completed successfully; Hosted Checkout will continue the flow
});

checkout.on(SdkEvent.ThreeDSCanceled, (payload) => {
  // User canceled the 3DS challenge
});

checkout.on(SdkEvent.ThreeDSError, (err) => {
  // Normalized ApiErrorPayload when available; fallback may be a raw object
  console.error('3DS error:', err);
});

Payload notes:

• error: the SDK forwards a normalized ApiErrorPayload when provided by Hosted Checkout.
• threeds_error: forwards payload.error when available; otherwise the raw message data.
• threeds_* non-error events: payload is forwarded as-is from Hosted Checkout (shape may evolve).

Core events (loaded, success, error, expired)

Using enums:

import { PaypercutCheckout, SdkEvent } from '@paypercut/checkout-js';

const checkout = PaypercutCheckout({ id: 'CHK_12345', containerId: '#checkout' });

checkout.on(SdkEvent.Loaded, () => {
  console.log('Checkout loaded');
});

checkout.on(SdkEvent.Success, () => {
  console.log('Payment successful');
});

checkout.on(SdkEvent.Error, (err) => {
  // err: ApiErrorPayload
  console.error('Payment error:', err.code, err.message);
});

checkout.on(SdkEvent.Expired, () => {
  console.warn('Checkout session expired');
});

Or with string event names:

checkout.on('loaded', () => {});
checkout.on('success', () => {});
checkout.on('error', (err) => {});
checkout.on('expired', () => {});

Types

ApiErrorPayload (example shape)

Example only; all fields are optional and additional passthrough properties may be present.

// Example shape for values received in `checkout.on('error', (err))`
type ApiErrorPayload = {
  code?:
    | 'threeds_error'
    | 'threeds_authentication_failed'
    | 'threeds_canceled'
    | 'card_declined'
    | 'authentication_failed'
    | 'session_expired'
    | string;
  type?: 'card_error' | string;
  message?: string;
  status?: number;       // HTTP-like status if available
  decline_code?: string; // Optional decline reason
  // ...other passthrough fields may be included by the server
};

3DS payloads (representative samples)

The SDK forwards whatever Hosted Checkout sends for 3DS events. Shapes may evolve.

// threeds_started
{
  type: 'THREEDS_START_FLOW',
  checkoutId: 'CHK_12345',
  // additional context as provided by Hosted Checkout (e.g., method, acsUrl)
}

// threeds_complete
{
  type: 'THREEDS_COMPLETE',
  checkoutId: 'CHK_12345',
  // authentication result context (e.g., status: 'Y' | 'A' | 'C' | 'D')
}

// threeds_canceled
{
  type: 'THREEDS_CANCELED',
  checkoutId: 'CHK_12345',
}

// threeds_error (non-terminal)
// Note: terminal failures will also be emitted on `error` with ApiErrorPayload
{
  type: 'THREEDS_ERROR',
  checkoutId: 'CHK_12345',
  error?: ApiErrorPayload,
}

Tip: Prefer subscribing with the SdkEvent enum for stronger typing.

Usage Examples

Vanilla JavaScript (CDN)

<!DOCTYPE html>
<html>
<head>
  <title>Paypercut Checkout</title>
</head>
<body>
  <div id="checkout"></div>
  
  <script src="https://cdn.jsdelivr.net/npm/@paypercut/checkout-js@1.0.7/dist/paypercut-checkout.iife.min.js"></script>
  <script>
    const checkout = PaypercutCheckout({
      id: 'CHK_12345',
      containerId: '#checkout'
    });

    checkout.on('success', function() {
      alert('Payment successful!');
    });

    checkout.on('error', function(error) {
      alert('Payment failed: ' + error.message);
    });

    checkout.render();
  </script>
</body>
</html>

TypeScript / ESM

import { PaypercutCheckout } from '@paypercut/checkout-js';

const checkout = PaypercutCheckout({
  id: 'CHK_12345',
  containerId: '#checkout'
});

checkout.on('success', () => {
  console.log('Payment successful');
  // Redirect to success page
  window.location.href = '/success';
});

checkout.on('error', (error) => {
  console.error('Payment error:', error);
  // Show error message to user
  alert(`Payment failed: ${error.message}`);
});

checkout.render();

React

import { useEffect, useRef, useState } from 'react';
import { PaypercutCheckout, CheckoutInstance } from '@paypercut/checkout-js';

export function CheckoutComponent({ checkoutId }: { checkoutId: string }) {
  const containerRef = useRef<HTMLDivElement>(null);
  const checkoutRef = useRef<CheckoutInstance | null>(null);
  const [status, setStatus] = useState<'idle' | 'loading' | 'success' | 'error'>('idle');

  useEffect(() => {
    if (!containerRef.current) return;

    const checkout = PaypercutCheckout({
      id: checkoutId,
      containerId: containerRef.current
    });

    checkout.on('loaded', () => {
      setStatus('idle');
      console.log('Checkout loaded');
    });

    checkout.on('success', () => {
      setStatus('success');
      console.log('Payment successful');
    });

    checkout.on('error', (error) => {
      setStatus('error');
      console.error('Payment error:', error);
    });

    checkout.render();
    checkoutRef.current = checkout;

    return () => {
      checkout.destroy();
    };
  }, [checkoutId]);

  return (
    <div>
      <div ref={containerRef} style={{ width: '100%', height: '600px' }} />
      {status === 'loading' && <p>Processing payment...</p>}
      {status === 'success' && <p>✅ Payment successful!</p>}
      {status === 'error' && <p>❌ Payment failed. Please try again.</p>}
    </div>
  );
}

Modal-like Implementation

If you want to create a modal-like experience, you can use the loaded event to show/hide a loading overlay:

import { useEffect, useRef, useState } from 'react';
import { PaypercutCheckout, CheckoutInstance } from '@paypercut/checkout-js';

export function ModalCheckout({ checkoutId, onClose }: { checkoutId: string; onClose: () => void }) {
  const containerRef = useRef<HTMLDivElement>(null);
  const [isLoading, setIsLoading] = useState(true);

  useEffect(() => {
    if (!containerRef.current) return;

    const checkout = PaypercutCheckout({
      id: checkoutId,
      containerId: containerRef.current
    });

    checkout.on('loaded', () => {
      setIsLoading(false);
    });

    checkout.on('success', () => {
      console.log('Payment successful');
      onClose();
    });

    checkout.on('error', (error) => {
      console.error('Payment error:', error);
    });

    checkout.render();

    return () => {
      checkout.destroy();
    };
  }, [checkoutId, onClose]);

  return (
    <div style={{
      position: 'fixed',
      top: 0,
      left: 0,
      right: 0,
      bottom: 0,
      backgroundColor: 'rgba(0, 0, 0, 0.5)',
      display: 'flex',
      alignItems: 'center',
      justifyContent: 'center',
      zIndex: 9999
    }}>
      <div style={{
        position: 'relative',
        width: '90%',
        maxWidth: '500px',
        height: '90%',
        maxHeight: '700px',
        backgroundColor: '#fff',
        borderRadius: '12px',
        overflow: 'hidden'
      }}>
        {isLoading && (
          <div style={{
            position: 'absolute',
            top: 0,
            left: 0,
            right: 0,
            bottom: 0,
            display: 'flex',
            alignItems: 'center',
            justifyContent: 'center',
            backgroundColor: '#fff',
            zIndex: 1
          }}>
            <p>Loading checkout...</p>
          </div>
        )}
        <div ref={containerRef} style={{ width: '100%', height: '100%' }} />
        <button
          onClick={onClose}
          style={{
            position: 'absolute',
            top: '10px',
            right: '10px',
            zIndex: 2
          }}
        >
          ✕
        </button>
      </div>
    </div>
  );
}

Security

Origin Validation

The SDK automatically validates all postMessage communications against the configured checkoutHost origin. This prevents unauthorized messages from being processed.

Content Security Policy

For enhanced security, configure your Content Security Policy headers:

Content-Security-Policy:
  frame-src https://buy.paypercut.io OR something else;
  script-src 'self' https://cdn.jsdelivr.net https://unpkg.com;
  connect-src https://buy.paypercut.io  OR something else;

HTTPS Only

Always use HTTPS in production. The SDK is designed for secure communication over HTTPS.

Troubleshooting

Checkout not displaying

Problem: The iframe doesn't appear after calling render().

Solutions:

• Ensure the container element exists in the DOM before calling render()
• Check that the id is a valid checkout session ID
• Verify there are no CSP errors in the browser console
• Enable debug mode: debug: true to see detailed logs

Events not firing

Problem: Event handlers are not being called.

Solutions:

• Ensure you subscribe to events before calling render()
• Check that the checkout session is active and not expired
• Enable debug mode to see message logs

TypeScript errors

Problem: TypeScript shows type errors when using the SDK.

Solutions:

• Ensure you're importing types: import { PaypercutCheckout, CheckoutInstance } from '@paypercut/checkout-js'
• Update to the latest version of the SDK
• Check that your tsconfig.json includes the SDK's type definitions

Performance Optimization

Preconnect to Checkout Host

Add DNS prefetch and preconnect hints to your HTML for faster loading:

<link rel="preconnect" href="https://buy.paypercut.io ">
<link rel="dns-prefetch" href="https://buy.paypercut.io ">

Lazy Loading

Load the SDK only when needed to reduce initial bundle size:

async function loadCheckout() {
  const { PaypercutCheckout } = await import('@paypercut/checkout-js');
  return PaypercutCheckout;
}

// Load when user clicks pay button
payButton.addEventListener('click', async () => {
  const PaypercutCheckout = await loadCheckout();
  const checkout = PaypercutCheckout({ id: 'CHK_12345' });
  checkout.render();
});

Best Practices

1. Always Verify Payments on Your Backend

Never rely solely on frontend events for payment confirmation. Always verify payments using webhooks on your backend:

// ✅ Good: Use frontend events for UI updates only
checkout.on('success', () => {
  // Show success message
  showSuccessMessage();
  // Redirect to order confirmation page
  window.location.href = '/orders/confirmation';
});

// ❌ Bad: Don't grant access based on frontend events alone
checkout.on('success', () => {
  // This can be manipulated by users!
  grantPremiumAccess(userId); // Don't do this!
});

2. Handle All Event Types

Always handle both success and error events:

checkout.on('success', () => {
  // Handle success
  showSuccessMessage();
});

checkout.on('error', () => {
  // Show user-friendly error message
  alert('Payment failed. Please try again.');
});

3. Clean Up on Component Unmount

Always call destroy() when your component unmounts to prevent memory leaks:

// React example
useEffect(() => {
  const checkout = PaypercutCheckout({ id: checkoutId });
  checkout.render();

  return () => {
    checkout.destroy(); // Clean up!
  };
}, []);

FAQ For Internal Validation

Q: How do I handle successful payments? Listen to the success event and redirect users or update your UI accordingly. Always verify the payment on your backend using webhooks.

Q: Can I use this with server-side rendering (SSR)? Yes, but ensure the SDK is only initialized on the client side. For Next.js, use dynamic imports with ssr: false.

Q: What happens if the user closes the browser during payment?

Q: Can I have multiple checkouts on one page? Maybe Yes, but only one should be active at a time to avoid user confusion. If no, we destroy the previous one and create a new one.

Q: How do I handle errors? Listen to the error event and display user-friendly error messages. Log errors for debugging.