node-behind-api-client 2.0.48

package/docs/behind-api-client/payments/payture/README.subscriptions.md

@@ -0,0 +1,1266 @@
+# Payments API V21 - Subscriptions Endpoint
+
+This document provides detailed information about the Subscriptions management methods for the V21 Payments API.
+
+## Overview
+
+The Subscriptions Payments API V21 provides methods for retrieving and managing user subscription instances. This includes fetching active subscriptions with their payment methods, billing details, status information, and scheduling data.
+
+---
+
+## Payments API V21 - Subscriptions Methods
+
+### behindAPI.V21.payments.subscriptions.getList()
+Retrieves all subscription instances for the authenticated user, including payment methods, amounts, currencies, intervals, and status information.
+
+**Parameters:**
+- None (uses authenticated user session)
+
+**Authorization:**
+- Required: Yes (uses `req.userSession.UserId`)
+
+**Usage:**
+```javascript
+const result = await behindAPI.V21.payments.subscriptions.getList();
+
+// Success Response (with subscriptions):
+{
+    success: true,
+        data: [
+    {
+        subscription_instance_id: "cc0e8400-e29b-41d4-a716-446655440009",
+        subscription_key: "premium-monthly",
+        payment_method: "payture",
+        subscription_amount: 3200,
+        subscription_currency: "RUB",
+        subscription_interval: 2592000,
+        instance_last_attempt_time: "2024-11-24T09:24:39.880Z",
+        instance_enabled: true,
+        instance_active: true,
+        instance_created_at: "2024-11-01T10:00:00.000Z",
+        next_billing_date: "2024-12-01T10:00:00.000Z"
+    }
+]
+}
+
+// Success Response (no subscriptions):
+{
+    success: true,
+        data: []
+}
+
+// Error Response:
+{
+    success: false,
+        message: "Can't finish request",
+    e: { /* error details */ }
+}
+```
+
+### behindAPI.V21.payments.subscriptions.subscribe(subscriptionId)
+Creates a new subscription instance for the authenticated user, linking them to a specific subscription plan and establishing recurring billing.
+
+**Parameters:**
+- `subscriptionId` (string, required) - The subscription plan ID/key to create instance for
+
+**Authorization:**
+- Required: Yes (uses `req.userSession.UserId`)
+
+**Usage:**
+```javascript
+const result = await behindAPI.V21.payments.subscriptions.subscribe(
+    "premium-monthly"
+);
+
+// Success Response:
+{
+    success: true,
+    data: {
+        subscription_instance_id: "sub_inst_1234567890abcdef"
+    }
+}
+
+// Error Response (failed to create):
+{
+    success: false,
+    message: "Failed to create subscription instance"
+}
+
+// Error Response (general error):
+{
+    success: false,
+    message: "Can't finish request",
+    e: { /* error details */ }
+}
+```
+
+---
+
+## Data Structure Reference
+
+### Subscription Instance Object
+Each subscription instance in the response contains:
+
+**Identification:**
+- `subscription_instance_id` (UUID string) - Unique identifier for this subscription instance
+- `subscription_key` (string) - The subscription plan identifier (e.g., "premium-monthly", "basic-annual")
+
+**Payment Information:**
+- `payment_method` (string) - Payment gateway type ("payture", "stripe", "yookassa")
+- `subscription_amount` (number) - Subscription cost in minor currency units (kopecks/cents)
+- `subscription_currency` (string) - ISO currency code (e.g., "RUB", "USD", "EUR")
+
+**Billing Schedule:**
+- `subscription_interval` (number) - Billing interval in seconds
+    - 2,592,000 = 30 days (monthly)
+    - 7,776,000 = 90 days (quarterly)
+    - 15,552,000 = 180 days (semi-annual)
+    - 31,536,000 = 365 days (annual)
+
+**Status Information:**
+- `instance_enabled` (boolean) - Whether subscription is enabled for billing
+- `instance_active` (boolean) - Whether subscription is currently active
+- `instance_last_attempt_time` (ISO datetime string) - Last payment attempt timestamp
+- `instance_created_at` (ISO datetime string) - When subscription was created
+- `next_billing_date` (ISO datetime string) - Calculated next billing date
+
+**Conversion Helpers:**
+```javascript
+// Amount conversion
+const rubles = subscription_amount / 100; // 3200 → 32.00 RUB
+
+// Interval conversion
+const days = subscription_interval / 86400; // 2592000 → 30 days
+const months = days / 30; // Approximate months
+```
+
+### Subscription Creation Response
+The `subscribe()` method returns:
+
+**Success Response:**
+- `success` (boolean) - Always `true` for successful requests
+- `data` (object) - Container for response data
+    - `subscription_instance_id` (UUID string) - Created subscription instance unique identifier
+
+**Error Response:**
+- `success` (boolean) - Always `false` for failed requests
+- `message` (string) - Error description
+    - "Failed to create subscription instance" - Database returned null/false
+    - "Can't finish request" - General processing error
+- `e` (object, optional) - Error details
+
+---
+
+## Complete Usage Examples
+
+### Basic Subscription List Retrieval
+
+```javascript
+// Example: Get and display user's subscriptions
+async function getUserSubscriptions() {
+    try {
+        console.log("Fetching user's subscriptions...");
+        
+        const result = await behindAPI.V21.payments.subscriptions.getList();
+        
+        if (result.success) {
+            if (result.data.length === 0) {
+                console.log("No active subscriptions found");
+                return [];
+            }
+            
+            console.log(`✓ Found ${result.data.length} subscription(s)`);
+            
+            result.data.forEach((sub, index) => {
+                console.log(`\nSubscription ${index + 1}:`);
+                console.log(`  Plan: ${sub.subscription_key}`);
+                console.log(`  Amount: ${sub.subscription_amount / 100} ${sub.subscription_currency}`);
+                console.log(`  Status: ${sub.instance_active ? 'Active' : 'Inactive'}`);
+                console.log(`  Next billing: ${new Date(sub.next_billing_date).toLocaleDateString()}`);
+            });
+            
+            return result.data;
+        } else {
+            console.error(`✗ Failed to fetch subscriptions: ${result.message}`);
+            return [];
+        }
+    } catch (error) {
+        console.error("Error fetching subscriptions:", error);
+        return [];
+    }
+}
+
+// Usage
+const subscriptions = await getUserSubscriptions();
+```
+
+### Create a New Subscription
+
+```javascript
+// Example: Create a new subscription for the authenticated user
+async function createSubscription(planKey) {
+    try {
+        console.log(`Creating subscription for plan: ${planKey}`);
+        
+        const result = await behindAPI.V21.payments.subscriptions.subscribe(planKey);
+        
+        if (result.success) {
+            console.log("✓ Subscription created successfully!");
+            console.log(`Subscription Instance ID: ${result.data.subscription_instance_id}`);
+            
+            return result.data.subscription_instance_id;
+        } else {
+            console.error(`✗ Failed to create subscription: ${result.message}`);
+            return null;
+        }
+    } catch (error) {
+        console.error("Error creating subscription:", error);
+        return null;
+    }
+}
+
+// Usage
+const subscriptionId = await createSubscription("premium-monthly");
+```
+
+### Complete Subscription Flow (Card Registration + Creation)
+
+```javascript
+// Example: Full flow from card registration to subscription creation
+async function completeSubscriptionFlow(planKey) {
+    try {
+        console.log("Starting subscription flow...");
+        
+        // Step 1: Check if user has a payment method
+        const cardsResult = await behindAPI.V21.payments.cards.getList();
+        
+        if (!cardsResult.success || cardsResult.data.length === 0) {
+            console.log("No payment method found. Initiating card registration...");
+            
+            // Initialize card registration
+            const initResult = await behindAPI.V21.payments.payture.init();
+            
+            if (initResult.success) {
+                // Store pending subscription for after card registration
+                sessionStorage.setItem('pending_subscription', planKey);
+                sessionStorage.setItem('card_registration_pending', 'true');
+                
+                // Redirect to Payture
+                window.location.href = initResult.data.RedirectUrl;
+                return;
+            } else {
+                console.error("Failed to initialize card registration");
+                return null;
+            }
+        }
+        
+        console.log("Payment method found. Creating subscription...");
+        
+        // Step 2: Create subscription
+        const subscriptionResult = await behindAPI.V21.payments.subscriptions.subscribe(planKey);
+        
+        if (subscriptionResult.success) {
+            console.log("✓ Subscription created successfully!");
+            console.log(`Subscription ID: ${subscriptionResult.data.subscription_instance_id}`);
+            
+            return subscriptionResult.data.subscription_instance_id;
+        } else {
+            console.error(`Failed to create subscription: ${subscriptionResult.message}`);
+            return null;
+        }
+        
+    } catch (error) {
+        console.error("Error in subscription flow:", error);
+        return null;
+    }
+}
+
+// Usage
+const subscriptionId = await completeSubscriptionFlow("premium-monthly");
+
+// In callback page after card registration:
+async function handleCardRegistrationCallback() {
+    const params = new URLSearchParams(window.location.search);
+    const success = params.get('result');
+    
+    if (success === 'True') {
+        // Finalize card registration
+        const finalizeResult = await behindAPI.V21.payments.payture.finalise();
+        
+        if (finalizeResult.success) {
+            console.log("Card registered successfully!");
+            
+            // Create pending subscription
+            const planKey = sessionStorage.getItem('pending_subscription');
+            
+            if (planKey) {
+                const subscriptionResult = await behindAPI.V21.payments.subscriptions.subscribe(planKey);
+                
+                if (subscriptionResult.success) {
+                    console.log("Subscription created!");
+                    sessionStorage.removeItem('pending_subscription');
+                    sessionStorage.removeItem('card_registration_pending');
+                    window.location.href = '/subscription-success';
+                } else {
+                    console.error("Failed to create subscription");
+                    window.location.href = '/error';
+                }
+            }
+        }
+    }
+}
+```
+
+### Display Subscriptions Dashboard
+
+```javascript
+// Example: Create a subscription management dashboard
+class SubscriptionDashboard {
+    constructor(containerId) {
+        this.container = document.getElementById(containerId);
+        this.subscriptions = [];
+    }
+    
+    async loadSubscriptions() {
+        try {
+            const result = await behindAPI.V21.payments.subscriptions.getList();
+            
+            if (!result.success) {
+                this.showError("Failed to load subscriptions");
+                return;
+            }
+            
+            this.subscriptions = result.data;
+            
+            if (this.subscriptions.length === 0) {
+                this.showNoSubscriptions();
+                return;
+            }
+            
+            this.renderDashboard();
+            
+        } catch (error) {
+            console.error("Error loading subscriptions:", error);
+            this.showError("An error occurred while loading subscriptions");
+        }
+    }
+    
+    renderDashboard() {
+        const html = `
+            <div class="subscription-dashboard">
+                <h2>Your Subscriptions</h2>
+                ${this.renderSummary()}
+                ${this.renderSubscriptionList()}
+            </div>
+        `;
+        
+        this.container.innerHTML = html;
+    }
+    
+    renderSummary() {
+        const stats = this.calculateStats();
+        
+        return `
+            <div class="subscription-summary">
+                <div class="stat">
+                    <label>Active Subscriptions</label>
+                    <value>${stats.active}</value>
+                </div>
+                <div class="stat">
+                    <label>Monthly Cost</label>
+                    <value>${stats.monthlyCost} ${stats.currency}</value>
+                </div>
+                <div class="stat">
+                    <label>Next Payment</label>
+                    <value>${stats.nextPayment}</value>
+                </div>
+            </div>
+        `;
+    }
+    
+    renderSubscriptionList() {
+        return `
+            <div class="subscription-list">
+                ${this.subscriptions.map(sub => this.renderSubscription(sub)).join('')}
+            </div>
+        `;
+    }
+    
+    renderSubscription(sub) {
+        const amount = (sub.subscription_amount / 100).toFixed(2);
+        const interval = this.formatInterval(sub.subscription_interval);
+        const nextBilling = new Date(sub.next_billing_date).toLocaleDateString();
+        const isActive = sub.instance_active && sub.instance_enabled;
+        
+        return `
+            <div class="subscription-card ${isActive ? 'active' : 'inactive'}">
+                <div class="subscription-header">
+                    <h3>${this.formatSubscriptionName(sub.subscription_key)}</h3>
+                    <span class="badge ${isActive ? 'badge-success' : 'badge-inactive'}">
+                        ${isActive ? 'Active' : 'Inactive'}
+                    </span>
+                </div>
+                <div class="subscription-details">
+                    <div class="detail">
+                        <span class="label">Amount:</span>
+                        <span class="value">${amount} ${sub.subscription_currency}</span>
+                    </div>
+                    <div class="detail">
+                        <span class="label">Billing:</span>
+                        <span class="value">${interval}</span>
+                    </div>
+                    <div class="detail">
+                        <span class="label">Payment Method:</span>
+                        <span class="value">${this.formatPaymentMethod(sub.payment_method)}</span>
+                    </div>
+                    <div class="detail">
+                        <span class="label">Next Billing:</span>
+                        <span class="value">${nextBilling}</span>
+                    </div>
+                </div>
+                <div class="subscription-actions">
+                    ${isActive ? 
+                        `<button onclick="dashboard.cancelSubscription('${sub.subscription_instance_id}')">
+                            Cancel Subscription
+                        </button>` :
+                        `<button onclick="dashboard.renewSubscription('${sub.subscription_instance_id}')">
+                            Renew Subscription
+                        </button>`
+                    }
+                </div>
+            </div>
+        `;
+    }
+    
+    calculateStats() {
+        const active = this.subscriptions.filter(s => s.instance_active).length;
+        
+        // Calculate monthly equivalent cost
+        let monthlyCost = 0;
+        let currency = 'RUB';
+        
+        this.subscriptions.forEach(sub => {
+            if (sub.instance_active) {
+                const amount = sub.subscription_amount / 100;
+                const months = sub.subscription_interval / 2592000; // Convert to months
+                monthlyCost += amount / months;
+                currency = sub.subscription_currency;
+            }
+        });
+        
+        // Find next payment date
+        const nextPaymentDates = this.subscriptions
+            .filter(s => s.instance_active)
+            .map(s => new Date(s.next_billing_date));
+        
+        const nextPayment = nextPaymentDates.length > 0 
+            ? new Date(Math.min(...nextPaymentDates)).toLocaleDateString()
+            : 'N/A';
+        
+        return {
+            active,
+            monthlyCost: monthlyCost.toFixed(2),
+            currency,
+            nextPayment
+        };
+    }
+    
+    formatInterval(seconds) {
+        const days = seconds / 86400;
+        
+        if (days === 30) return 'Monthly';
+        if (days === 90) return 'Quarterly';
+        if (days === 180) return 'Semi-Annual';
+        if (days === 365) return 'Annual';
+        
+        return `Every ${Math.round(days)} days`;
+    }
+    
+    formatSubscriptionName(key) {
+        return key
+            .split('-')
+            .map(word => word.charAt(0).toUpperCase() + word.slice(1))
+            .join(' ');
+    }
+    
+    formatPaymentMethod(method) {
+        const methods = {
+            payture: 'Payture Card',
+            stripe: 'Stripe Card',
+            yookassa: 'YooKassa'
+        };
+        return methods[method] || method;
+    }
+    
+    showNoSubscriptions() {
+        this.container.innerHTML = `
+            <div class="no-subscriptions">
+                <h2>No Active Subscriptions</h2>
+                <p>You don't have any active subscriptions yet.</p>
+                <button onclick="window.location.href='/subscribe'">
+                    Browse Plans
+                </button>
+            </div>
+        `;
+    }
+    
+    showError(message) {
+        this.container.innerHTML = `
+            <div class="error-message">
+                <p>⚠️ ${message}</p>
+                <button onclick="dashboard.loadSubscriptions()">Retry</button>
+            </div>
+        `;
+    }
+    
+    async cancelSubscription(subscriptionId) {
+        // Implement cancellation logic
+        console.log(`Canceling subscription: ${subscriptionId}`);
+    }
+    
+    async renewSubscription(subscriptionId) {
+        // Implement renewal logic
+        console.log(`Renewing subscription: ${subscriptionId}`);
+    }
+}
+
+// Initialize dashboard
+const dashboard = new SubscriptionDashboard('subscription-container');
+dashboard.loadSubscriptions();
+```
+
+### Filter and Analyze Subscriptions
+
+```javascript
+// Example: Analyze user's subscription data
+class SubscriptionAnalyzer {
+    constructor(subscriptions) {
+        this.subscriptions = subscriptions;
+    }
+    
+    getActiveSubscriptions() {
+        return this.subscriptions.filter(sub => 
+            sub.instance_active && sub.instance_enabled
+        );
+    }
+    
+    getInactiveSubscriptions() {
+        return this.subscriptions.filter(sub => 
+            !sub.instance_active || !sub.instance_enabled
+        );
+    }
+    
+    getSubscriptionsByPaymentMethod(method) {
+        return this.subscriptions.filter(sub => 
+            sub.payment_method === method
+        );
+    }
+    
+    getTotalMonthlySpend() {
+        let total = 0;
+        
+        this.getActiveSubscriptions().forEach(sub => {
+            const amount = sub.subscription_amount / 100;
+            const intervalMonths = sub.subscription_interval / 2592000;
+            total += amount / intervalMonths;
+        });
+        
+        return total;
+    }
+    
+    getAnnualSpend() {
+        return this.getTotalMonthlySpend() * 12;
+    }
+    
+    getUpcomingPayments(days = 30) {
+        const now = Date.now();
+        const futureDate = now + (days * 24 * 60 * 60 * 1000);
+        
+        return this.getActiveSubscriptions()
+            .filter(sub => {
+                const nextBilling = new Date(sub.next_billing_date).getTime();
+                return nextBilling >= now && nextBilling <= futureDate;
+            })
+            .sort((a, b) => 
+                new Date(a.next_billing_date) - new Date(b.next_billing_date)
+            );
+    }
+    
+    getSubscriptionHealth() {
+        const active = this.getActiveSubscriptions().length;
+        const total = this.subscriptions.length;
+        const inactive = total - active;
+        
+        return {
+            total,
+            active,
+            inactive,
+            healthScore: total > 0 ? (active / total * 100).toFixed(0) : 0
+        };
+    }
+    
+    generateReport() {
+        const health = this.getSubscriptionHealth();
+        const monthlySpend = this.getTotalMonthlySpend();
+        const annualSpend = this.getAnnualSpend();
+        const upcoming = this.getUpcomingPayments();
+        
+        console.log("\n=== SUBSCRIPTION ANALYSIS REPORT ===");
+        console.log(`\nHealth Score: ${health.healthScore}%`);
+        console.log(`Total Subscriptions: ${health.total}`);
+        console.log(`  Active: ${health.active}`);
+        console.log(`  Inactive: ${health.inactive}`);
+        
+        console.log(`\nSpending:`);
+        console.log(`  Monthly: ${monthlySpend.toFixed(2)} RUB`);
+        console.log(`  Annual: ${annualSpend.toFixed(2)} RUB`);
+        
+        console.log(`\nUpcoming Payments (next 30 days):`);
+        if (upcoming.length === 0) {
+            console.log(`  None`);
+        } else {
+            upcoming.forEach(sub => {
+                const date = new Date(sub.next_billing_date).toLocaleDateString();
+                const amount = (sub.subscription_amount / 100).toFixed(2);
+                console.log(`  ${date}: ${sub.subscription_key} - ${amount} ${sub.subscription_currency}`);
+            });
+        }
+        
+        console.log("\n" + "=".repeat(40));
+        
+        return {
+            health,
+            spending: { monthly: monthlySpend, annual: annualSpend },
+            upcomingPayments: upcoming
+        };
+    }
+}
+
+// Usage
+async function analyzeSubscriptions() {
+    const result = await behindAPI.V21.payments.subscriptions.getList();
+    
+    if (result.success && result.data.length > 0) {
+        const analyzer = new SubscriptionAnalyzer(result.data);
+        return analyzer.generateReport();
+    }
+    
+    console.log("No subscriptions to analyze");
+    return null;
+}
+
+const report = await analyzeSubscriptions();
+```
+
+### Subscription Status Monitor
+
+```javascript
+// Example: Monitor subscription status and send alerts
+class SubscriptionMonitor {
+    constructor(checkIntervalMinutes = 60) {
+        this.checkInterval = checkIntervalMinutes * 60 * 1000;
+        this.lastCheck = null;
+        this.alertCallbacks = [];
+    }
+    
+    async startMonitoring() {
+        console.log("Starting subscription monitoring...");
+        
+        await this.checkSubscriptions();
+        
+        setInterval(async () => {
+            await this.checkSubscriptions();
+        }, this.checkInterval);
+    }
+    
+    async checkSubscriptions() {
+        try {
+            const result = await behindAPI.V21.payments.subscriptions.getList();
+            
+            if (!result.success) {
+                console.error("Failed to check subscriptions:", result.message);
+                return;
+            }
+            
+            this.lastCheck = new Date();
+            
+            // Check for issues
+            result.data.forEach(sub => {
+                this.checkPaymentDue(sub);
+                this.checkInactiveSubscription(sub);
+                this.checkFailedPayment(sub);
+            });
+            
+        } catch (error) {
+            console.error("Monitoring error:", error);
+        }
+    }
+    
+    checkPaymentDue(subscription) {
+        const nextBilling = new Date(subscription.next_billing_date);
+        const now = new Date();
+        const daysUntilPayment = (nextBilling - now) / (1000 * 60 * 60 * 24);
+        
+        if (daysUntilPayment <= 3 && daysUntilPayment > 0) {
+            this.alert({
+                type: 'payment_due',
+                severity: 'info',
+                subscription: subscription,
+                message: `Payment due in ${Math.ceil(daysUntilPayment)} day(s) for ${subscription.subscription_key}`,
+                daysRemaining: Math.ceil(daysUntilPayment)
+            });
+        }
+    }
+    
+    checkInactiveSubscription(subscription) {
+        if (!subscription.instance_active && subscription.instance_enabled) {
+            this.alert({
+                type: 'inactive_subscription',
+                severity: 'warning',
+                subscription: subscription,
+                message: `Subscription ${subscription.subscription_key} is enabled but inactive`
+            });
+        }
+    }
+    
+    checkFailedPayment(subscription) {
+        const lastAttempt = new Date(subscription.instance_last_attempt_time);
+        const nextBilling = new Date(subscription.next_billing_date);
+        
+        // If last attempt was after scheduled billing date, payment may have failed
+        if (lastAttempt > nextBilling && !subscription.instance_active) {
+            this.alert({
+                type: 'payment_failed',
+                severity: 'error',
+                subscription: subscription,
+                message: `Payment may have failed for ${subscription.subscription_key}`,
+                lastAttempt: lastAttempt.toISOString()
+            });
+        }
+    }
+    
+    alert(alertData) {
+        console.log(`[${alertData.severity.toUpperCase()}] ${alertData.message}`);
+        
+        // Call registered callbacks
+        this.alertCallbacks.forEach(callback => callback(alertData));
+    }
+    
+    onAlert(callback) {
+        this.alertCallbacks.push(callback);
+    }
+    
+    stopMonitoring() {
+        console.log("Stopping subscription monitoring");
+        clearInterval(this.checkInterval);
+    }
+}
+
+// Usage
+const monitor = new SubscriptionMonitor(60); // Check every hour
+
+monitor.onAlert(alert => {
+    if (alert.severity === 'error') {
+        // Show notification to user
+        showNotification(alert.message, 'error');
+    } else if (alert.severity === 'warning') {
+        console.warn(alert.message);
+    } else {
+        console.info(alert.message);
+    }
+});
+
+monitor.startMonitoring();
+```
+
+### Subscription Comparison Tool
+
+```javascript
+// Example: Compare available plans with user's current subscriptions
+async function compareSubscriptionPlans() {
+    const result = await behindAPI.V21.payments.subscriptions.getList();
+    
+    if (!result.success) {
+        console.error("Failed to fetch subscriptions");
+        return;
+    }
+    
+    const currentSubscriptions = result.data;
+    
+    // Available plans (would typically come from API)
+    const availablePlans = [
+        {
+            key: 'basic-monthly',
+            name: 'Basic Monthly',
+            amount: 1900,
+            currency: 'RUB',
+            interval: 2592000,
+            features: ['Feature 1', 'Feature 2']
+        },
+        {
+            key: 'premium-monthly',
+            name: 'Premium Monthly',
+            amount: 3200,
+            currency: 'RUB',
+            interval: 2592000,
+            features: ['Feature 1', 'Feature 2', 'Feature 3', 'Feature 4']
+        },
+        {
+            key: 'premium-annual',
+            name: 'Premium Annual',
+            amount: 32000,
+            currency: 'RUB',
+            interval: 31536000,
+            features: ['Feature 1', 'Feature 2', 'Feature 3', 'Feature 4', 'Annual Discount']
+        }
+    ];
+    
+    console.log("\n=== SUBSCRIPTION COMPARISON ===\n");
+    
+    availablePlans.forEach(plan => {
+        const isSubscribed = currentSubscriptions.some(sub => 
+            sub.subscription_key === plan.key && sub.instance_active
+        );
+        
+        const monthlyEquivalent = plan.amount / 100 / (plan.interval / 2592000);
+        
+        console.log(`${plan.name}:`);
+        console.log(`  Status: ${isSubscribed ? '✅ SUBSCRIBED' : '❌ Not Subscribed'}`);
+        console.log(`  Price: ${plan.amount / 100} ${plan.currency}`);
+        console.log(`  Monthly Equivalent: ${monthlyEquivalent.toFixed(2)} ${plan.currency}`);
+        console.log(`  Features: ${plan.features.join(', ')}`);
+        console.log();
+    });
+    
+    // Calculate savings for annual plans
+    const monthlyPremium = availablePlans.find(p => p.key === 'premium-monthly');
+    const annualPremium = availablePlans.find(p => p.key === 'premium-annual');
+    
+    if (monthlyPremium && annualPremium) {
+        const monthlyCost = (monthlyPremium.amount / 100) * 12;
+        const annualCost = annualPremium.amount / 100;
+        const savings = monthlyCost - annualCost;
+        const savingsPercent = (savings / monthlyCost * 100).toFixed(0);
+        
+        console.log(`💡 Savings Tip:`);
+        console.log(`   Switch to annual: Save ${savings.toFixed(2)} ${monthlyPremium.currency} (${savingsPercent}%)`);
+    }
+    
+    console.log("\n" + "=".repeat(35));
+}
+
+// Usage
+await compareSubscriptionPlans();
+```
+
+---
+
+## Database Integration
+
+### Database Procedure Called
+The `getList()` method calls:
+```sql
+subscriptions.subscriptions_get(i_user_id)
+```
+
+**Parameters:**
+- `i_user_id` (UUID) - The authenticated user's ID from session
+
+**Returns:**
+Array of subscription instance records with fields:
+- subscription_instance_id
+- subscription_key
+- payment_method
+- subscription_amount
+- subscription_currency
+- subscription_interval
+- instance_last_attempt_time
+- instance_enabled
+- instance_active
+- instance_created_at
+- next_billing_date (calculated)
+
+---
+
+## Testing
+
+### Test Subscription List Retrieval
+
+```javascript
+// Test script for subscriptions list functionality
+async function testSubscriptionsList() {
+    console.log("=== TESTING SUBSCRIPTIONS LIST API ===\n");
+    
+    // Test 1: Fetch subscriptions
+    console.log("Test 1: Fetching user's subscriptions...");
+    const result = await behindAPI.V21.payments.subscriptions.getList();
+    
+    console.log(result.success ? "✓ PASS" : "✗ FAIL");
+    
+    if (result.success) {
+        console.log(`Found ${result.data.length} subscription(s)`);
+        
+        if (result.data.length > 0) {
+            console.log("\nFirst subscription details:");
+            const first = result.data[0];
+            console.log(`  ID: ${first.subscription_instance_id}`);
+            console.log(`  Plan: ${first.subscription_key}`);
+            console.log(`  Amount: ${first.subscription_amount / 100} ${first.subscription_currency}`);
+            console.log(`  Status: ${first.instance_active ? 'Active' : 'Inactive'}`);
+            console.log(`  Payment Method: ${first.payment_method}`);
+            console.log(`  Next Billing: ${first.next_billing_date}`);
+        }
+    } else {
+        console.log(`Error: ${result.message}`);
+    }
+    
+    console.log("\n=== TEST COMPLETE ===");
+}
+
+// Run test
+testSubscriptionsList();
+```
+
+### Mock Subscription Data
+
+```javascript
+// Example mock data for testing UI components
+const mockSubscriptionData = {
+    success: true,
+    data: [
+        {
+            subscription_instance_id: "cc0e8400-e29b-41d4-a716-446655440009",
+            subscription_key: "premium-monthly",
+            payment_method: "payture",
+            subscription_amount: 3200,
+            subscription_currency: "RUB",
+            subscription_interval: 2592000,
+            instance_last_attempt_time: "2024-11-24T09:24:39.880Z",
+            instance_enabled: true,
+            instance_active: true,
+            instance_created_at: "2024-11-01T10:00:00.000Z",
+            next_billing_date: "2024-12-01T10:00:00.000Z"
+        },
+        {
+            subscription_instance_id: "dd0e8400-e29b-41d4-a716-446655440010",
+            subscription_key: "basic-monthly",
+            payment_method: "payture",
+            subscription_amount: 1900,
+            subscription_currency: "RUB",
+            subscription_interval: 2592000,
+            instance_last_attempt_time: "2024-10-15T08:00:00.000Z",
+            instance_enabled: false,
+            instance_active: false,
+            instance_created_at: "2024-09-15T08:00:00.000Z",
+            next_billing_date: "2024-11-15T08:00:00.000Z"
+        }
+    ]
+};
+
+// Use mock data in development
+async function getSubscriptionsWithMock(useMock = false) {
+    if (useMock) {
+        return mockSubscriptionData;
+    }
+    return await behindAPI.V21.payments.subscriptions.getList();
+}
+```
+
+---
+
+## Troubleshooting
+
+### Common Issues and Solutions
+
+**Issue: Subscription shows as active but user doesn't have access**
+```javascript
+// Solution: Verify both instance_active and instance_enabled
+function isSubscriptionFullyActive(subscription) {
+    return subscription.instance_active && 
+           subscription.instance_enabled;
+}
+
+async function verifyUserAccess() {
+    const result = await behindAPI.V21.payments.subscriptions.getList();
+    
+    if (!result.success) {
+        return false;
+    }
+    
+    const activeSubscriptions = result.data.filter(isSubscriptionFullyActive);
+    
+    console.log(`Active subscriptions: ${activeSubscriptions.length}`);
+    
+    return activeSubscriptions.length > 0;
+}
+```
+
+**Issue: Next billing date seems incorrect**
+```javascript
+// Solution: Calculate from last attempt + interval
+function calculateNextBillingDate(subscription) {
+    const lastAttempt = new Date(subscription.instance_last_attempt_time);
+    const intervalMs = subscription.subscription_interval * 1000;
+    
+    return new Date(lastAttempt.getTime() + intervalMs);
+}
+
+// Verify calculated date
+async function verifyBillingDates() {
+    const result = await behindAPI.V21.payments.subscriptions.getList();
+    
+    if (result.success) {
+        result.data.forEach(sub => {
+            const calculated = calculateNextBillingDate(sub);
+            const provided = new Date(sub.next_billing_date);
+            
+            console.log(`${sub.subscription_key}:`);
+            console.log(`  Provided: ${provided.toISOString()}`);
+            console.log(`  Calculated: ${calculated.toISOString()}`);
+            console.log(`  Match: ${calculated.getTime() === provided.getTime()}`);
+        });
+    }
+}
+```
+
+**Issue: Empty subscription list for paying customers**
+```javascript
+// Solution: Debug authentication and database
+async function debugSubscriptionList() {
+    console.log("Debugging subscription list...");
+    
+    // Verify authentication
+    const isAuth = !!sessionStorage.getItem('auth_token');
+    console.log(`Authenticated: ${isAuth}`);
+    
+    if (!isAuth) {
+        console.error("User not authenticated");
+        return;
+    }
+    
+    // Fetch with detailed logging
+    try {
+        const result = await behindAPI.V21.payments.subscriptions.getList();
+        
+        console.log("API Response:", JSON.stringify(result, null, 2));
+        console.log("Success:", result.success);
+        console.log("Subscription count:", result.data?.length || 0);
+        
+        if (result.success && result.data.length > 0) {
+            console.log("Subscription details:");
+            result.data.forEach(sub => {
+                console.log(`  - ${sub.subscription_key}: ${sub.instance_active ? 'Active' : 'Inactive'}`);
+            });
+        }
+        
+    } catch (error) {
+        console.error("Error:", error);
+    }
+}
+```
+
+**Issue: Subscription not updating after payment**
+```javascript
+// Solution: Implement cache invalidation and refresh
+class SubscriptionCache {
+    constructor() {
+        this.subscriptions = [];
+        this.lastFetch = null;
+        this.cacheTimeout = 60000; // 1 minute
+    }
+    
+    async getSubscriptions(forceRefresh = false) {
+        const now = Date.now();
+        
+        if (!forceRefresh && 
+            this.lastFetch && 
+            (now - this.lastFetch) < this.cacheTimeout) {
+            console.log("Returning cached subscriptions");
+            return this.subscriptions;
+        }
+        
+        console.log("Fetching fresh subscriptions...");
+        const result = await behindAPI.V21.payments.subscriptions.getList();
+        
+        if (result.success) {
+            this.subscriptions = result.data;
+            this.lastFetch = now;
+        }
+        
+        return this.subscriptions;
+    }
+    
+    invalidate() {
+        this.lastFetch = null;
+        console.log("Subscription cache invalidated");
+    }
+}
+
+// Usage
+const cache = new SubscriptionCache();
+
+// After payment or subscription change
+cache.invalidate();
+const subscriptions = await cache.getSubscriptions(true);
+```
+
+---
+
+## Security Considerations
+
+1. **Authentication Required**: This endpoint requires valid user session
+2. **User Isolation**: Users can only see their own subscriptions
+3. **Payment Method Security**: Sensitive payment details not included
+4. **HTTPS Only**: All API calls must use HTTPS in production
+5. **Session Validation**: Validate session tokens on every request
+6. **Rate Limiting**: Implement appropriate rate limits
+7. **Data Integrity**: Verify subscription data integrity
+
+```javascript
+// Example: Secure subscription access
+async function getSubscriptionsSecurely() {
+    // Verify session is valid
+    if (!sessionStorage.getItem('auth_token')) {
+        throw new Error("Not authenticated");
+    }
+    
+    // Fetch subscriptions
+    const result = await behindAPI.V21.payments.subscriptions.getList();
+    
+    if (!result.success) {
+        throw new Error("Failed to fetch subscriptions");
+    }
+    
+    // Log access (send to audit service)
+    auditLog({
+        action: 'subscriptions_viewed',
+        timestamp: new Date().toISOString(),
+        count: result.data.length
+    });
+    
+    return result.data;
+}
+```
+
+---
+
+## Integration Examples
+
+### Complete Subscription Lifecycle
+
+```javascript
+// Example: Full subscription management flow
+class SubscriptionManager {
+    async createSubscription(planKey) {
+        // Step 1: Check if user has valid payment method
+        const hasCard = await this.checkPaymentMethod();
+        
+        if (!hasCard) {
+            console.log("No payment method found. Redirecting to setup...");
+            await this.setupPaymentMethod(planKey);
+            return null;
+        }
+        
+        // Step 2: Create subscription instance
+        const result = await behindAPI.V21.payments.subscriptions.subscribe(planKey);
+        
+        if (result.success) {
+            console.log("✅ Subscription created successfully!");
+            return result.data.subscription_instance_id;
+        } else {
+            console.error("❌ Failed to create subscription:", result.message);
+            return null;
+        }
+    }
+    
+    async checkPaymentMethod() {
+        const cards = await behindAPI.V21.payments.cards.getList();
+        
+        if (!cards.success || cards.data.length === 0) {
+            return false;
+        }
+        
+        // Check for valid active cards
+        const validCards = cards.data.filter(card => 
+            card.is_active && 
+            card.response.Status === "IsActive" &&
+            card.response.Expired === "false"
+        );
+        
+        return validCards.length > 0;
+    }
+    
+    async setupPaymentMethod(planKey) {
+        const init = await behindAPI.V21.payments.payture.init();
+        
+        if (init.success) {
+            // Store pending subscription
+            sessionStorage.setItem('pending_subscription', planKey);
+            sessionStorage.setItem('card_registration_pending', 'true');
+            
+            // Redirect to card registration
+            window.location.href = init.data.RedirectUrl;
+        } else {
+            console.error("Failed to initialize payment setup");
+        }
+    }
+    
+    async listSubscriptions() {
+        const result = await behindAPI.V21.payments.subscriptions.getList();
+        
+        if (result.success) {
+            return result.data;
+        }
+        
+        return [];
+    }
+    
+    async getActiveSubscriptions() {
+        const all = await this.listSubscriptions();
+        return all.filter(sub => sub.instance_active && sub.instance_enabled);
+    }
+    
+    async hasActiveSubscription(planKey) {
+        const active = await this.getActiveSubscriptions();
+        return active.some(sub => sub.subscription_key === planKey);
+    }
+}
+
+// Usage
+const manager = new SubscriptionManager();
+
+// Create new subscription
+const subscriptionId = await manager.createSubscription("premium-monthly");
+
+// List all subscriptions
+const subscriptions = await manager.listSubscriptions();
+
+// Check if user has specific subscription
+const hasPremium = await manager.hasActiveSubscription("premium-monthly");
+```
+
+---
+
+## API Reference Summary
+
+| Method | Authorization Required | Parameters | Returns |
+|--------|----------------------|------------|---------|
+| `getList` | Yes | None | Array of subscription instances |
+| `subscribe` | Yes | subscriptionId | subscription_instance_id |
+
+---
+
+## Support and Resources
+
+For additional help:
+- **API Documentation**: Refer to the main Payments API V21 documentation
+- **Database Schema**: Check subscription_instances table structure
+- **Related Endpoints**:
+    - `/payments/V21/payture/init` - Initialize card registration
+    - `/payments/V21/payture/finalise` - Finalize card after registration
+    - `/payments/V21/cards/getList` - Manage payment methods
+    - `/payments/V21/subscriptions/subscribe` - Create new subscriptions
+- **Database Procedures**:
+    - `subscriptions.subscriptions_get` - Retrieve subscriptions
+    - `subscriptions.subscription_instance_create` - Create instances
+- **Support**: Contact your technical support team for integration assistance