@one-payments/web-components 1.1.31 → 1.2.0

package/docs/wix-checkout-integration-analysis.md

@@ -0,0 +1,695 @@
+# Wix Checkout Integration Analysis for One Payments Drop-in Element
+
+## Executive Summary
+
+**Can you integrate a custom Drop-in payment element into Wix websites?**
+
+| Scenario | Feasibility | Requirements |
+|----------|-------------|--------------|
+| Individual Site (Velo) | **YES - POSSIBLE** | Premium plan, Velo coding, hosted payment page |
+| Wix App Market (All Sites) | **POSSIBLE** | PSP onboarding with Wix, REST API implementation |
+| Direct Checkout Embed | **LIMITED** | Redirect flow required, no direct embed in native checkout |
+
+**Bottom Line**: Wix is **significantly more flexible** than Shopify for custom payment integration. Individual site owners can integrate custom payment providers using Velo, and payment service providers can apply to offer services across all Wix sites through the PSP program.
+
+---
+
+## Table of Contents
+
+1. [Wix Payment Architecture Overview](#1-wix-payment-architecture-overview)
+2. [Integration Option 1: Velo Service Plugin (Individual Sites)](#2-integration-option-1-velo-service-plugin-individual-sites)
+3. [Integration Option 2: REST PSP Plugin (App Market)](#3-integration-option-2-rest-psp-plugin-app-market)
+4. [Technical Implementation Details](#4-technical-implementation-details)
+5. [Comparison: Wix vs Shopify](#5-comparison-wix-vs-shopify)
+6. [Feasibility for One Payments Drop-in](#6-feasibility-for-one-payments-drop-in)
+7. [Recommended Integration Approach](#7-recommended-integration-approach)
+8. [Implementation Guide](#8-implementation-guide)
+9. [Conclusion & Next Steps](#9-conclusion--next-steps)
+
+---
+
+## 1. Wix Payment Architecture Overview
+
+### How Wix Payments Work
+
+Unlike Shopify's locked-down checkout, Wix provides **two pathways** for custom payment integration:
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                     WIX PAYMENT OPTIONS                          │
+├─────────────────────────────────────────────────────────────────┤
+│                                                                  │
+│  ┌─────────────────────┐      ┌─────────────────────────────┐  │
+│  │   VELO SERVICE      │      │   REST PSP PLUGIN           │  │
+│  │   PLUGIN            │      │   (App Market)              │  │
+│  │                     │      │                             │  │
+│  │ • For own sites     │      │ • For all Wix sites         │  │
+│  │ • No approval needed│      │ • Requires Wix onboarding   │  │
+│  │ • Hosted page flow  │      │ • Full PSP integration      │  │
+│  │ • Custom code       │      │ • Official payment option   │  │
+│  └─────────────────────┘      └─────────────────────────────┘  │
+│                                                                  │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+### Supported Payment Methods
+
+Wix's infrastructure supports:
+- Credit/Debit Cards (with 3DS2/PSD2 compliance)
+- Digital Wallets (Apple Pay, Google Pay, etc.)
+- Buy Now Pay Later (Klarna, Afterpay, etc.)
+- Bank Transfers
+- Cryptocurrency
+- Local Payment Methods
+- **Hosted Payment Pages** ← Key for Drop-in integration
+
+### Plan Requirements
+
+| Feature | Free Plan | Premium Plans |
+|---------|-----------|---------------|
+| Accept Payments | ❌ | ✅ |
+| Custom Payment Provider (Velo) | ❌ | ✅ |
+| Multiple Payment Methods | ❌ | ✅ |
+| eCommerce Checkout | ❌ | ✅ Business/eCommerce |
+
+---
+
+## 2. Integration Option 1: Velo Service Plugin (Individual Sites)
+
+### Overview
+
+The **Payment Provider Service Plugin** allows Wix site owners to integrate **any payment provider** with their own sites using Velo (Wix's development platform).
+
+### Key Characteristics
+
+| Aspect | Details |
+|--------|---------|
+| **Availability** | Any Wix Premium site with Velo enabled |
+| **Approval Required** | ❌ No Wix approval needed |
+| **App Market** | ❌ Cannot be published to App Market |
+| **Scope** | Own sites only |
+| **Payment Flow** | Hosted page (redirect) |
+| **Development** | JavaScript/Velo code |
+
+### How It Works
+
+```
+Customer Journey with Velo Plugin:
+
+┌──────────┐    ┌──────────┐    ┌───────────────────┐    ┌──────────┐
+│   Wix    │ -> │ Checkout │ -> │  One Payments     │ -> │  Order   │
+│  Store   │    │  Page    │    │  Hosted Page      │    │ Complete │
+└──────────┘    └──────────┘    │  (with Drop-in)   │    └──────────┘
+                                └───────────────────┘
+                                        │
+                                        ▼
+                                ┌───────────────────┐
+                                │  Webhook to Wix   │
+                                │  (submitEvent)    │
+                                └───────────────────┘
+```
+
+### Required Implementation Files
+
+#### 1. Configuration File (`payment-provider-config.js`)
+
+```javascript
+// payment-provider-config.js
+export function getConfig() {
+  return {
+    title: "One Payments",
+
+    paymentMethods: [
+      {
+        hostedPage: {
+          // Billing address fields required
+          billingAddressMandatoryFields: [
+            "EMAIL",
+            "FIRST_NAME",
+            "LAST_NAME",
+            "COUNTRY",
+            "ZIP_CODE"
+          ]
+        }
+      }
+    ],
+
+    credentialsFields: [
+      {
+        simpleField: {
+          name: "apiKey",
+          label: "One Payments API Key"
+        }
+      },
+      {
+        simpleField: {
+          name: "merchantId",
+          label: "Merchant ID"
+        }
+      },
+      {
+        dropdownField: {
+          name: "environment",
+          label: "Environment",
+          options: [
+            { value: "prod", label: "Production" },
+            { value: "demo", label: "Demo/Sandbox" }
+          ]
+        }
+      }
+    ]
+  };
+}
+```
+
+#### 2. Plugin Implementation (`payment-provider.js`)
+
+```javascript
+// payment-provider.js
+import { fetch } from 'wix-fetch';
+
+// Called when merchant connects their account
+export async function connectAccount(options) {
+  const { credentials, country, currency } = options;
+
+  try {
+    // Validate credentials with One Payments API
+    const response = await fetch('https://public.prod.one.ooo/validate-credentials', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        apiKey: credentials.apiKey,
+        merchantId: credentials.merchantId
+      })
+    });
+
+    if (response.ok) {
+      return {
+        credentials: {
+          apiKey: credentials.apiKey,
+          merchantId: credentials.merchantId,
+          environment: credentials.environment
+        },
+        accountId: credentials.merchantId,
+        accountName: "One Payments Account"
+      };
+    } else {
+      return {
+        errorCode: -1,
+        errorMessage: "Invalid credentials"
+      };
+    }
+  } catch (error) {
+    return {
+      errorCode: -1,
+      errorMessage: error.message
+    };
+  }
+}
+
+// Called at checkout to create transaction
+export async function createTransaction(options) {
+  const {
+    wixTransactionId,
+    merchantCredentials,
+    order,
+    paymentMethod
+  } = options;
+
+  // Generate unique transaction ID
+  const pluginTransactionId = `one_${wixTransactionId}_${Date.now()}`;
+
+  // Build redirect URL to hosted payment page
+  const baseUrl = merchantCredentials.environment === 'prod'
+    ? 'https://checkout.one.ooo'
+    : 'https://checkout.demo.one.ooo';
+
+  const params = new URLSearchParams({
+    orderId: pluginTransactionId,
+    amount: order.description.totalAmount,
+    currency: order.description.currency,
+    merchantId: merchantCredentials.merchantId,
+    returnUrl: order.returnUrls.successUrl,
+    cancelUrl: order.returnUrls.cancelUrl,
+    webhookUrl: order.returnUrls.pendingUrl, // Use for webhook
+    customerEmail: order.description.billingAddress?.email,
+    customerName: `${order.description.billingAddress?.firstName} ${order.description.billingAddress?.lastName}`
+  });
+
+  return {
+    pluginTransactionId,
+    redirectUrl: `${baseUrl}/pay?${params.toString()}`
+  };
+}
+
+// Called for refunds
+export async function refundTransaction(options) {
+  const {
+    pluginTransactionId,
+    merchantCredentials,
+    refundAmount
+  } = options;
+
+  try {
+    const response = await fetch('https://public.prod.one.ooo/refund', {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'Authorization': `Bearer ${merchantCredentials.apiKey}`
+      },
+      body: JSON.stringify({
+        transactionId: pluginTransactionId,
+        amount: refundAmount
+      })
+    });
+
+    const result = await response.json();
+
+    return {
+      pluginRefundId: result.refundId
+    };
+  } catch (error) {
+    return {
+      errorCode: -1,
+      errorMessage: error.message
+    };
+  }
+}
+```
+
+#### 3. Webhook Handler (`http-functions.js`)
+
+```javascript
+// backend/http-functions.js
+import { ok, badRequest } from 'wix-http-functions';
+import { paymentProvider } from 'wix-payment-provider-backend';
+
+// Webhook endpoint: https://[your-site]/_functions/onePaymentsWebhook
+export async function post_onePaymentsWebhook(request) {
+  try {
+    const body = await request.body.json();
+
+    const {
+      transactionId,
+      status,
+      wixTransactionId
+    } = body;
+
+    // Map One Payments status to Wix status
+    const eventType = status === 'completed'
+      ? 'Approved'
+      : status === 'failed'
+        ? 'Declined'
+        : 'Pending';
+
+    // Notify Wix about the transaction status
+    await paymentProvider.submitEvent({
+      event: {
+        transaction: {
+          wixTransactionId,
+          pluginTransactionId: transactionId,
+          eventType
+        }
+      }
+    });
+
+    return ok({ received: true });
+  } catch (error) {
+    return badRequest({ error: error.message });
+  }
+}
+```
+
+### Advantages of Velo Approach
+
+| Advantage | Description |
+|-----------|-------------|
+| **No Approval Needed** | Site owners can implement immediately |
+| **Full Control** | Complete customization of payment flow |
+| **Hosted Page Support** | Perfect for Drop-in integration |
+| **Quick Implementation** | Days/weeks, not months |
+| **Direct Integration** | No middleman required |
+
+### Limitations
+
+| Limitation | Impact |
+|------------|--------|
+| **Own Sites Only** | Cannot distribute to other Wix users |
+| **Requires Coding** | Site owner needs Velo knowledge |
+| **Premium Required** | Need paid Wix plan |
+| **Hosted Page Only** | Cannot embed directly in Wix checkout |
+
+---
+
+## 3. Integration Option 2: REST PSP Plugin (App Market)
+
+### Overview
+
+For payment service providers who want to offer their services to **all Wix merchants**, there's the REST Payment Service Provider plugin program.
+
+### Requirements
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│           PSP ONBOARDING REQUIREMENTS                        │
+├─────────────────────────────────────────────────────────────┤
+│                                                              │
+│ 1. Fill out application form at:                            │
+│    https://www.wix-providerplatform.com/                    │
+│                                                              │
+│ 2. Complete business development onboarding                  │
+│                                                              │
+│ 3. Implement required REST endpoints:                        │
+│    • Connect Account                                         │
+│    • Create Transaction                                      │
+│    • Refund Transaction                                      │
+│    • (Optional) Capture Transaction                          │
+│    • (Optional) Void Transaction                             │
+│                                                              │
+│ 4. Implement webhook handling (Submit Event API)             │
+│                                                              │
+│ 5. Support PSD2/3DS2 compliance                             │
+│                                                              │
+│ 6. Create Wix App in App Dashboard                          │
+│                                                              │
+│ 7. Pass Wix review and testing                              │
+│                                                              │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### Required Endpoints
+
+| Endpoint | Purpose | When Called |
+|----------|---------|-------------|
+| **Connect Account** | Merchant onboarding | Merchant connects provider |
+| **Create Transaction** | Process payment | Buyer initiates payment |
+| **Refund Transaction** | Process refund | Merchant initiates refund |
+| **Capture Transaction** | Capture authorized payment | Optional: Auth-capture flow |
+| **Void Transaction** | Cancel authorization | Optional: Void payment |
+
+### Webhook Events
+
+PSPs must send webhooks to Wix using the Submit Event API to notify about:
+- Transaction approval/decline
+- Refund completion/failure
+- Chargeback notifications
+- Status updates
+
+### Supported Features
+
+| Feature | Support |
+|---------|---------|
+| Credit Cards | ✅ Full support |
+| 3DS2/PSD2 | ✅ Required for cards |
+| Alternative Payments | ✅ Supported |
+| Multi-currency | ✅ Supported |
+| Auth-Capture | ✅ Optional |
+| Refunds | ✅ Required |
+| Partial Refunds | ✅ Supported |
+
+### Timeline & Process
+
+```
+Week 1-2:    Submit application at wix-providerplatform.com
+Week 2-4:    Business development discussions
+Week 4-8:    Technical integration development
+Week 8-10:   Testing and validation
+Week 10-12:  Wix review and approval
+Week 12+:    Launch in Wix App Market
+```
+
+---
+
+## 4. Technical Implementation Details
+
+### Hosted Payment Page Flow
+
+This is the recommended flow for One Payments Drop-in integration:
+
+```
+┌──────────────────────────────────────────────────────────────────┐
+│                    HOSTED PAGE PAYMENT FLOW                       │
+└──────────────────────────────────────────────────────────────────┘
+
+Step 1: Customer clicks "Pay" on Wix checkout
+        │
+        ▼
+Step 2: Wix calls createTransaction()
+        │
+        ▼
+Step 3: Your code returns { redirectUrl: "https://checkout.one.ooo/pay?..." }
+        │
+        ▼
+Step 4: Customer is redirected to hosted payment page
+        │
+        ▼
+Step 5: Customer sees One Payments Drop-in element
+        │
+        ▼
+Step 6: Customer completes payment
+        │
+        ▼
+Step 7: One Payments sends webhook to Wix (submitEvent)
+        │
+        ▼
+Step 8: Customer is redirected back to Wix success page
+        │
+        ▼
+Step 9: Order is marked as paid in Wix dashboard
+```
+
+### Hosted Payment Page Implementation
+
+You'll need to create a hosted checkout page that includes the Drop-in:
+
+```html
+<!-- checkout.one.ooo/pay -->
+<!DOCTYPE html>
+<html>
+<head>
+  <title>Complete Your Payment</title>
+  <script src="https://cdn.jsdelivr.net/npm/@one-payments/web-components@latest/dist/one-payment.browser.iife.js"></script>
+</head>
+<body>
+  <div class="checkout-container">
+    <h1>Complete Your Payment</h1>
+
+    <one-payment
+      id="payment-element"
+      amount=""
+      currency=""
+      order-id=""
+      first-name=""
+      last-name=""
+      email="">
+    </one-payment>
+  </div>
+
+  <script>
+    // Parse URL parameters
+    const params = new URLSearchParams(window.location.search);
+
+    // Configure element
+    const element = document.getElementById('payment-element');
+    element.amount = params.get('amount');
+    element.currency = params.get('currency');
+    element.orderId = params.get('orderId');
+    element.firstName = params.get('customerName')?.split(' ')[0] || '';
+    element.lastName = params.get('customerName')?.split(' ').slice(1).join(' ') || '';
+    element.email = params.get('customerEmail');
+
+    // Configure adapters and config
+    element.adapters = OnePayments.createWebAdapters();
+    element.config = {
+      apiKey: 'YOUR_API_KEY',
+      environment: 'prod'
+    };
+
+    // Handle payment completion
+    element.addEventListener('payment-success', async (e) => {
+      // Send webhook to Wix
+      await fetch(params.get('webhookUrl'), {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+          transactionId: params.get('orderId'),
+          status: 'completed',
+          wixTransactionId: params.get('wixTransactionId')
+        })
+      });
+
+      // Redirect to success page
+      window.location.href = params.get('returnUrl');
+    });
+
+    element.addEventListener('payment-error', () => {
+      window.location.href = params.get('cancelUrl');
+    });
+  </script>
+</body>
+</html>
+```
+
+---
+
+## 5. Comparison: Wix vs Shopify
+
+| Aspect | Wix | Shopify |
+|--------|-----|---------|
+| **Individual Site Integration** | ✅ Possible via Velo | ❌ Not possible |
+| **Approval Required (Own Site)** | ❌ No | N/A |
+| **Custom Payment Provider** | ✅ Yes (Velo plugin) | ❌ Only via Partner Program |
+| **Hosted Page Support** | ✅ Yes | ❌ Sandboxed |
+| **App Market Distribution** | ✅ Via PSP program | ✅ Via Partner Program |
+| **Time to First Integration** | Days/Weeks | Months |
+| **Coding Required** | ✅ Velo/JavaScript | ✅ Shopify-specific |
+| **Direct Checkout Embed** | ❌ Redirect only | ❌ Sandboxed only |
+| **Plan Requirements** | Premium | Plus ($2000+/mo) for extensions |
+
+### Key Difference
+
+> **Wix allows individual site owners to add custom payment providers themselves.**
+>
+> Shopify requires becoming an approved Payments Partner, which takes months and has strict requirements.
+
+---
+
+## 6. Feasibility for One Payments Drop-in
+
+### Can It Be Done?
+
+| Integration Type | Feasible? | Effort |
+|-----------------|-----------|--------|
+| Velo Plugin (hosted page redirect) | ✅ **YES** | Medium |
+| Direct embed in Wix checkout | ❌ No | N/A |
+| App Market PSP integration | ✅ **YES** | High |
+| Wix Stores native checkout | ❌ Redirect only | N/A |
+
+### Recommended Approach
+
+**For immediate integration**: Use the Velo Service Plugin with a hosted payment page containing the Drop-in element.
+
+**For broad distribution**: Apply to Wix's PSP program to offer One Payments in the Wix App Market.
+
+---
+
+## 7. Recommended Integration Approach
+
+### Phase 1: Hosted Payment Page (Immediate)
+
+Create a hosted checkout page at `checkout.one.ooo` (or similar) that:
+
+1. Receives order details via URL parameters
+2. Displays the One Payments Drop-in
+3. Processes payment
+4. Sends webhook to Wix
+5. Redirects customer back to Wix
+
+**Timeline**: 1-2 weeks
+
+### Phase 2: Velo Plugin Template (Short-term)
+
+Create a ready-to-use Velo plugin template that Wix merchants can:
+
+1. Copy into their Wix site
+2. Configure with their One Payments credentials
+3. Immediately accept payments
+
+**Timeline**: 2-4 weeks
+
+### Phase 3: Wix App Market (Long-term)
+
+Apply to Wix's PSP program to:
+
+1. Offer One Payments as official payment option
+2. Appear in Wix payment provider list
+3. Enable one-click setup for merchants
+
+**Timeline**: 2-4 months
+
+---
+
+## 8. Implementation Guide
+
+### For Wix Merchants
+
+#### Step 1: Set Up Hosted Payment Page
+
+Contact One Payments to get access to the hosted checkout page, or host your own using the template above.
+
+#### Step 2: Create Velo Service Plugin
+
+1. Open your Wix site in the Editor
+2. Enable Developer Mode (Dev Mode toggle)
+3. Go to Code Files → Service Plugins
+4. Add new Payment Provider plugin
+5. Copy the configuration and plugin code from section 2
+
+#### Step 3: Deploy and Test
+
+1. Publish your site
+2. Go to Dashboard → Accept Payments
+3. Find and connect "One Payments"
+4. Enter your API credentials
+5. Test with a small transaction
+
+### For One Payments Team
+
+#### Immediate Actions
+
+1. **Create hosted checkout page** at `checkout.one.ooo/pay`
+2. **Document the integration** for Wix merchants
+3. **Create Velo plugin template** (copy-paste ready)
+4. **Set up webhook endpoints** to handle Wix callbacks
+
+#### Long-term Actions
+
+1. **Apply to Wix PSP program** at https://www.wix-providerplatform.com/
+2. **Implement REST endpoints** per Wix specifications
+3. **Complete Wix onboarding** process
+4. **Launch in App Market**
+
+---
+
+## 9. Conclusion & Next Steps
+
+### Summary
+
+| Question | Answer |
+|----------|--------|
+| Can we integrate with Wix? | **YES** |
+| Can individual merchants do it? | **YES** (via Velo) |
+| Is it easier than Shopify? | **YES** (significantly) |
+| Can we use the Drop-in? | **YES** (via hosted page) |
+| Can we reach all Wix users? | **YES** (via PSP program) |
+
+### Immediate Next Steps
+
+1. **Create hosted payment page** for Wix redirect flow
+2. **Write Velo plugin template** for easy merchant setup
+3. **Document the integration process** for merchants
+4. **Apply to Wix PSP program** for App Market presence
+
+### Key Advantages of Wix Integration
+
+1. **No approval needed** for individual site integration
+2. **Faster time-to-market** than Shopify
+3. **Broader accessibility** (any Premium site can use it)
+4. **Clear path to App Market** via PSP program
+
+---
+
+## References & Sources
+
+- [Wix Payment Provider Service Plugin Tutorial](https://dev.wix.com/docs/develop-websites/articles/code-tutorials/wix-pay/tutorial-payment-provider-service-plugin)
+- [Connecting Payment Providers - Wix Help](https://support.wix.com/en/article/connecting-a-payment-provider)
+- [PSP Service Plugin Introduction](https://dev.wix.com/docs/api-reference/business-management/payments/service-plugins/payment-service-provider-service-plugin/introduction)
+- [Wix Provider Platform Application](https://www.wix-providerplatform.com/)
+- [Wix Velo Service Plugins Overview](https://dev.wix.com/docs/velo/articles/api-overview/service-plugins-spis)
+- [eCommerce Payment Settings SPI](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/payments/payment-settings/payment-settings-integration-service-plugin/introduction)
+
+---
+
+*Document created: December 3, 2024*
+*Last updated: December 3, 2024*
+*Version: 1.0*