node-behind-api-client 2.0.48

package/docs/behind-api-client/payments/stripe/README.flow.md

@@ -0,0 +1,254 @@
+# Stripe Subscription Flow
+
+## Workflow Overview
+
+This document outlines the complete subscription process for integrating Stripe payments with BehindAPI.
+
+### Process Steps
+
+1. **Extract Subscription ID**
+    - Receive `subscription_id` from URL GET parameter
+
+2. **Check Existing Payment Methods**
+    - Query BehindAPI to check if user has saved Stripe cards
+
+3. **Direct Subscription (Existing Card)**
+    - If saved card exists, proceed directly to subscription creation using `subscription_id`
+
+4. **New Card Authorization Flow**
+    - If no saved card exists, initiate card authorization process:
+
+   4.1 **Initialize Authorization**
+    - Call BehindAPI to initialize card authorization
+    - Obtain `client_secret` for Stripe integration
+
+   4.2 **Stripe Card Setup**
+    - Use Stripe SDK to authorize card with `client_secret`
+    - Receive customer card token from Stripe
+
+   4.3 **Finalize Authorization**
+    - Send customer card token to BehindAPI endpoint
+    - Save payment method for future use
+
+   4.4 **Create Subscription**
+    - Subscribe user using `subscription_id`
+
+
+````html
+
+ <script src="https://js.stripe.com/v3/"></script>
+
+ <form  style="width:100%;display:none" method="post" id="stripe-payment-form">
+     <div class="form-row">
+         <label for="card-element" style="display:none">
+             We accept credit or debit cards. After you fill all necessary fileds,
+             <span id="stripe-payment-form-amount"></span> will be debited from your card. The rest of founds
+             <span id="stripe-payment-form-amount-rest"></span> will be taken from your Zecamp wallet.
+         </label>
+         <div id="stripe-payment-form-card-element">
+             <!-- A Stripe Element will be inserted here. -->
+         </div>
+
+         <div id="payment-method-selection">
+
+         </div>
+
+         <!-- Used to display form errors. -->
+         <div id="card-errors" role="alert"></div>
+     </div>
+ </form>
+
+````
+
+````js
+
+/**
+ * Stripe Payment Integration
+ * Handles subscription payments with saved card support
+ */
+$(document).ready(function() {
+    (async () => {
+        // Initialize API clients
+        console.log("Initializing Stripe Payment System...");
+        const BehindAPI = new BehindApiClient(
+            "https://127.0.0.1:6002",
+            "ACCESS_TOKEN HERE"
+        );
+        const stripe = Stripe("pk_test_OE8u9FAKvK0W8vYr5mMCj92G");
+
+        // Step 1: Check for existing saved cards
+        const savedCards = await BehindAPI.payments.V21.cards.getList();
+        const savedStripeCards = savedCards.data.filter(card => card.payment_method === "stripe");
+        console.log("Found saved Stripe cards:", savedStripeCards.length);
+
+        // Step 2: Initialize payment form based on saved cards
+        if (savedStripeCards.length === 0) {
+            initializeNewCardForm();
+        } else {
+            displaySavedCardInfo();
+        }
+
+        /**
+         * Initialize form for new card entry
+         */
+        function initializeNewCardForm() {
+            console.log("Setting up new card form...");
+
+            // Create Stripe Elements instance
+            const elements = stripe.elements();
+
+            // Define card input styling
+            const cardElementStyle = {
+                base: {
+                    color: '#32325d',
+                    lineHeight: '18px',
+                    fontFamily: '"Helvetica Neue", Helvetica, sans-serif',
+                    fontSmoothing: 'antialiased',
+                    fontSize: '16px',
+                    '::placeholder': {
+                        color: '#aab7c4'
+                    }
+                },
+                invalid: {
+                    color: '#fa755a',
+                    iconColor: '#fa755a'
+                }
+            };
+
+            // Create and mount card element
+            const card = elements.create('card', { style: cardElementStyle });
+            card.mount('#stripe-payment-form-card-element');
+
+            // Handle real-time validation errors
+            card.addEventListener('change', function(event) {
+                const displayError = document.getElementById('card-errors');
+                displayError.textContent = event.error ? event.error.message : '';
+            });
+
+            // Store card element for use in payment processing
+            window.stripeCardElement = card;
+        }
+
+        /**
+         * Display saved card information
+         */
+        function displaySavedCardInfo() {
+            console.log("Displaying saved card info...");
+
+            const firstCard = savedStripeCards[0];
+            const cardElement = document.getElementById('stripe-payment-form-card-element');
+
+            // Generate card display HTML
+            cardElement.innerHTML = `
+                <div class="saved-card-info">
+                    <div class="card-display">
+                       <div class="card-icon">${getCardIcon(firstCard.binding_type)}</div>
+                        <div class="card-details">
+                           
+                            <div class="card-number">•••• •••• •••• ${firstCard.binding_name}</div>
+                        </div>
+                
+                    </div>
+                </div>
+            `;
+        }
+
+        /**
+         * Get appropriate icon for card type
+         */
+        function getCardIcon(cardType) {
+            const icons = {
+                'visa': '💳',
+                'mastercard': '💳',
+                'amex': '💳',
+                'discover': '💳',
+                'default': '💳'
+            };
+            return icons[cardType.toLowerCase()] || icons.default;
+        }
+
+        // Step 3: Handle payment form submission
+        $("#stripe-payment-submit").on("click", async function(event) {
+            event.preventDefault();
+            console.log("Processing payment...");
+
+            try {
+                if (savedStripeCards.length === 0) {
+                    await processNewCardPayment();
+                } else {
+                    await processSubscriptionWithSavedCard();
+                }
+            } catch (error) {
+                console.error("Payment processing error:", error);
+                alert("Payment failed. Please try again.");
+            }
+        });
+
+        /**
+         * Process payment with new card
+         */
+        async function processNewCardPayment() {
+            console.log("Processing new card payment...");
+
+            // Step 1: Initialize payment intent on server
+            const paymentIntent = await BehindAPI.payments.V21.stripe.init();
+            console.log("Payment intent created:", paymentIntent);
+
+            const clientSecret = paymentIntent.data.client_secret;
+            const cardholderName = "CARDHOLDER NAME"; // TODO: Get from form input
+
+            try {
+                // Step 2: Set up payment method with Stripe
+                const cardToken = await stripe.handleCardSetup(
+                    clientSecret,
+                    window.stripeCardElement,
+                    {
+                        payment_method_data: {
+                            billing_details: { name: cardholderName }
+                        }
+                    }
+                );
+
+                // Step 3: Finalize card setup on server
+                const bindResult = await BehindAPI.payments.V21.stripe.finalise(
+                    cardToken.setupIntent.payment_method
+                );
+                console.log("Card setup finalized:", bindResult);
+
+                // Step 4: Create subscription
+                await createSubscription();
+
+            } catch (cardError) {
+                console.error("Card setup error:", cardError);
+                throw new Error("Card setup failed");
+            }
+        }
+
+        /**
+         * Process subscription with existing saved card
+         */
+        async function processSubscriptionWithSavedCard() {
+            console.log("Using saved card for subscription...");
+            await createSubscription();
+        }
+
+        /**
+         * Create subscription using the configured payment method
+         */
+        async function createSubscription() {
+            console.log("Creating subscription...");
+
+            // TODO: Get subscription_id from URL parameter
+            const subscriptionId = "subscription_id_here";
+
+            const subscriptionResult = await BehindAPI.payments.V21.subscriptions.subscribe(subscriptionId);
+            console.log("Subscription created successfully:", subscriptionResult);
+
+            // Show success message to user
+            alert("Subscription activated successfully!");
+        }
+
+    })();
+});
+
+````