wedge-pay-web

Wedge Pay Web SDK v1.0.0

A simple vanilla TypeScript SDK for hosting web applications with callback support. This SDK provides a modal interface that can communicate with embedded web applications through postMessage events.

Features

• 🎯 Simple Integration: Easy-to-use TypeScript SDK with clear callback interfaces
• 🖼️ Modal Interface: Responsive wrapper with shadow and rounded borders
• 📡 Event Communication: Bidirectional communication with embedded webapps
• 🎯 Webapp-Controlled: Webapp handles its own exit functionality
• 🎨 Customizable: Custom CSS classes and styling options
• 📱 Modern Design: Clean modal appearance with subtle shadows and rounded corners

Installation

npm install wedge-pay-web

Quick Start

import { WedgePaySDK } from 'wedge-pay-web';

const sdk = new WedgePaySDK({
  token: 'your-onboarding-token',
  env: 'sandbox',
  type: 'onboarding',
  onEvent: (event) => {
    console.log('Event:', event);
  },
  onSuccess: (customerId) => {
    console.log('Success:', customerId);
  },
   onClose: (reason) => {
    console.log('Closed:', reason);
  },
  onError: (error) => {
    console.error('Error:', error);
  },
  onLoad: (url) => {
    console.log('Loaded:', url);
  },
});

// Open the modal
sdk.open();

Configuration

Required Parameters

• token: Your onboarding token (string)
• env: Environment to use - 'sandbox' or 'production'
• type: Flow type - 'onboarding' or 'funding'

Required Callbacks

All callbacks are required and must be provided:

• onSuccess: Triggered when webapp sends onSuccess event with customer ID
• onError: Triggered when webapp sends onError event or loading fails (auto-calls onClose)
• onClose: Triggered when webapp sends onClose event or user cancels
• onEvent: Triggered when webapp sends onEvent event for general events
• onLoad: Triggered when webapp finishes loading (sends iOSReady to webapp)

Environment URLs

The SDK automatically constructs URLs based on your environment:

• Sandbox: https://onboarding-sandbox.wedge-can.com
• Production: https://onboarding-production.wedge-can.com

Examples

// Onboarding flow
const sdk = new WedgePaySDK({
  token: 'abc123',
  env: 'sandbox',
  type: 'onboarding',
  // ... callbacks
});

// Funding flow  
const sdk = new WedgePaySDK({
  token: 'abc123',
  env: 'sandbox',
  type: 'funding',
  // ... callbacks
});

// Production environment
const sdk = new WedgePaySDK({
  token: 'prod-token-123',
  env: 'production',
  type: 'onboarding',
  // ... callbacks
});

Webapp Communication

Your webapp should send messages to the parent window using postMessage. The SDK supports multiple message formats:

Standard Format (Recommended)

// Success event
window.parent.postMessage({
  event: 'onSuccess', // or type: 'SUCCESS'
  data: 'customer-123'
}, '*');

// Error event
window.parent.postMessage({
  event: 'onError', // or type: 'ERROR'
  data: { message: 'Something went wrong' }
}, '*');

// Close event
window.parent.postMessage({
  event: 'onClose', // or type: 'EXIT' or type: 'CLOSE'
  data: 'user_cancelled'
}, '*');

// General event
window.parent.postMessage({
  event: 'onEvent', // or type: 'EVENT'
  data: { type: 'progress', step: 2 }
}, '*');

Direct Callback Format

// Success event
window.parent.postMessage({
  onSuccess: 'customer-123'
}, '*');

// Error event
window.parent.postMessage({
  onError: { message: 'Something went wrong' }
}, '*');

// Close event
window.parent.postMessage({
  onClose: 'user_cancelled'
}, '*');

// General event
window.parent.postMessage({
  onEvent: { type: 'progress', step: 2 }
}, '*');

String Format

// Simple string messages
window.parent.postMessage('onClose', '*');
window.parent.postMessage('onSuccess', '*');

API Reference

WedgePaySDK

Constructor

new WedgePaySDK(config: WedgePaySDKConfig)

Methods

• open(): Opens the modal and loads the webapp
• close(reason?: any): Closes the modal with optional reason
• getIsOpen(): Returns current open state

Types

interface WedgePaySDKConfig {
  token: string;
  env: 'sandbox' | 'production';
  type: 'onboarding' | 'funding';
  onSuccess: (customerId: string) => void;
  onError: (error: any) => void;
  onClose: (reason: any) => void;
  onEvent: (event: any) => void;
  onLoad: (url: string) => void;
}

Examples

React Example

See examples/react-example.tsx for a complete React implementation.

Vanilla JavaScript Example

See examples/vanilla-example.html for a vanilla JavaScript implementation.

Development

# Install dependencies
npm install

# Build the SDK
npm run build

# Watch mode for development
npm run dev

# Clean build directory
npm run clean

Browser Support

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

License

MIT