embedpay

v3.0.9

Published

9 days ago

Universal browser-based payment SDK for embedding card and mobile money payments. Zero-dependency IIFE bundle that works with any website, CMS, or framework. Supports multiple payment providers including AlexPay, Vesicash, and Portal.

Downloads

964

0High
0Medium
0Low

vesicash-npm

EmbedPay

Complete browser-based payment SDK for EmbedPay. Zero-dependency IIFE bundle that works with any website or CMS.

Overview

embedpay is the standalone browser bundle of the EmbedPay SDK. It provides a complete payment solution that:

💳 Supports Multiple Payment Methods - Cards, Mobile Money
🔒 Built-in Security - Tamper detection and fraud prevention
🎨 Customizable - Style buttons to match your brand
🌐 Universal - Works with any website, CMS, or framework
📱 Mobile-First - Optimized for mobile payments
🧪 Mock Mode - Test without real transactions

Quick Start

CDN (Recommended)

Add to your HTML <head>:

<script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/embedpay.js"></script>

npm

npm install embedpay
# or
yarn add embedpay
# or
pnpm add embedpay

Basic Usage

1. Add the Script

<!DOCTYPE html>
<html>
<head>
  <script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/embedpay.js"></script>
</head>
<body>
  <!-- Your content -->
</body>
</html>

2. Configure the SDK

<script>
  // Global configuration (set before the SDK loads)
  window.EMBEDPAY = {
    key: 'pk_live_alexpay_xxxxxxxx',
    currency: 'GHS',
    narration: 'Order Payment',
    callback: 'https://yoursite.com/success',
    cancel: 'https://yoursite.com/cancel'
  };
</script>
<script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/embedpay.js"></script>

3. Add Payment Button

<!-- Fixed amount -->
<button data-checkout data-amount="5000">
  Pay GHS 50.00
</button>

<!-- Or read amount from page element -->
<span id="total">7500</span>
<button data-checkout data-amount-from="#total">
  Checkout
</button>

<!-- Or use JavaScript variable -->
<script>
  window.cartTotal = 10000;
</script>
<button data-checkout data-amount-var="cartTotal">
  Pay Now
</button>

Configuration Options

Global Configuration (window.EMBEDPAY)

| Option | Type | Required | Description | |--------|------|----------|-------------| | key | string | ✅ | Your publishable key from payment provider | | currency | string | ❌ | Currency code (GHS, NGN, USD, KES, ZAR) | | method | string | ❌ | Payment method: 'card' or 'mobile-money' | | narration | string | ❌ | Default payment description | | callback | string | ❌ | Success redirect URL | | cancel | string | ❌ | Cancel redirect URL | | forceMock | boolean | ❌ | Enable test mode (default: false) | | checkoutUrl | string | ❌ | Custom checkout page URL (for mock mode) |

Button Attributes

| Attribute | Description | Example | |-----------|-------------|---------| | data-checkout | Marks button as checkout trigger | <button data-checkout> | | data-amount | Fixed payment amount | data-amount="5000" | | data-amount-from | CSS selector for amount element | data-amount-from="#total" | | data-amount-var | JavaScript variable name | data-amount-var="cartTotal" | | data-currency | Override currency | data-currency="USD" | | data-narration | Override description | data-narration="Product #123" | | data-key | Use different publishable key | data-key="pk_test_..." | | data-force-mock | Enable mock mode per button | data-force-mock="true" |

Advanced Usage

WooCommerce Integration

<script>
  window.EMBEDPAY = {
    key: 'pk_live_alexpay_xxxxxxxx',
    currency: 'GHS',
    narration: 'WooCommerce Order',
    amountVar: 'EMBEDPAY_CART_TOTAL'  // Auto-sync with cart
  };
</script>

Custom Styling

/* Base button styles */
.embedpay-btn {
  background: #1a1714;
  color: #f5f2ee;
  padding: 12px 24px;
  border: none;
  border-radius: 8px;
  font-size: 16px;
  cursor: pointer;
  transition: background 0.15s;
}

.embedpay-btn:hover {
  background: #2d2926;
}

.embedpay-btn:disabled {
  opacity: 0.6;
  cursor: not-allowed;
}

Event Handling

// SDK exposes EmbedPay object globally
document.addEventListener('DOMContentLoaded', function() {
  // Refresh button bindings (if dynamically adding buttons)
  if (window.EmbedPay) {
    window.EmbedPay.refresh();
  }
});

Mock Mode (Testing)

Enable test mode to simulate payments without real transactions:

<script>
  window.EMBEDPAY = {
    key: 'pk_test_alexpay_xxxxxxxx',
    forceMock: true,
    checkoutUrl: 'https://yoursite.com/checkout.html'
  };
</script>

Test Cards:

✅ Success: 4084 0841 2345 6789, Exp: 12/28, CVV: 123
❌ Declined: 4000 0000 0000 0002, Exp: 12/28, CVV: 456

Test Mobile Money:

✅ Success: 0244 123 456, Network: MTN
❌ Declined: 0244 000 000, Network: MTN

Security Features

Tamper Detection

The SDK automatically monitors for:

🖥️ DevTools Detection - Blocks payments if developer tools are open
📐 Window Resize - Detects suspicious window resizing
💰 Amount Changes - Validates amount hasn't been manipulated

Domain Authorization

Your publishable key is restricted to specific domains. Configure allowed domains in your merchant dashboard.

CMS Integrations

WordPress

Install the EmbedPay WordPress Plugin for easy integration.

// Shortcode
[embedpay_button amount="5000"]Pay Now[/embedpay_button]

// With dynamic amount
[embedpay_button amount_from="#total"]Checkout[/embedpay_button]

Shopify

Add to your theme's checkout page:

<script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/embedpay.js"></script>
<script>
  window.EMBEDPAY = {
    key: 'pk_live_alexpay_xxxxxxxx',
    currency: '{{ shop.currency }}',
    narration: 'Order {{ order.name }}'
  };
</script>

Browser Support

✅ Chrome 80+
✅ Firefox 75+
✅ Safari 13+
✅ Edge 80+
✅ iOS Safari 13+
✅ Chrome Android 80+

File Size

Gzipped: ~4.2 KB
Minified: ~10 KB

Troubleshooting

"Payment service not authorized for this site"

Your domain is not authorized. Add your domain in the merchant dashboard.

"Invalid payment key"

Check that your publishable key is correct and matches the format: pk_live_alexpay_xxxxxxxx

"Payment amount is missing or zero"

Ensure the amount element exists and contains a valid number:

<span id="total">5000</span>  <!-- Must be just the number -->

"Initialising payment service…"

The SDK is still fetching configuration. Wait a moment and try again.

API Reference

The browser bundle exposes a global EmbedPay object:

interface EmbedPaySDK {
  refresh(): void;  // Re-scan for buttons and bind events
}

Related Packages

embedpay-core - Core functionality
embedpay-react - React hooks and components
embedpay-vue - Vue composables and components

License

MIT © Vesicash

Support

📧 Email: [email protected]
🌐 Website: https://vesicash.com/embedpay
📖 Documentation: https://docs.vesicash.com/embedpay

Accept payments anywhere with EmbedPay 🚀