@one-payments/web-components 1.1.27 → 1.1.29

package/docs/cdn-integration-guide.md

@@ -0,0 +1,980 @@
+# CDN Integration Guide
+
+## Overview
+
+This guide explains how to integrate the ONE Payments Drop-in Element on platforms that don't use npm or bundlers, such as **Shopify**, **Wix**, and **WordPress**.
+
+The `@one-payments/web-components` package provides a browser-ready IIFE bundle that can be loaded via a simple `<script>` tag:
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/@one-payments/web-components@1.1.28/dist/one-payment.browser.iife.js"></script>
+```
+
+This bundle:
+- Auto-registers the `<one-payment>` custom element
+- Exposes a global `window.OnePayments` API
+- Bundles all dependencies (no additional scripts needed)
+- Works without npm, bundlers, or build steps
+
+---
+
+## CRITICAL: orderId Must Be a UUID
+
+> **This is the most important requirement. Read this section carefully.**
+
+The backend **strictly validates** the `orderId` format. If `orderId` is not a valid UUID, the payment request **will fail**.
+
+### What is Required
+
+`orderId` must be a **pure UUID string** with no prefixes, suffixes, or additional data.
+
+**Correct format (UUID v4):**
+```
+550e8400-e29b-41d4-a716-446655440000
+```
+
+### Examples
+
+| Example | Valid? | Reason |
+|---------|--------|--------|
+| `550e8400-e29b-41d4-a716-446655440000` | ✅ Yes | Pure UUID |
+| `cart-550e8400-e29b-41d4-a716-446655440000` | ❌ No | Has prefix |
+| `550e8400-e29b-41d4-a716-446655440000__cartToken` | ❌ No | Has suffix |
+| `550e8400-e29b-41d4-a716-446655440000-12345` | ❌ No | Extra data appended |
+| `order-123` | ❌ No | Not a UUID |
+| `12345` | ❌ No | Not a UUID |
+| `{{ cart.token }}` (Shopify) | ❌ No | Cart token is not a UUID |
+
+### How to Generate a UUID
+
+Use the built-in browser API:
+
+```javascript
+const orderId = crypto.randomUUID();
+// Result: "550e8400-e29b-41d4-a716-446655440000"
+```
+
+`crypto.randomUUID()` is supported in all modern browsers (Chrome 92+, Firefox 95+, Safari 15.4+, Edge 92+).
+
+### Common Mistakes to Avoid
+
+| Mistake | Why It's Wrong |
+|---------|----------------|
+| Using Shopify `cart.token` as orderId | Cart token is not a UUID format |
+| Concatenating UUID with cart.token | Backend expects pure UUID only |
+| Using order numbers like `#1001` | Not a UUID format |
+| Reusing the same orderId for multiple payments | Each payment attempt needs a fresh UUID |
+
+---
+
+## General Usage Pattern
+
+This pattern works on **any platform** that supports `<script>` tags:
+
+```html
+<!-- 1. Load the CDN bundle -->
+<script src="https://cdn.jsdelivr.net/npm/@one-payments/web-components@1.1.28/dist/one-payment.browser.iife.js"></script>
+
+<!-- 2. Place the web component -->
+<one-payment id="one-payment-element"></one-payment>
+
+<!-- 3. Configure via JavaScript -->
+<script>
+  var el = document.getElementById('one-payment-element');
+
+  // Amount in minor units (e.g., cents)
+  // 5000 = $50.00 USD
+  el.amount = 5000;
+
+  // ISO 4217 currency code
+  el.currency = 'USD';
+
+  // ✅ CRITICAL: Generate a fresh UUID for each payment
+  el.orderId = crypto.randomUUID();
+
+  // Configuration
+  el.config = {
+    apiKey: 'pk_live_...',      // Your public API key
+    secretKey: 'sk_live_...',   // Your secret key
+    environment: 'prod'          // 'prod' or 'demo'
+  };
+
+  // Create browser adapters
+  el.adapters = OnePayments.createWebAdapters();
+
+  // Customer information
+  el.firstName = 'John';
+  el.lastName = 'Doe';
+  el.email = 'john@example.com';
+
+  // Handle successful payment
+  el.addEventListener('payment-success', function(event) {
+    console.log('Payment successful!', event.detail.paymentIntentId);
+    // Redirect to success page or update UI
+  });
+
+  // Handle payment error
+  el.addEventListener('payment-error', function(event) {
+    console.error('Payment failed:', event.detail.error);
+    // Show error message to user
+  });
+</script>
+```
+
+### Required Properties
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `amount` | Number | Amount in minor units (cents). Example: `5000` = $50.00 |
+| `currency` | String | ISO 4217 currency code. Example: `'USD'`, `'SGD'`, `'EUR'` |
+| `orderId` | String | **Must be a UUID.** Use `crypto.randomUUID()` |
+| `config` | Object | Contains `apiKey`, `secretKey`, `environment` |
+| `adapters` | Object | Use `OnePayments.createWebAdapters()` |
+
+### Optional Properties
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `firstName` | String | Customer's first name |
+| `lastName` | String | Customer's last name |
+| `email` | String | Customer's email address |
+
+### Events
+
+| Event | Description |
+|-------|-------------|
+| `payment-success` | Fired when payment completes successfully. `event.detail.paymentIntentId` contains the payment ID. |
+| `payment-error` | Fired when payment fails. `event.detail.error` contains error information. |
+| `state-change` | Fired when internal state changes. `event.detail.state` contains current state. |
+
+---
+
+## Shopify Integration
+
+This section explains how to integrate the ONE Payments Drop-in Element into a Shopify theme.
+
+### Where to Add the Code
+
+You can add this code to:
+- `sections/cart-template.liquid` - For cart page integration
+- `snippets/one-payments.liquid` - As a reusable snippet
+- `templates/cart.liquid` - For older themes
+
+### Understanding Shopify Data
+
+Shopify provides these Liquid variables:
+- `{{ cart.total_price }}` - Cart total in minor units (cents)
+- `{{ shop.currency }}` - Store currency code (e.g., "USD")
+- `{{ customer.first_name }}` - Customer's first name (if logged in)
+- `{{ customer.last_name }}` - Customer's last name (if logged in)
+- `{{ customer.email }}` - Customer's email (if logged in)
+
+> **Important:** Do NOT use `{{ cart.token }}` as orderId. Cart token is not a UUID.
+
+### Complete Shopify Example
+
+Create a new file `snippets/one-payments-dropin.liquid`:
+
+```liquid
+{% comment %}
+  ONE Payments Drop-in Element
+
+  Usage: {% render 'one-payments-dropin' %}
+
+  IMPORTANT: orderId must be a UUID generated via crypto.randomUUID()
+  Do NOT use cart.token as orderId - it will fail backend validation.
+{% endcomment %}
+
+<div id="one-payments-container" style="max-width: 500px; margin: 20px auto;">
+  <one-payment id="one-payment-element"></one-payment>
+</div>
+
+<!-- Load ONE Payments CDN Bundle -->
+<script src="https://cdn.jsdelivr.net/npm/@one-payments/web-components@1.1.28/dist/one-payment.browser.iife.js"></script>
+
+<script>
+  (function() {
+    // Wait for DOM to be ready
+    if (document.readyState === 'loading') {
+      document.addEventListener('DOMContentLoaded', initPayment);
+    } else {
+      initPayment();
+    }
+
+    function initPayment() {
+      var el = document.getElementById('one-payment-element');
+
+      if (!el) {
+        console.error('[ONE Payments] Payment element not found');
+        return;
+      }
+
+      // =====================================================
+      // AMOUNT & CURRENCY (from Shopify Liquid)
+      // =====================================================
+
+      // cart.total_price is in minor units (cents)
+      // Example: $50.00 = 5000
+      el.amount = {{ cart.total_price }};
+
+      // Shop currency (e.g., "USD", "SGD", "EUR")
+      el.currency = "{{ shop.currency }}";
+
+      // =====================================================
+      // ORDER ID - MUST BE A UUID
+      // =====================================================
+
+      // ✅ CORRECT: Generate a fresh UUID for each payment
+      el.orderId = crypto.randomUUID();
+
+      // ❌ WRONG: Do NOT use cart.token
+      // el.orderId = "{{ cart.token }}";  // This will FAIL!
+
+      // ❌ WRONG: Do NOT concatenate with other values
+      // el.orderId = crypto.randomUUID() + "__{{ cart.token }}";  // This will FAIL!
+
+      // =====================================================
+      // CONFIGURATION
+      // =====================================================
+
+      el.config = {
+        apiKey: 'pk_live_YOUR_API_KEY_HERE',
+        secretKey: 'sk_live_YOUR_SECRET_KEY_HERE',
+        environment: 'prod'  // Use 'demo' for testing
+      };
+
+      // Create browser adapters
+      el.adapters = OnePayments.createWebAdapters();
+
+      // =====================================================
+      // CUSTOMER INFORMATION (optional but recommended)
+      // =====================================================
+
+      {% if customer %}
+        // Logged-in customer - use their saved information
+        el.firstName = {{ customer.first_name | json }};
+        el.lastName = {{ customer.last_name | json }};
+        el.email = {{ customer.email | json }};
+      {% else %}
+        // Guest checkout - you may want to collect this via a form
+        // or leave empty and let the payment form collect it
+        el.firstName = '';
+        el.lastName = '';
+        el.email = '';
+      {% endif %}
+
+      // =====================================================
+      // EVENT HANDLERS
+      // =====================================================
+
+      // Handle successful payment
+      el.addEventListener('payment-success', function(event) {
+        console.log('[ONE Payments] Payment successful!');
+        console.log('Payment Intent ID:', event.detail.paymentIntentId);
+
+        // Option 1: Redirect to thank you page
+        // window.location.href = '/pages/thank-you';
+
+        // Option 2: Redirect to Shopify checkout to complete order
+        // window.location.href = '/checkout';
+
+        // Option 3: Show success message
+        alert('Payment successful! Order ID: ' + event.detail.paymentIntentId);
+      });
+
+      // Handle payment error
+      el.addEventListener('payment-error', function(event) {
+        console.error('[ONE Payments] Payment failed:', event.detail.error);
+        alert('Payment failed: ' + event.detail.error);
+      });
+
+      // Optional: Handle state changes for loading indicators
+      el.addEventListener('state-change', function(event) {
+        var state = event.detail.state;
+        console.log('[ONE Payments] State changed to:', state.status);
+
+        // You can show/hide loading indicators here
+        // if (state.status === 'processing') { showLoading(); }
+        // if (state.status === 'ready') { hideLoading(); }
+      });
+
+      console.log('[ONE Payments] Payment element initialized');
+      console.log('Amount:', el.amount, 'cents');
+      console.log('Currency:', el.currency);
+      console.log('Order ID:', el.orderId);
+    }
+  })();
+</script>
+```
+
+### Using the Snippet
+
+In your cart template (`sections/cart-template.liquid` or similar), add:
+
+```liquid
+{% render 'one-payments-dropin' %}
+```
+
+### Shopify-Specific Notes
+
+| Topic | Details |
+|-------|---------|
+| **Amount format** | `cart.total_price` is already in minor units (cents). No conversion needed. |
+| **Currency** | `shop.currency` gives the ISO code. Use it directly. |
+| **Customer data** | Use `{% if customer %}` to check if user is logged in. |
+| **Order ID** | Always use `crypto.randomUUID()`. Never use `cart.token`. |
+| **Checkout flow** | After payment success, you may redirect to Shopify checkout or a custom thank-you page. |
+
+### Testing on Shopify
+
+1. Use `environment: 'demo'` for testing
+2. Use demo API keys (not production keys)
+3. Check browser console for any errors
+4. Verify the payment element renders correctly
+5. Test with a demo card number
+
+---
+
+## Wix Integration
+
+This section explains how to integrate the ONE Payments Drop-in Element into a Wix site.
+
+### Integration Methods
+
+Wix offers two ways to add custom code:
+
+1. **HTML Embed** - Simple, no coding required beyond the snippet
+2. **Velo (Wix Code)** - More advanced, allows dynamic data
+
+### Method 1: HTML Embed (Simple)
+
+This is the easiest method for most Wix users.
+
+#### Step 1: Add an HTML Embed Element
+
+1. In Wix Editor, click **Add** (+)
+2. Select **Embed** > **Custom Embeds** > **Embed a Widget**
+3. Click **Enter Code**
+
+#### Step 2: Paste This Code
+
+```html
+<!DOCTYPE html>
+<html>
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <style>
+    * {
+      margin: 0;
+      padding: 0;
+      box-sizing: border-box;
+    }
+    body {
+      font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
+      padding: 20px;
+    }
+    #payment-container {
+      max-width: 100%;
+    }
+  </style>
+</head>
+<body>
+  <div id="payment-container">
+    <one-payment id="payment"></one-payment>
+  </div>
+
+  <!-- Load ONE Payments CDN Bundle -->
+  <script src="https://cdn.jsdelivr.net/npm/@one-payments/web-components@1.1.28/dist/one-payment.browser.iife.js"></script>
+
+  <script>
+    (function() {
+      var el = document.getElementById('payment');
+
+      if (!el) {
+        console.error('[ONE Payments] Payment element not found');
+        return;
+      }
+
+      // =====================================================
+      // AMOUNT & CURRENCY
+      // =====================================================
+
+      // Set your amount in minor units (cents)
+      // Example: $50.00 = 5000
+      el.amount = 5000;
+
+      // Set your currency
+      el.currency = 'USD';
+
+      // =====================================================
+      // ORDER ID - MUST BE A UUID
+      // =====================================================
+
+      // ✅ CORRECT: Generate a fresh UUID
+      el.orderId = crypto.randomUUID();
+
+      // =====================================================
+      // CONFIGURATION
+      // =====================================================
+
+      el.config = {
+        apiKey: 'pk_live_YOUR_API_KEY_HERE',
+        secretKey: 'sk_live_YOUR_SECRET_KEY_HERE',
+        environment: 'prod'  // Use 'demo' for testing
+      };
+
+      el.adapters = OnePayments.createWebAdapters();
+
+      // =====================================================
+      // CUSTOMER INFORMATION
+      // =====================================================
+
+      el.firstName = 'John';
+      el.lastName = 'Doe';
+      el.email = 'john@example.com';
+
+      // =====================================================
+      // EVENT HANDLERS
+      // =====================================================
+
+      // Handle successful payment
+      el.addEventListener('payment-success', function(event) {
+        console.log('Payment successful!', event.detail.paymentIntentId);
+
+        // Notify parent Wix page
+        window.parent.postMessage({
+          type: 'ONE_PAYMENT_SUCCESS',
+          paymentIntentId: event.detail.paymentIntentId
+        }, '*');
+      });
+
+      // Handle payment error
+      el.addEventListener('payment-error', function(event) {
+        console.error('Payment failed:', event.detail.error);
+
+        // Notify parent Wix page
+        window.parent.postMessage({
+          type: 'ONE_PAYMENT_ERROR',
+          error: event.detail.error
+        }, '*');
+      });
+
+      console.log('[ONE Payments] Initialized with Order ID:', el.orderId);
+    })();
+  </script>
+</body>
+</html>
+```
+
+#### Step 3: Resize the Embed
+
+- Set width to 100% or a fixed width like 500px
+- Set height to approximately 600px (adjust as needed)
+
+### Method 2: Velo (Advanced)
+
+If you need to pass dynamic data (like cart amount), use Velo page code.
+
+#### HTML Embed (with URL parameters)
+
+```html
+<!DOCTYPE html>
+<html>
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <style>
+    body { font-family: sans-serif; padding: 20px; margin: 0; }
+  </style>
+</head>
+<body>
+  <one-payment id="payment"></one-payment>
+
+  <script src="https://cdn.jsdelivr.net/npm/@one-payments/web-components@1.1.28/dist/one-payment.browser.iife.js"></script>
+
+  <script>
+    (function() {
+      var el = document.getElementById('payment');
+
+      // Parse URL parameters (passed from Velo code)
+      var params = new URLSearchParams(window.location.search);
+
+      // Get amount from URL param, default to 0
+      el.amount = parseInt(params.get('amount')) || 0;
+      el.currency = params.get('currency') || 'USD';
+
+      // ✅ Always generate a fresh UUID for orderId
+      el.orderId = crypto.randomUUID();
+
+      el.config = {
+        apiKey: params.get('apiKey') || 'pk_demo_...',
+        secretKey: params.get('secretKey') || 'sk_demo_...',
+        environment: params.get('env') || 'demo'
+      };
+
+      el.adapters = OnePayments.createWebAdapters();
+
+      el.firstName = params.get('firstName') || '';
+      el.lastName = params.get('lastName') || '';
+      el.email = params.get('email') || '';
+
+      el.addEventListener('payment-success', function(event) {
+        window.parent.postMessage({
+          type: 'ONE_PAYMENT_SUCCESS',
+          data: event.detail
+        }, '*');
+      });
+
+      el.addEventListener('payment-error', function(event) {
+        window.parent.postMessage({
+          type: 'ONE_PAYMENT_ERROR',
+          data: event.detail
+        }, '*');
+      });
+    })();
+  </script>
+</body>
+</html>
+```
+
+#### Velo Page Code
+
+```javascript
+// In your Wix page code (Velo)
+import wixLocation from 'wix-location';
+
+$w.onReady(function () {
+  // Listen for messages from the payment iframe
+  $w('#html1').onMessage((event) => {
+    const { type, data } = event.data;
+
+    if (type === 'ONE_PAYMENT_SUCCESS') {
+      console.log('Payment successful:', data.paymentIntentId);
+      // Redirect to thank you page
+      wixLocation.to('/thank-you');
+    }
+
+    if (type === 'ONE_PAYMENT_ERROR') {
+      console.error('Payment failed:', data.error);
+      // Show error message
+      $w('#errorText').text = 'Payment failed. Please try again.';
+      $w('#errorText').show();
+    }
+  });
+
+  // Optional: Pass dynamic data to the iframe
+  // $w('#html1').src = `https://your-hosted-html.com/payment.html?amount=${cartTotal}&currency=USD`;
+});
+```
+
+### Wix-Specific Notes
+
+| Topic | Details |
+|-------|---------|
+| **HTML Embed size** | Set height to ~600px to fit the payment form |
+| **Communication** | Use `postMessage` to communicate between iframe and Wix page |
+| **Dynamic data** | Pass amount/currency via URL params or postMessage |
+| **Order ID** | Always use `crypto.randomUUID()` inside the embed |
+| **Styling** | The embed runs in an iframe, so Wix styles won't affect it |
+
+---
+
+## WordPress Integration
+
+This section explains how to integrate the ONE Payments Drop-in Element into a WordPress site.
+
+### Integration Methods
+
+1. **Custom HTML Block** - For Gutenberg editor (WordPress 5.0+)
+2. **Shortcode** - For Classic editor or widgets
+3. **Theme template** - For theme developers
+
+### Method 1: Custom HTML Block (Gutenberg)
+
+This is the simplest method for most WordPress users.
+
+#### Step 1: Add a Custom HTML Block
+
+1. Edit your page/post in WordPress
+2. Click the **+** button to add a block
+3. Search for **"Custom HTML"**
+4. Add the Custom HTML block
+
+#### Step 2: Paste This Code
+
+```html
+<div id="one-payments-container" style="max-width: 500px; margin: 20px auto;">
+  <one-payment id="one-payment-element"></one-payment>
+</div>
+
+<!-- Load ONE Payments CDN Bundle -->
+<script src="https://cdn.jsdelivr.net/npm/@one-payments/web-components@1.1.28/dist/one-payment.browser.iife.js"></script>
+
+<script>
+  (function() {
+    // Wait for DOM ready
+    function initPayment() {
+      var el = document.getElementById('one-payment-element');
+
+      if (!el) {
+        console.error('[ONE Payments] Payment element not found');
+        return;
+      }
+
+      // =====================================================
+      // AMOUNT & CURRENCY
+      // =====================================================
+
+      // Set your amount in minor units (cents)
+      // Example: $75.00 = 7500
+      el.amount = 7500;
+
+      // Set your currency
+      el.currency = 'USD';
+
+      // =====================================================
+      // ORDER ID - MUST BE A UUID
+      // =====================================================
+
+      // ✅ CORRECT: Generate a fresh UUID
+      el.orderId = crypto.randomUUID();
+
+      // ❌ WRONG: Do NOT use WordPress post ID or other identifiers
+      // el.orderId = '12345';  // This will FAIL!
+
+      // =====================================================
+      // CONFIGURATION
+      // =====================================================
+
+      el.config = {
+        apiKey: 'pk_live_YOUR_API_KEY_HERE',
+        secretKey: 'sk_live_YOUR_SECRET_KEY_HERE',
+        environment: 'prod'  // Use 'demo' for testing
+      };
+
+      el.adapters = OnePayments.createWebAdapters();
+
+      // =====================================================
+      // CUSTOMER INFORMATION
+      // =====================================================
+
+      el.firstName = 'John';
+      el.lastName = 'Doe';
+      el.email = 'john@example.com';
+
+      // =====================================================
+      // EVENT HANDLERS
+      // =====================================================
+
+      el.addEventListener('payment-success', function(event) {
+        console.log('Payment successful!', event.detail.paymentIntentId);
+
+        // Option 1: Redirect to thank you page
+        // window.location.href = '/thank-you/';
+
+        // Option 2: Show success message
+        document.getElementById('one-payments-container').innerHTML =
+          '<div style="text-align: center; padding: 40px;">' +
+          '<h2 style="color: green;">Payment Successful!</h2>' +
+          '<p>Your payment ID: ' + event.detail.paymentIntentId + '</p>' +
+          '</div>';
+      });
+
+      el.addEventListener('payment-error', function(event) {
+        console.error('Payment failed:', event.detail.error);
+        alert('Payment failed: ' + event.detail.error);
+      });
+
+      console.log('[ONE Payments] Initialized');
+      console.log('Amount:', el.amount, 'cents');
+      console.log('Currency:', el.currency);
+      console.log('Order ID:', el.orderId);
+    }
+
+    // Initialize when DOM is ready
+    if (document.readyState === 'loading') {
+      document.addEventListener('DOMContentLoaded', initPayment);
+    } else {
+      initPayment();
+    }
+  })();
+</script>
+```
+
+### Method 2: WordPress Shortcode (Advanced)
+
+For more control, create a shortcode in your theme's `functions.php`:
+
+```php
+<?php
+// Add to your theme's functions.php
+
+function one_payments_shortcode($atts) {
+    // Parse shortcode attributes
+    $atts = shortcode_atts(array(
+        'amount' => '0',
+        'currency' => 'USD',
+    ), $atts);
+
+    // Generate unique element ID
+    $element_id = 'one-payment-' . uniqid();
+
+    ob_start();
+    ?>
+    <div id="<?php echo esc_attr($element_id); ?>-container" style="max-width: 500px; margin: 20px auto;">
+        <one-payment id="<?php echo esc_attr($element_id); ?>"></one-payment>
+    </div>
+
+    <script src="https://cdn.jsdelivr.net/npm/@one-payments/web-components@1.1.28/dist/one-payment.browser.iife.js"></script>
+
+    <script>
+    (function() {
+        function init() {
+            var el = document.getElementById('<?php echo esc_js($element_id); ?>');
+            if (!el) return;
+
+            el.amount = <?php echo intval($atts['amount']); ?>;
+            el.currency = '<?php echo esc_js($atts['currency']); ?>';
+
+            // ✅ Generate UUID for orderId
+            el.orderId = crypto.randomUUID();
+
+            el.config = {
+                apiKey: 'pk_live_YOUR_API_KEY_HERE',
+                secretKey: 'sk_live_YOUR_SECRET_KEY_HERE',
+                environment: 'prod'
+            };
+
+            el.adapters = OnePayments.createWebAdapters();
+
+            el.addEventListener('payment-success', function(event) {
+                console.log('Payment successful!', event.detail.paymentIntentId);
+            });
+
+            el.addEventListener('payment-error', function(event) {
+                console.error('Payment failed:', event.detail.error);
+            });
+        }
+
+        if (document.readyState === 'loading') {
+            document.addEventListener('DOMContentLoaded', init);
+        } else {
+            init();
+        }
+    })();
+    </script>
+    <?php
+    return ob_get_clean();
+}
+add_shortcode('one_payments', 'one_payments_shortcode');
+```
+
+#### Using the Shortcode
+
+```
+[one_payments amount="7500" currency="USD"]
+```
+
+### Method 3: WooCommerce Integration (Advanced)
+
+For WooCommerce stores, you can integrate with the checkout:
+
+```php
+<?php
+// Add to your theme's functions.php or a custom plugin
+
+add_action('woocommerce_review_order_after_payment', 'add_one_payments_to_checkout');
+
+function add_one_payments_to_checkout() {
+    ?>
+    <div id="one-payments-wc-container" style="margin: 20px 0;">
+        <h3>Pay with ONE Payments</h3>
+        <one-payment id="one-payment-wc"></one-payment>
+    </div>
+
+    <script src="https://cdn.jsdelivr.net/npm/@one-payments/web-components@1.1.28/dist/one-payment.browser.iife.js"></script>
+
+    <script>
+    jQuery(function($) {
+        var el = document.getElementById('one-payment-wc');
+        if (!el) return;
+
+        // Get cart total (WooCommerce stores in cents)
+        el.amount = <?php echo intval(WC()->cart->get_total('edit') * 100); ?>;
+        el.currency = '<?php echo get_woocommerce_currency(); ?>';
+
+        // ✅ Generate UUID for orderId
+        el.orderId = crypto.randomUUID();
+
+        el.config = {
+            apiKey: 'pk_live_YOUR_API_KEY_HERE',
+            secretKey: 'sk_live_YOUR_SECRET_KEY_HERE',
+            environment: 'prod'
+        };
+
+        el.adapters = OnePayments.createWebAdapters();
+
+        // Get customer data from checkout form
+        el.firstName = $('#billing_first_name').val() || '';
+        el.lastName = $('#billing_last_name').val() || '';
+        el.email = $('#billing_email').val() || '';
+
+        el.addEventListener('payment-success', function(event) {
+            console.log('Payment successful!', event.detail.paymentIntentId);
+            // Proceed with WooCommerce order completion
+        });
+    });
+    </script>
+    <?php
+}
+```
+
+### WordPress-Specific Notes
+
+| Topic | Details |
+|-------|---------|
+| **Gutenberg** | Use Custom HTML block for simple integration |
+| **Classic Editor** | Use shortcode method |
+| **WooCommerce** | Can integrate with checkout, but orderId must still be UUID |
+| **Order ID** | Always use `crypto.randomUUID()`. Never use WordPress post IDs. |
+| **Amount format** | Convert to minor units (cents). $75.00 = 7500 |
+
+---
+
+## Troubleshooting
+
+### Common Errors
+
+#### "Invalid orderId format"
+
+**Cause:** The `orderId` is not a valid UUID.
+
+**Solution:** Use `crypto.randomUUID()` to generate a proper UUID:
+
+```javascript
+el.orderId = crypto.randomUUID();
+```
+
+**Do NOT use:**
+- Shopify `cart.token`
+- WordPress post IDs
+- Order numbers like `#1001`
+- Any string that isn't a UUID
+
+#### "Payment element not found"
+
+**Cause:** JavaScript runs before the element is in the DOM.
+
+**Solution:** Wrap your code in a DOM ready check:
+
+```javascript
+if (document.readyState === 'loading') {
+  document.addEventListener('DOMContentLoaded', initPayment);
+} else {
+  initPayment();
+}
+```
+
+#### "OnePayments is not defined"
+
+**Cause:** The CDN script hasn't loaded yet.
+
+**Solution:** Make sure the `<script src="...">` tag comes BEFORE your configuration script:
+
+```html
+<!-- 1. Load the bundle FIRST -->
+<script src="https://cdn.jsdelivr.net/npm/@one-payments/web-components@1.1.28/dist/one-payment.browser.iife.js"></script>
+
+<!-- 2. THEN configure -->
+<script>
+  // Your configuration code
+</script>
+```
+
+#### Element not rendering
+
+**Possible causes:**
+1. Missing required properties (`amount`, `currency`, `orderId`, `config`, `adapters`)
+2. Invalid `config` object
+3. CSS hiding the element
+
+**Solution:** Check browser console for errors and verify all required properties are set.
+
+---
+
+## Security Considerations
+
+### API Keys in Client-Side Code
+
+The current integration pattern includes `secretKey` in client-side code. This is acceptable for the current use case but be aware:
+
+- Keep your production keys secure
+- Use `environment: 'demo'` for testing
+- Consider using a backend proxy for additional security in the future
+
+### Content Security Policy (CSP)
+
+If your site uses CSP, ensure these are allowed:
+
+- Scripts from `cdn.jsdelivr.net` (or `unpkg.com`)
+- Inline scripts (or use nonce/hash)
+
+---
+
+## API Reference
+
+### Global Object: `window.OnePayments`
+
+| Property/Method | Description |
+|-----------------|-------------|
+| `createWebAdapters()` | Creates adapters for browser environment. Required. |
+| `VERSION` | Current package version (e.g., "1.1.28") |
+| `TAG_NAME` | Custom element tag name ("one-payment") |
+| `isRegistered()` | Returns `true` if element is registered |
+| `whenDefined()` | Promise that resolves when element is ready |
+
+### Element Properties
+
+| Property | Type | Required | Description |
+|----------|------|----------|-------------|
+| `amount` | Number | Yes | Amount in minor units (cents) |
+| `currency` | String | Yes | ISO 4217 currency code |
+| `orderId` | String | Yes | **Must be a UUID** |
+| `config` | Object | Yes | `{ apiKey, secretKey, environment }` |
+| `adapters` | Object | Yes | From `OnePayments.createWebAdapters()` |
+| `firstName` | String | No | Customer first name |
+| `lastName` | String | No | Customer last name |
+| `email` | String | No | Customer email |
+
+### Element Events
+
+| Event | Detail | Description |
+|-------|--------|-------------|
+| `payment-success` | `{ paymentIntentId }` | Payment completed successfully |
+| `payment-error` | `{ error }` | Payment failed |
+| `state-change` | `{ state }` | Internal state changed |
+
+---
+
+## Version History
+
+| Version | Changes |
+|---------|---------|
+| 1.1.28 | Fixed VERSION constant replacement in browser bundle |
+| 1.1.27 | Initial CDN/IIFE bundle release |
+
+---
+
+## Notes for Existing Users
+
+This documentation describes how to use the CDN bundle for platforms without bundlers.
+
+**This does NOT change:**
+- `src/index.ts` - ESM entry point (unchanged)
+- `src/one-payment.ts` - Component implementation (unchanged)
+- React/Vue/Angular/React-Native wrappers (unchanged)
+- `@one-payments/core` (unchanged)
+- `@one-payments/adapters-*` (unchanged)
+
+Existing ESM-based integrations (React, Vue, Angular) continue to work exactly as before.