node-behind-api-client 2.0.48

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

@@ -0,0 +1,901 @@
+# Payments API V21 - Payture Endpoint
+
+This document provides detailed information about the Payture payment gateway integration methods for the V21 Payments API.
+
+## Overview
+
+The Payture Payments API V21 provides methods for initializing payment sessions through the Payture EWallet gateway. This includes creating payment sessions for both authorized and unauthorized users, managing customer accounts, and handling subscription payment flows with card registration.
+
+---
+
+## Payments API V21 - Payture Methods
+
+### behindAPI.V21.payments.payture.init()
+Initializes a payment session for an authorized user.
+
+**Parameters:**
+- None (uses authenticated user session)
+
+**Authorization:**
+- Required: No (but uses session if available)
+
+**Usage:**
+```javascript
+const result = await behindAPI.V21.payments.payture.init();
+
+// Response:
+{
+    success: true,
+        data: {
+    Success: "True",
+        Amount: "10.00",
+        SessionLifeTime: "60",
+        AttemptsCount: "5",
+        SessionId: "38ff74a9-c37c-42ba-a38a-bca05afecfc9",
+        SessionType: "Add",
+        RedirectUrl: "https://sandbox3.payture.com/vwapi/Add?SessionId=38ff74a9-c37c-42ba-a38a-bca05afecfc9",
+        Cmd: "Init"
+}
+}
+
+// Error Response:
+{
+    success: false,
+        message: "Can't finish request",
+    e: { /* error details */ }
+}
+```
+
+### behindAPI.V21.payments.payture.initUnauthorised(userId)
+Authorizes payment for a user subscription through Payture EWallet. Creates or verifies user wallet, registers customer in Payture, and initializes payment session for card registration.
+
+**Parameters:**
+- `userId` (string, required) - User ID for payment authorization
+
+**Authorization:**
+- Required: No
+
+**Usage:**
+```javascript
+const result = await behindAPI.V21.payments.payture.initUnauthorised(
+    "550e8400-e29b-41d4-a716-446655440001"
+);
+
+// Response:
+{
+    success: true,
+    data: {
+        Success: "True",
+        Amount: "10.00",
+        SessionLifeTime: "60",
+        AttemptsCount: "5",
+        SessionId: "38ff74a9-c37c-42ba-a38a-bca05afecfc9",
+        SessionType: "Add",
+        RedirectUrl: "https://sandbox3.payture.com/vwapi/Add?SessionId=38ff74a9-c37c-42ba-a38a-bca05afecfc9",
+        Cmd: "Init"
+    }
+}
+
+// Error Response:
+{
+    success: false,
+    message: "Can't finish request",
+    e: { /* error details */ }
+}
+```
+
+### behindAPI.V21.payments.payture.finalise()
+Finalizes the payment process after card registration. Retrieves user's card list from Payture, selects the first active card that doesn't require CVV and isn't expired, and saves it to the database.
+
+**Parameters:**
+- None (uses authenticated user session)
+
+**Authorization:**
+- Required: No (but uses session)
+
+**Usage:**
+```javascript
+const result = await behindAPI.V21.payments.payture.finalise();
+
+// Success Response (with active card):
+{
+    success: true,
+    data: {
+        card: {
+            CardName: "411111******1111",
+            CardHolder: "JOHN DOE",
+            Status: "IsActive",
+            NoCVV: "false",
+            Expired: "false"
+            // Note: CardId is removed for security
+        }
+    }
+}
+
+// Error Response (no active card):
+{
+    success: false,
+    message: "No active card found"
+}
+
+// Error Response (can't get cards):
+{
+    success: false,
+    message: "Can't get card list",
+    e: { /* error details */ }
+}
+```
+
+---
+
+## Data Structure Reference
+
+### Payment Initialization Response
+The `init()` and `initUnauthorised()` methods return:
+
+**Success Response:**
+- `success` (boolean) - Always `true` for successful requests
+- `data` (object) - Payture response data
+    - `Success` (string) - Payture success indicator ("True"/"False")
+    - `Amount` (string) - Payment amount in rubles (e.g., "10.00")
+    - `SessionLifeTime` (string) - Session lifetime in minutes (e.g., "60")
+    - `AttemptsCount` (string) - Number of payment attempts allowed (e.g., "5")
+    - `SessionId` (UUID string) - Unique payment session ID
+    - `SessionType` (string) - Session type ("Add" for card registration)
+    - `RedirectUrl` (string) - URL to redirect user for payment/card registration
+    - `Cmd` (string) - Command type ("Init")
+
+**Error Response:**
+- `success` (boolean) - Always `false` for failed requests
+- `message` (string) - Error description
+- `e` (object) - Error details
+
+### Subscription Creation Response
+The `finalise()` method returns:
+
+**Success Response:**
+- `success` (boolean) - Always `true` for successful requests
+- `data` (object) - Container for response data
+    - `card` (object) - Selected active card information
+        - `CardName` (string) - Masked card number (e.g., "411111******1111")
+        - `CardHolder` (string) - Cardholder name
+        - `Status` (string) - Card status ("IsActive")
+        - `NoCVV` (string) - Whether CVV is required ("true"/"false")
+        - `Expired` (string) - Whether card is expired ("true"/"false")
+
+**Error Response:**
+- `success` (boolean) - Always `false` for failed requests
+- `message` (string) - Error description ("No active card found", "Can't get card list")
+- `e` (object, optional) - Error details
+
+---
+
+## Complete Usage Examples
+
+### Basic Payment Initialization for Guest Users
+
+```javascript
+// Example: Initialize payment for guest user
+async function initializeGuestPayment(userId) {
+    try {
+        console.log("Initializing payment session...");
+        
+        const result = await behindAPI.V21.payments.payture.initUnauthorised(userId);
+        
+        if (result.success) {
+            console.log("✓ Payment session initialized!");
+            console.log(`Session ID: ${result.data.SessionId}`);
+            console.log(`Payment URL: ${result.data.RedirectUrl}`);
+            console.log(`Session lifetime: ${result.data.SessionLifeTime} minutes`);
+            
+            // Redirect user to Payture for card registration
+            window.location.href = result.data.RedirectUrl;
+            
+            return result.data;
+        } else {
+            console.log(`✗ Failed to initialize payment: ${result.message}`);
+            return null;
+        }
+    } catch (error) {
+        console.error("Error initializing payment:", error);
+        return null;
+    }
+}
+
+// Usage
+const sessionData = await initializeGuestPayment(
+    "aa0e8400-e29b-41d4-a716-446655440005"
+);
+```
+
+### Payment Initialization for Authorized Users
+
+```javascript
+// Example: Initialize payment for logged-in user
+async function initializeUserPayment() {
+    try {
+        console.log("Initializing payment for authorized user...");
+        
+        const result = await behindAPI.V21.payments.payture.init();
+        
+        if (result.success) {
+            console.log("✓ Payment session ready!");
+            console.log(`Redirect URL: ${result.data.RedirectUrl}`);
+            
+            // Store session ID for later reference
+            sessionStorage.setItem('payture_session_id', result.data.SessionId);
+            
+            // Open in new window or redirect
+            const paymentWindow = window.open(result.data.RedirectUrl, '_blank');
+            
+            if (!paymentWindow || paymentWindow.closed) {
+                // Fallback to same-window redirect
+                window.location.href = result.data.RedirectUrl;
+            }
+            
+            return result.data;
+        } else {
+            console.error(`✗ Initialization failed: ${result.message}`);
+            return null;
+        }
+    } catch (error) {
+        console.error("Error:", error);
+        return null;
+    }
+}
+
+// Usage
+const paymentData = await initializeUserPayment();
+```
+
+### Complete Card Registration and Finalization Flow
+
+```javascript
+// Example: Register card and finalize after callback
+async function registerAndFinalizeCard() {
+    try {
+        console.log("Step 1: Initializing card registration...");
+        
+        const initResult = await behindAPI.V21.payments.payture.init();
+        
+        if (!initResult.success) {
+            console.error(`✗ Initialization failed: ${initResult.message}`);
+            return null;
+        }
+        
+        console.log("✓ Card registration session initialized!");
+        console.log(`Redirect URL: ${initResult.data.RedirectUrl}`);
+        
+        // Store session data
+        sessionStorage.setItem('payture_session_id', initResult.data.SessionId);
+        sessionStorage.setItem('card_registration_pending', 'true');
+        
+        // Redirect user to Payture
+        window.location.href = initResult.data.RedirectUrl;
+        
+        return initResult.data;
+        
+    } catch (error) {
+        console.error("Error:", error);
+        return null;
+    }
+}
+
+// After user returns from Payture (in callback page)
+async function finalizeCardRegistration() {
+    try {
+        console.log("Step 2: Finalizing card registration...");
+        
+        // Check if there's a pending registration
+        const isPending = sessionStorage.getItem('card_registration_pending');
+        
+        if (!isPending) {
+            console.log("No pending card registration");
+            return null;
+        }
+        
+        // Parse callback parameters
+        const params = new URLSearchParams(window.location.search);
+        const success = params.get('result');
+        
+        if (success !== 'True') {
+            console.error("Card registration was not successful");
+            sessionStorage.removeItem('card_registration_pending');
+            return null;
+        }
+        
+        // Finalize the registration
+        const finalizeResult = await behindAPI.V21.payments.payture.finalise();
+        
+        if (finalizeResult.success) {
+            console.log("✓ Card registered successfully!");
+            console.log(`Card: ${finalizeResult.data.card.CardName}`);
+            console.log(`Holder: ${finalizeResult.data.card.CardHolder}`);
+            
+            // Clear pending flag
+            sessionStorage.removeItem('card_registration_pending');
+            
+            return {
+                cardInfo: {
+                    maskedNumber: finalizeResult.data.card.CardName,
+                    holder: finalizeResult.data.card.CardHolder
+                }
+            };
+        } else {
+            console.log(`✗ Failed to finalize: ${finalizeResult.message}`);
+            
+            if (finalizeResult.message === "No active card found") {
+                console.log("No valid card was registered. Please try again.");
+            }
+            
+            return null;
+        }
+    } catch (error) {
+        console.error("Error finalizing card registration:", error);
+        return null;
+    }
+}
+
+// Usage on main page - Start registration
+await registerAndFinalizeCard();
+
+// Usage on callback page - Complete registration
+const cardData = await finalizeCardRegistration();
+if (cardData) {
+    // Proceed with subscription creation
+    window.location.href = '/create-subscription';
+}
+```
+
+### Complete Payment Flow with Two-Step Process
+
+```javascript
+// Example: Full payment flow - card registration, finalization, and subscription creation
+async function completePaymentFlow(userId, subscriptionId) {
+    const flow = {
+        step: 1,
+        status: "starting",
+        data: {}
+    };
+    
+    try {
+        // Step 1: Initialize payment session
+        console.log("Step 1: Initializing card registration...");
+        flow.step = 1;
+        
+        const initResult = await behindAPI.V21.payments.payture.initUnauthorised(userId);
+        
+        if (!initResult.success) {
+            flow.status = "failed_init";
+            flow.error = initResult.message;
+            return flow;
+        }
+        
+        flow.data.sessionId = initResult.data.SessionId;
+        flow.data.redirectUrl = initResult.data.RedirectUrl;
+        console.log("✓ Session initialized");
+        
+        // Step 2: Redirect user for card registration
+        console.log("Step 2: Redirecting to Payture...");
+        flow.step = 2;
+        
+        // Store flow data before redirect
+        sessionStorage.setItem('payment_flow', JSON.stringify(flow));
+        sessionStorage.setItem('pending_subscription', subscriptionId);
+        sessionStorage.setItem('card_registration_pending', 'true');
+        
+        // Redirect user
+        window.location.href = initResult.data.RedirectUrl;
+        
+        // AFTER USER RETURNS FROM PAYTURE (in callback handler):
+        
+        // Step 3: Finalize card registration
+        console.log("Step 3: Finalizing card registration...");
+        flow.step = 3;
+        
+        const finalizeResult = await behindAPI.V21.payments.payture.finalise();
+        
+        if (!finalizeResult.success) {
+            flow.status = "failed_finalize";
+            flow.error = finalizeResult.message;
+            return flow;
+        }
+        
+        flow.data.cardInfo = finalizeResult.data.card;
+        console.log("✓ Card registered and saved");
+        
+        // Step 4: Create subscription instance
+        console.log("Step 4: Creating subscription...");
+        flow.step = 4;
+        
+        const subscriptionResult = await behindAPI.V21.payments.subscriptions.create(
+            subscriptionId
+        );
+        
+        if (!subscriptionResult.success) {
+            flow.status = "failed_subscription";
+            flow.error = subscriptionResult.message;
+            return flow;
+        }
+        
+        flow.data.subscriptionId = subscriptionResult.data.subscription_instance_id;
+        flow.status = "completed";
+        console.log("✓ Payment flow completed successfully");
+        
+        return flow;
+        
+    } catch (error) {
+        console.error(`Error at step ${flow.step}:`, error);
+        flow.status = "error";
+        flow.error = error.message;
+        return flow;
+    }
+}
+
+// Usage on main page
+const result = await completePaymentFlow(
+    "aa0e8400-e29b-41d4-a716-446655440005",
+    "premium-monthly"
+);
+
+// Usage on callback page (after Payture redirect)
+async function handlePaymentCallback() {
+    const urlParams = new URLSearchParams(window.location.search);
+    const orderid = urlParams.get('orderid');
+    const success = urlParams.get('result');
+    
+    if (success === 'True') {
+        console.log("Card registration successful, finalizing...");
+        
+        // Step 1: Finalize card registration
+        const finalizeResult = await behindAPI.V21.payments.payture.finalise();
+        
+        if (!finalizeResult.success) {
+            console.error("Failed to finalize card:", finalizeResult.message);
+            window.location.href = '/error?reason=card_finalization_failed';
+            return;
+        }
+        
+        console.log("Card finalized successfully!");
+        
+        // Step 2: Create subscription if there's a pending one
+        const subscriptionId = sessionStorage.getItem('pending_subscription');
+        
+        if (subscriptionId) {
+            console.log("Creating subscription...");
+            
+            const subscriptionResult = await behindAPI.V21.payments.subscriptions.create(
+                subscriptionId
+            );
+            
+            if (subscriptionResult.success) {
+                console.log("Subscription created!");
+                sessionStorage.removeItem('pending_subscription');
+                sessionStorage.removeItem('card_registration_pending');
+                // Redirect to success page
+                window.location.href = '/subscription-success';
+            } else {
+                console.error("Failed to create subscription:", subscriptionResult.message);
+                window.location.href = '/error?reason=subscription_creation_failed';
+            }
+        } else {
+            // No subscription to create, just card registration
+            sessionStorage.removeItem('card_registration_pending');
+            window.location.href = '/cards-success';
+        }
+    } else {
+        console.log("Card registration was not successful");
+        sessionStorage.removeItem('card_registration_pending');
+        window.location.href = '/error?reason=card_registration_failed';
+    }
+}
+```
+
+### Handling Card Registration Callbacks
+
+```javascript
+// Example: Process callback after card registration using finalise
+class PaytureCallbackHandler {
+    constructor() {
+        this.processCallback();
+    }
+    
+    async processCallback() {
+        try {
+            // Parse URL parameters
+            const params = new URLSearchParams(window.location.search);
+            const orderId = params.get('orderid');
+            const success = params.get('result');
+            
+            console.log(`Order ID: ${orderId}`);
+            console.log(`Success: ${success}`);
+            
+            if (success !== 'True') {
+                this.handleFailure("Card registration was cancelled or failed");
+                return;
+            }
+            
+            // Wait a bit for Payture to process
+            await this.sleep(2000);
+            
+            // Step 1: Finalize card registration
+            console.log("Finalizing card registration...");
+            const finalizeResult = await behindAPI.V21.payments.payture.finalise();
+            
+            if (!finalizeResult.success) {
+                this.handleFailure(finalizeResult.message);
+                return;
+            }
+            
+            console.log("Card registered successfully!");
+            
+            // Step 2: Check if there's a pending subscription to create
+            const subscriptionId = sessionStorage.getItem('pending_subscription');
+            
+            if (subscriptionId) {
+                console.log("Creating subscription...");
+                
+                const subscriptionResult = await behindAPI.V21.payments.subscriptions.create(
+                    subscriptionId
+                );
+                
+                if (subscriptionResult.success) {
+                    this.handleSuccess(finalizeResult.data, subscriptionResult.data);
+                } else {
+                    this.handleFailure(subscriptionResult.message);
+                }
+            } else {
+                // No subscription, just card registration
+                this.handleCardOnlySuccess(finalizeResult.data);
+            }
+            
+        } catch (error) {
+            console.error("Callback processing error:", error);
+            this.handleFailure(error.message);
+        }
+    }
+    
+    handleSuccess(cardData, subscriptionData) {
+        console.log("✓ Subscription activated!");
+        console.log(`Subscription ID: ${subscriptionData.subscription_instance_id}`);
+        console.log(`Card: ${cardData.card.CardName}`);
+        
+        // Clear session data
+        sessionStorage.removeItem('pending_subscription');
+        sessionStorage.removeItem('payment_flow');
+        sessionStorage.removeItem('card_registration_pending');
+        
+        // Show success message
+        this.showMessage(
+            `Your subscription has been activated! Card: ${cardData.card.CardName}`,
+            'success'
+        );
+        
+        // Redirect after delay
+        setTimeout(() => {
+            window.location.href = '/dashboard';
+        }, 3000);
+    }
+    
+    handleCardOnlySuccess(cardData) {
+        console.log("✓ Card registered successfully!");
+        console.log(`Card: ${cardData.card.CardName}`);
+        
+        // Clear session data
+        sessionStorage.removeItem('card_registration_pending');
+        
+        // Show success message
+        this.showMessage(
+            `Card registered successfully: ${cardData.card.CardName}`,
+            'success'
+        );
+        
+        // Redirect after delay
+        setTimeout(() => {
+            window.location.href = '/cards';
+        }, 3000);
+    }
+    
+    handleFailure(message = "Payment failed") {
+        console.error("✗ Process failed:", message);
+        
+        // Clear pending flags
+        sessionStorage.removeItem('card_registration_pending');
+        
+        this.showMessage(
+            `Failed: ${message}. Please try again.`,
+            'error'
+        );
+        
+        // Redirect after delay
+        setTimeout(() => {
+            window.location.href = '/subscribe';
+        }, 3000);
+    }
+    
+    showMessage(text, type = 'info') {
+        // Implement your UI message display
+        console.log(`[${type.toUpperCase()}] ${text}`);
+    }
+    
+    sleep(ms) {
+        return new Promise(resolve => setTimeout(resolve, ms));
+    }
+}
+
+// Initialize on callback page
+if (window.location.pathname === '/payment/callback') {
+    new PaytureCallbackHandler();
+}
+```
+
+---
+
+## Internal Process Flow
+
+### Customer Registration Process
+1. **Check Wallet**: System verifies user has RUB wallet
+2. **Create Wallet**: Creates RUB wallet if needed
+3. **Register Customer**: Registers customer in Payture with credentials
+    - Username: `customer-{user_id}`
+    - Password: MD5 hash of `{user_id}{salt}`
+4. **Initialize Session**: Creates payment session for card registration
+
+### Card Selection Logic
+The `createSubscription()` method selects cards based on:
+- `Status`: Must be "IsActive"
+- `NoCVV`: Must be "false" (CVV not required for recurring)
+- `Expired`: Must be "false"
+- Selection: First matching card is used
+
+### Session Parameters
+Payment sessions are initialized with:
+- **Amount**: 1000 kopecks (10.00 RUB) - test amount for card verification
+- **SessionType**: "Add" - for card registration
+- **Product**: "Ru-kitchen.ru"
+- **Description**: "Monthly subscription for premium content"
+
+---
+
+## Testing
+
+### Test Environment Setup
+```javascript
+// Configure test environment
+const TEST_CONFIG = {
+    testUserId: "test-user-000000000000000000000001",
+    testSubscriptionId: "test-premium-monthly",
+    callbackUrl: "http://localhost:3000/payment/callback"
+};
+
+// Test payment initialization
+async function testPaymentInit() {
+    console.log("=== TESTING PAYMENT INITIALIZATION ===\n");
+    
+    // Test 1: Unauthorized init
+    console.log("Test 1: Initialize payment for guest...");
+    const initResult = await behindAPI.V21.payments.payture.initUnauthorised(
+        TEST_CONFIG.testUserId
+    );
+    
+    console.log(initResult.success ? "✓ PASS" : "✗ FAIL");
+    if (initResult.success) {
+        console.log(`Session ID: ${initResult.data.SessionId}`);
+        console.log(`Redirect URL: ${initResult.data.RedirectUrl}\n`);
+    }
+    
+    // Test 2: Authorized init
+    console.log("Test 2: Initialize payment for authorized user...");
+    const authInitResult = await behindAPI.V21.payments.payture.init();
+    
+    console.log(authInitResult.success ? "✓ PASS" : "✗ FAIL\n");
+    
+    console.log("=== TESTS COMPLETE ===");
+}
+
+// Test subscription creation
+async function testSubscriptionCreation() {
+    console.log("=== TESTING SUBSCRIPTION CREATION ===\n");
+    
+    console.log("Test: Create subscription with card...");
+    const result = await behindAPI.V21.payments.payture.createSubscription(
+        TEST_CONFIG.testSubscriptionId
+    );
+    
+    if (result.success) {
+        console.log("✓ PASS");
+        console.log(`Subscription ID: ${result.data.subscription_instance_id}`);
+        console.log(`Card: ${result.data.card.CardName}`);
+    } else {
+        console.log("✗ FAIL");
+        console.log(`Error: ${result.message}`);
+    }
+    
+    console.log("\n=== TEST COMPLETE ===");
+}
+
+// Run tests
+testPaymentInit();
+```
+
+---
+
+## Troubleshooting
+
+### Common Issues and Solutions
+
+**Issue: Payment session expired before user completed registration**
+```javascript
+// Solution: Check session lifetime and warn user
+async function initWithExpiryWarning(userId) {
+    const result = await behindAPI.V21.payments.payture.initUnauthorised(userId);
+    
+    if (result.success) {
+        const sessionMinutes = parseInt(result.data.SessionLifeTime);
+        
+        alert(`Please complete payment within ${sessionMinutes} minutes`);
+        
+        // Set warning timer
+        setTimeout(() => {
+            alert("Payment session will expire soon!");
+        }, (sessionMinutes - 5) * 60 * 1000); // Warn 5 minutes before expiry
+        
+        window.location.href = result.data.RedirectUrl;
+    }
+}
+```
+
+**Issue: No active cards found when finalizing**
+```javascript
+// Solution: Guide user to register a new card
+async function finalizeWithFallback() {
+    const result = await behindAPI.V21.payments.payture.finalise();
+    
+    if (!result.success && result.message === "No active card found") {
+        console.log("No card was registered. Redirecting to card registration...");
+        
+        // Initialize new card registration session
+        const initResult = await behindAPI.V21.payments.payture.init();
+        
+        if (initResult.success) {
+            window.location.href = initResult.data.RedirectUrl;
+        }
+    } else if (result.success) {
+        console.log("Card finalized successfully!");
+        return result.data;
+    }
+}
+```
+
+**Issue: Wallet not created for user**
+```javascript
+// Solution: Ensure wallet creation is successful
+async function verifyWalletBeforePayment(userId) {
+    try {
+        // The initUnauthorised method handles wallet creation automatically,
+        // but you can verify by checking the response
+        const result = await behindAPI.V21.payments.payture.initUnauthorised(userId);
+        
+        if (!result.success) {
+            console.error("Failed to initialize payment. Wallet may not exist.");
+            // Attempt manual wallet creation through separate API if available
+        }
+        
+        return result;
+    } catch (error) {
+        console.error("Wallet verification error:", error);
+        return { success: false, message: error.message };
+    }
+}
+```
+
+**Issue: Callback URL parameters not being processed**
+```javascript
+// Solution: Robust parameter parsing
+function parseCallbackParams() {
+    const params = new URLSearchParams(window.location.search);
+    
+    const data = {
+        orderId: params.get('orderid'),
+        success: params.get('result'),
+        timestamp: Date.now()
+    };
+    
+    // Validate parameters
+    if (!data.orderId) {
+        console.error("Missing order ID in callback");
+        return null;
+    }
+    
+    // Normalize success value
+    data.success = data.success === 'True' || data.success === 'true' || data.success === '1';
+    
+    console.log("Callback parameters:", data);
+    return data;
+}
+
+// Usage in callback handler
+const callbackData = parseCallbackParams();
+if (callbackData && callbackData.success) {
+    // Process successful payment
+}
+```
+
+---
+
+## Security Considerations
+
+1. **Customer Credentials**: User passwords are hashed with MD5 and salt
+2. **Session Security**: Payment sessions have limited lifetime (typically 60 minutes)
+3. **Card Storage**: Card IDs are removed from responses for security
+4. **HTTPS Required**: All redirect URLs must use HTTPS in production
+5. **Rate Limiting**: Implement rate limiting on payment initialization
+6. **Input Validation**: Always validate UUIDs and user IDs
+7. **Error Handling**: Don't expose sensitive error details to users
+8. **Audit Logging**: Log all payment operations
+
+```javascript
+// Example: Secure payment initialization with validation
+async function securePaymentInit(userId) {
+    // Validate UUID format
+    const uuidRegex = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+    
+    if (!uuidRegex.test(userId)) {
+        return { 
+            success: false, 
+            message: "Invalid user ID format" 
+        };
+    }
+    
+    // Check rate limit
+    const rateLimitKey = `payment_init_${userId}`;
+    const attempts = parseInt(sessionStorage.getItem(rateLimitKey) || '0');
+    
+    if (attempts >= 5) {
+        return { 
+            success: false, 
+            message: "Too many attempts. Please try again later." 
+        };
+    }
+    
+    // Increment attempt counter
+    sessionStorage.setItem(rateLimitKey, (attempts + 1).toString());
+    
+    // Initialize payment
+    const result = await behindAPI.V21.payments.payture.initUnauthorised(userId);
+    
+    // Log the operation (send to your logging service)
+    logPaymentOperation({
+        action: 'payment_init',
+        userId: userId,
+        success: result.success,
+        timestamp: new Date().toISOString()
+    });
+    
+    return result;
+}
+```
+
+---
+
+## API Reference Summary
+
+| Method | Authorization Required | Parameters | Returns |
+|--------|----------------------|------------|---------|
+| `init` | No | None | SessionId, RedirectUrl, SessionLifeTime |
+| `initUnauthorised` | No | userId | SessionId, RedirectUrl, SessionLifeTime |
+| `finalise` | No (uses session) | None | card |
+
+---
+
+## Support and Resources
+
+For additional help:
+- **API Documentation**: Refer to the main Payments API V21 documentation
+- **Payture Documentation**: Check Payture's official EWallet API documentation
+- **Database Procedures**:
+    - `escrow.tr_account_get_default` - Get user wallet
+    - `public.create_simple_wallet` - Create wallet
+    - `escrow.payment_method_create` - Save payment method
+- **Support**: Contact your technical support team for integration assistance
+- **Testing**: Always use sandbox environment before production deployment