@one-payments/web-components 1.1.31 → 1.2.0

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

@@ -0,0 +1,496 @@
+# Shopify Checkout Integration Analysis for One Payments Drop-in Element
+
+## Executive Summary
+
+**Can you integrate a custom Drop-in payment element into Shopify's checkout page?**
+
+| Scenario | Feasibility | Requirements |
+|----------|-------------|--------------|
+| Regular Shopify Store | **NOT POSSIBLE** | N/A |
+| Shopify Plus Store (Merchant) | **Very Limited** | Plus plan ($2,000+/month) |
+| Shopify Payments Partner | **POSSIBLE** | Shopify Partner approval, extensive review process |
+| Headless Commerce (Custom Storefront) | **POSSIBLE** | Development expertise, Storefront API |
+
+**Bottom Line**: Integrating a custom payment Drop-in element directly into Shopify's native checkout is **extremely restricted** and requires either becoming an approved Shopify Payments Partner or building a completely headless storefront.
+
+---
+
+## Table of Contents
+
+1. [Shopify Checkout Architecture](#1-shopify-checkout-architecture)
+2. [Checkout Extensibility (Current System)](#2-checkout-extensibility-current-system)
+3. [checkout.liquid (Deprecated)](#3-checkoutliquid-deprecated)
+4. [Payment Extensions Program](#4-payment-extensions-program)
+5. [Technical Limitations & Restrictions](#5-technical-limitations--restrictions)
+6. [Integration Options Analysis](#6-integration-options-analysis)
+7. [Feasibility for One Payments Drop-in](#7-feasibility-for-one-payments-drop-in)
+8. [Alternative Approaches](#8-alternative-approaches)
+9. [Recommendations](#9-recommendations)
+
+---
+
+## 1. Shopify Checkout Architecture
+
+### Overview
+
+Shopify's checkout is a **highly controlled, PCI-compliant environment** that processes billions of dollars in transactions. Due to security, compliance, and user experience requirements, Shopify maintains strict control over what can be modified in the checkout flow.
+
+### Checkout Flow Stages
+
+```
+┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
+│   Information   │ -> │    Shipping     │ -> │    Payment      │ -> │   Thank You     │
+│     Step        │    │     Step        │    │     Step        │    │     Page        │
+└─────────────────┘    └─────────────────┘    └─────────────────┘    └─────────────────┘
+       │                      │                      │                      │
+       └──────────────────────┴──────────────────────┴──────────────────────┘
+                                      │
+                          Shopify Plus ONLY for
+                          UI Extension access
+```
+
+### Plan-Based Access Levels
+
+| Feature | Basic/Standard Plans | Shopify Plus ($2,000+/mo) |
+|---------|---------------------|---------------------------|
+| Checkout UI Extensions (Info/Shipping/Payment) | ❌ Not Available | ✅ Available |
+| Checkout UI Extensions (Thank You/Order Status) | ✅ Limited | ✅ Full Access |
+| Payment Method Customization | ❌ Credit cards locked | ✅ Full customization |
+| Custom Payment Extensions | ❌ Not Available | ⚠️ Requires Partner Approval |
+| checkout.liquid | ❌ Deprecated/Removed | ❌ Deprecated (Aug 2025) |
+
+---
+
+## 2. Checkout Extensibility (Current System)
+
+### What is Checkout Extensibility?
+
+Checkout Extensibility is Shopify's modern framework for customizing checkout. It replaces the deprecated `checkout.liquid` and provides a **sandboxed, secure environment** for extensions.
+
+### How It Works
+
+```javascript
+// Example: Checkout UI Extension (React/Preact)
+import { Banner, useExtensionCapability } from '@shopify/ui-extensions-react/checkout';
+
+export default function MyExtension() {
+  // Limited to Shopify-provided components only
+  return (
+    <Banner title="Custom Message">
+      You cannot render arbitrary HTML here.
+    </Banner>
+  );
+}
+```
+
+### Available Components (Polaris-based)
+
+- `Banner`, `Button`, `Checkbox`
+- `Heading`, `Text`, `TextBlock`
+- `Image`, `Icon`
+- `BlockStack`, `InlineStack`, `Grid`
+- `TextField`, `Select`, `ChoiceList`
+
+**Critical Limitation**: You can ONLY use these Shopify-provided components. No custom HTML, no `<div>`, no `<script>` tags.
+
+### Extension Targets (Where You Can Place Extensions)
+
+```
+checkout/
+├── information/
+│   └── contact/before, after
+├── shipping/
+│   └── address/before, after
+├── payment/                    ← PAYMENT STEP
+│   └── method-list/before, after  ⚠️ Plus Only
+├── order-summary/
+│   └── line-item/before, after
+└── thank-you/
+    └── customer-information/before, after
+```
+
+### Sandboxed Environment Restrictions
+
+| What You CAN Do | What You CANNOT Do |
+|-----------------|-------------------|
+| Display Shopify components | Inject custom HTML |
+| Access checkout data via APIs | Access DOM directly |
+| Show banners/messages | Run arbitrary JavaScript |
+| Collect additional form data | Override CSS/branding |
+| Validate checkout fields | Access payment card data |
+
+---
+
+## 3. checkout.liquid (Deprecated)
+
+### Historical Context
+
+`checkout.liquid` was Shopify's original method for checkout customization, available only to Shopify Plus merchants. It allowed:
+
+- Custom JavaScript injection
+- DOM manipulation after render
+- Custom CSS styling
+- Third-party script tags
+
+### Deprecation Timeline
+
+| Milestone | Date | Impact |
+|-----------|------|--------|
+| Information/Shipping/Payment steps removed | August 13, 2024 | ❌ No longer editable |
+| Thank You/Order Status deprecated | August 28, 2025 | ⚠️ Sunsetting |
+| Shopify Scripts end | June 30, 2026 | End of legacy customization |
+
+### Why It Was Deprecated
+
+1. **Security risks** from arbitrary code injection
+2. **Performance issues** from unoptimized scripts
+3. **Maintenance burden** for Shopify
+4. **Inconsistent merchant experiences**
+
+### Current Status
+
+> **checkout.liquid is effectively DEAD for payment customization.**
+>
+> Any existing integrations using checkout.liquid for custom payment forms will stop working and cannot be recreated with Checkout Extensibility.
+
+---
+
+## 4. Payment Extensions Program
+
+### Overview
+
+Shopify's Payment Extensions Program is the **ONLY official way** to add custom payment methods to Shopify checkout.
+
+### Eligibility Requirements
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                  PAYMENT PARTNER REQUIREMENTS                │
+├─────────────────────────────────────────────────────────────┤
+│ 1. Apply to become a Shopify Partner                        │
+│ 2. Submit Payment Extension application                     │
+│ 3. Pass security review (PCI compliance, etc.)              │
+│ 4. Sign revenue share agreement                             │
+│ 5. Meet technical requirements                              │
+│ 6. Pass Shopify's approval process                          │
+│ 7. Ongoing compliance and review                            │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### Payment Extension Types
+
+| Type | Description | Use Case |
+|------|-------------|----------|
+| **Credit Card** | Standard card processing with 3DS | Stripe, Braintree competitors |
+| **Credit Card with UI** | Custom fields (installments, etc.) | Affirm, Klarna |
+| **Custom Credit Card** | Hosted fields for processing | Specialized card processors |
+| **Alternative Payments** | Non-card methods | Crypto, bank transfers, BNPL |
+| **Redeemables** | Gift cards, store credit | Third-party gift card providers |
+| **Offsite** | Redirect to external payment page | PayPal, redirect-based flows |
+
+### Approval Process
+
+1. **Application** - Submit through Shopify Partners portal
+2. **Technical Review** - API integration, security audit
+3. **Compliance Check** - PCI-DSS, regional regulations
+4. **Test Integration** - Sandbox testing with Shopify
+5. **Legal Agreement** - Revenue share, terms of service
+6. **Launch Review** - Final approval before going live
+7. **Ongoing Monitoring** - Continuous compliance
+
+**Timeline**: This process typically takes **3-6 months minimum**.
+
+---
+
+## 5. Technical Limitations & Restrictions
+
+### Checkout UI Extensions Cannot:
+
+```javascript
+// ❌ CANNOT inject custom HTML
+<div class="my-payment-form">...</div>
+
+// ❌ CANNOT run arbitrary scripts
+<script src="https://cdn.one.ooo/drop-in.js"></script>
+
+// ❌ CANNOT access DOM
+document.querySelector('.payment-section').appendChild(myElement);
+
+// ❌ CANNOT override styles
+.shopify-payment-button { display: none; }
+
+// ❌ CANNOT access payment card data
+const cardNumber = getCardNumber(); // Blocked by sandbox
+
+// ❌ CANNOT render Web Components
+<one-payment amount="5000"></one-payment>
+```
+
+### Why This Matters for Drop-in Integration
+
+The One Payments Drop-in element is a **Web Component** (`<one-payment>`) that requires:
+
+1. ✅ JavaScript execution → ❌ **Blocked in sandbox**
+2. ✅ DOM access → ❌ **Blocked in sandbox**
+3. ✅ Custom HTML rendering → ❌ **Blocked in sandbox**
+4. ✅ External script loading → ❌ **Blocked in sandbox**
+5. ✅ CSS styling → ❌ **Cannot override**
+6. ✅ Payment card collection → ❌ **Blocked for security**
+
+### Shopify's Security Model
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    SHOPIFY CHECKOUT                          │
+│  ┌─────────────────────────────────────────────────────┐    │
+│  │              ISOLATED SANDBOX                        │    │
+│  │  ┌─────────────────┐                                │    │
+│  │  │  Your Extension │ ← Limited API access           │    │
+│  │  │  (Preact/React) │ ← No DOM access                │    │
+│  │  │                 │ ← No external scripts          │    │
+│  │  └─────────────────┘                                │    │
+│  │         ↓                                           │    │
+│  │  Shopify Components Only                            │    │
+│  └─────────────────────────────────────────────────────┘    │
+│                          ↓                                   │
+│  ┌─────────────────────────────────────────────────────┐    │
+│  │         SHOPIFY PAYMENT PROCESSING                   │    │
+│  │         (PCI-Compliant, Managed by Shopify)         │    │
+│  └─────────────────────────────────────────────────────┘    │
+└─────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 6. Integration Options Analysis
+
+### Option 1: Become a Shopify Payments Partner
+
+**Process**:
+1. Apply to Shopify Payments Platform
+2. Build integration using Payments Extensions API
+3. Pass security and compliance review
+4. Launch as official payment provider
+
+**Pros**:
+- Full integration into Shopify checkout
+- Access to all Shopify merchants
+- Official support and documentation
+
+**Cons**:
+- 3-6+ month approval process
+- Significant development effort
+- Revenue share with Shopify
+- Ongoing compliance requirements
+- Must rebuild Drop-in as Shopify-native extension
+
+**Effort**: ⭐⭐⭐⭐⭐ (Very High)
+
+---
+
+### Option 2: Headless Commerce (Storefront API)
+
+**Process**:
+1. Merchant builds custom storefront (Next.js, Gatsby, etc.)
+2. Uses Shopify Storefront API for products/cart
+3. Implements custom checkout with One Payments Drop-in
+4. Handles order creation via API
+
+**Pros**:
+- Full control over checkout experience
+- Can use Drop-in element directly
+- No Shopify approval needed
+
+**Cons**:
+- Requires complete custom storefront build
+- Merchant loses Shopify's native checkout benefits
+- More complex order management
+- Not suitable for typical Shopify merchants
+
+**Effort**: ⭐⭐⭐⭐ (High)
+
+---
+
+### Option 3: Post-Purchase Integration
+
+**Process**:
+1. Use Shopify checkout for initial purchase
+2. Offer additional products/services post-purchase
+3. Integrate Drop-in on thank-you page or separate page
+
+**Pros**:
+- No checkout modification needed
+- Works on all Shopify plans
+- Can use Drop-in element freely
+
+**Cons**:
+- Not a primary payment method
+- Limited use case (upsells, subscriptions)
+- Doesn't replace Shopify checkout
+
+**Effort**: ⭐⭐ (Low-Medium)
+
+---
+
+### Option 4: External Checkout Page
+
+**Process**:
+1. Merchant adds "Buy with One" button to product pages
+2. Redirects to external checkout hosted by you
+3. Processes payment with Drop-in
+4. Creates order in Shopify via API
+
+**Pros**:
+- Full control over payment experience
+- Can use Drop-in element
+- Works on all Shopify plans
+
+**Cons**:
+- Customers leave Shopify site
+- Trust/conversion concerns
+- Complex order syncing
+- May violate Shopify TOS
+
+**Effort**: ⭐⭐⭐ (Medium)
+
+---
+
+## 7. Feasibility for One Payments Drop-in
+
+### Can Regular Merchants Integrate the Drop-in?
+
+**NO.** Regular Shopify merchants cannot:
+- Add custom JavaScript to checkout
+- Render Web Components in checkout
+- Replace Shopify's payment methods
+- Modify the checkout DOM
+
+### Can Shopify Plus Merchants Integrate?
+
+**VERY LIMITED.** Even with Shopify Plus:
+- Checkout UI Extensions are sandboxed
+- Cannot render arbitrary HTML/Web Components
+- Cannot inject external scripts
+- Cannot access payment card data directly
+
+The Drop-in element **cannot be used as-is** in Shopify checkout.
+
+### What Would Be Required?
+
+To integrate One Payments into Shopify checkout, you would need to:
+
+1. **Become a Shopify Payments Partner** (3-6+ months)
+2. **Rebuild the integration** using Shopify's Payments Extensions API
+3. **Use Shopify's component system** instead of Web Components
+4. **Handle payments through Shopify's Payment resource**
+5. **Pass security and compliance review**
+
+---
+
+## 8. Alternative Approaches
+
+### A. Shopify App with Separate Payment Page
+
+```
+Customer Journey:
+┌──────────┐    ┌──────────┐    ┌──────────────┐    ┌──────────┐
+│ Shopify  │ -> │  Cart    │ -> │ One Payments │ -> │  Order   │
+│  Store   │    │  Page    │    │  Drop-in     │    │ Complete │
+└──────────┘    └──────────┘    │  (External)  │    └──────────┘
+                                └──────────────┘
+```
+
+Build a Shopify App that:
+1. Adds "Pay with One" button to cart
+2. Redirects to hosted checkout page with Drop-in
+3. Processes payment
+4. Creates draft order in Shopify
+5. Redirects back to thank-you page
+
+### B. Subscription/Recurring Payments
+
+For merchants selling subscriptions:
+1. Initial purchase through Shopify
+2. Recurring payments via One Payments
+3. Customer portal with Drop-in for payment management
+
+### C. B2B / Invoice Payments
+
+For B2B merchants:
+1. Create invoices in Shopify
+2. Send payment links with Drop-in
+3. Payment collection outside checkout
+
+### D. Hybrid: Shopify + Custom Landing Pages
+
+1. Use Shopify for catalog and cart
+2. Specific products have "custom checkout" option
+3. Those products use external page with Drop-in
+4. Regular products use Shopify checkout
+
+---
+
+## 9. Recommendations
+
+### For One Payments Team
+
+| Priority | Action | Timeline | Effort |
+|----------|--------|----------|--------|
+| 1 | Apply to Shopify Payments Partner Program | Start immediately | Low (application) |
+| 2 | Build proof-of-concept Headless integration | 2-4 weeks | Medium |
+| 3 | Create Shopify App for external checkout flow | 4-6 weeks | Medium |
+| 4 | Document alternative integration patterns | 1-2 weeks | Low |
+| 5 | Develop Shopify-native extension (if approved) | 3-6 months | Very High |
+
+### For Merchants Wanting to Use One Payments
+
+| Merchant Type | Recommended Approach |
+|---------------|---------------------|
+| Small Business | Use external checkout page or wait for official integration |
+| Shopify Plus | Consider headless approach for full control |
+| Enterprise | Contact One Payments for custom solution |
+| Subscription Business | Use Drop-in for recurring payment management |
+
+### Realistic Timeline for Full Integration
+
+```
+Month 1-2:   Apply to Payments Partner Program
+Month 2-4:   Security review and compliance preparation
+Month 4-6:   Technical integration development
+Month 6-8:   Testing and approval process
+Month 8-10:  Soft launch with select merchants
+Month 10-12: Full public availability
+```
+
+---
+
+## Conclusion
+
+**Direct integration of the One Payments Drop-in element into Shopify's native checkout is NOT currently possible** for regular merchants or even Shopify Plus merchants without becoming an approved Shopify Payments Partner.
+
+The checkout environment is intentionally locked down for security and compliance reasons. Any custom payment integration must go through Shopify's official Payments Platform program.
+
+### Immediate Actions
+
+1. **Do NOT promise** Shopify checkout integration to merchants
+2. **Apply** to Shopify Payments Partner Program if serious about this market
+3. **Offer alternatives** like external checkout pages or headless solutions
+4. **Document** the limitations clearly for sales/support teams
+
+---
+
+## References & Sources
+
+- [Shopify Checkout UI Extensions](https://shopify.dev/docs/api/checkout-ui-extensions)
+- [Shopify Payments Extensions](https://shopify.dev/docs/apps/build/payments)
+- [checkout.liquid Deprecation](https://shopify.dev/docs/storefronts/themes/architecture/layouts/checkout-liquid)
+- [Checkout Extensibility Overview](https://www.shopify.com/plus/upgrading-to-checkout-extensibility)
+- [Shopify Checkout Customization Guide](https://help.shopify.com/en/manual/checkout-settings/checkout-customization)
+- [Payment Method Customizations](https://help.shopify.com/en/manual/checkout-settings/checkout-blocks/customizations/payment-methods)
+- [Shopify Community: Custom Payment Gateway](https://community.shopify.com/c/payments-shipping-and/how-to-setup-a-custom-payment-gateway-in-2023/m-p/2082131)
+
+---
+
+*Document created: December 3, 2024*
+*Last updated: December 3, 2024*
+*Version: 1.0*