node-behind-api-client 2.0.48

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

@@ -0,0 +1,1497 @@
+# Payments API - Payture Extension
+
+This document extends the main EasyJob JavaScript API Client Documentation with detailed information about the Payture payment gateway integration methods.
+
+## Overview
+
+The Payture Payments API provides methods for creating and managing payment bills through the Payture payment gateway. This includes creating bills for authorized and unauthorized users, checking bill status, and handling payment workflows for subscriptions and gift purchases.
+
+---
+
+## Payments API - Payture
+
+### behindAPI.V20.payments.payture.billCreate(subscriptionId)
+Creates a payment bill for an authorized user subscribing to a product.
+
+**Parameters:**
+- `subscriptionId` (string, required) - The subscription product UUID to create a bill for
+
+**Usage:**
+```javascript
+const result = await behindAPI.V20.payments.payture.billCreate(
+    "550e8400-e29b-41d4-a716-446655440001"
+);
+
+// Response:
+{
+    success: true,
+    data: {
+        bill_id: "cc0e8400-e29b-41d4-a716-446655440009",
+        bill: {
+            payUrl: "https://payture.com/apim/Pay?SessionId=abc123xyz"
+        }
+    }
+}
+
+// Error Response:
+{
+    success: false,
+    message: "Can't finish request"
+}
+```
+
+### behindAPI.V20.payments.payture.billCreateUnauthorised(subscriptionId, userId, redirectUrl, extended)
+Creates a payment bill for an unauthorized user or allows specifying custom parameters. This method is useful for guest checkouts or when you need to pass additional data with the payment.
+
+**Parameters:**
+- `subscriptionId` (string, required) - The subscription product UUID to create a bill for
+- `userId` (string, required) - The user UUID who is making the purchase
+- `redirectUrl` (string, optional) - Custom URL to redirect after payment completion. Must be a valid HTTP/HTTPS URL
+- `extended` (object, optional) - Additional data to store with the bill (e.g., gift recipient info, page access details)
+
+**Usage:**
+```javascript
+const result = await behindAPI.V20.payments.payture.billCreateUnauthorised(
+    "550e8400-e29b-41d4-a716-446655440001", // subscription_id
+    "aa0e8400-e29b-41d4-a716-446655440005", // user_id
+    "https://example.com/payment-complete", // redirect_url
+    {
+        pageId: "ck4jrtawdA3Ed4",
+        giftRecipient: "john@example.com",
+        customNote: "Holiday special"
+    } // extended
+);
+
+// Response:
+{
+    success: true,
+    data: {
+        bill_id: "cc0e8400-e29b-41d4-a716-446655440009",
+        bill: {
+            payUrl: "https://payture.com/apim/Pay?SessionId=abc123xyz"
+        }
+    }
+}
+
+// Error Response:
+{
+    success: false,
+    message: "Can't finish request"
+}
+```
+
+### behindAPI.V20.payments.payture.billStatus(billId)
+Retrieves the current status of a payment bill and processes completed payments. This method checks the bill status with Payture and updates the local database accordingly.
+
+**Parameters:**
+- `billId` (string, required) - The bill UUID to check status for
+
+**Usage:**
+```javascript
+const result = await behindAPI.V20.payments.payture.billStatus(
+    "cc0e8400-e29b-41d4-a716-446655440009"
+);
+
+// Response (pending payment):
+{
+    success: true,
+    data: {
+        bill_info: {
+            bill_status: "PENDING",
+            amount: 99900
+        },
+        status: "PENDING"
+    }
+}
+
+// Response (successful payment):
+{
+    success: true,
+    data: {
+        bill_info: {
+            bill_status: "PAID",
+            amount: 99900
+        },
+        status: "PAID"
+    }
+}
+
+// Response (gift purchase - includes gift code):
+{
+    success: true,
+    data: {
+        bill_info: {
+            bill_status: "PAID",
+            amount: 99900,
+            gift: {
+                code: "GIFT-ABC123"
+            }
+        },
+        status: "PAID"
+    }
+}
+
+// Error Response (empty bill_id):
+{
+    success: false,
+    message: "bill_id can not be empty"
+}
+
+// Error Response (amount mismatch):
+{
+    success: false,
+    data: {
+        bill_info: {
+            bill_status: "PAID",
+            amount: 99900
+        },
+        status: "AMOUNT_MISMATCH"
+    }
+}
+```
+
+---
+
+## Data Structure Reference
+
+### Bill Creation Response
+The `billCreate()` and `billCreateUnauthorised()` methods return:
+
+**Success Response:**
+- `success` (boolean) - Always `true` for successful requests
+- `data` (object) - Container for response data
+    - `bill_id` (UUID) - The newly created bill's unique identifier
+    - `bill` (object) - Bill details
+        - `payUrl` (string) - URL to redirect user for payment
+
+**Error Response:**
+- `success` (boolean) - Always `false` for failed requests
+- `message` (string) - Error description
+
+### Bill Status Response
+The `billStatus()` method returns:
+
+**Success Response:**
+- `success` (boolean) - Always `true` for successful requests
+- `data` (object) - Container for response data
+    - `bill_info` (object) - Payment information from Payture
+        - `bill_status` (string) - Current status: "PENDING", "PAID"
+        - `amount` (number) - Payment amount in kopecks (cents)
+        - `gift` (object, optional) - Only present for gift purchases after payment
+            - `code` (string) - Gift activation code
+    - `status` (string) - Current bill status: "PENDING", "PAID", "DONE", "AMOUNT_MISMATCH"
+
+**Special Status Values:**
+- `PENDING` - Payment not yet completed
+- `PAID` - Payment completed on Payture side
+- `DONE` - Payment processed and subscription/gift activated
+- `AMOUNT_MISMATCH` - Payment amount doesn't match expected amount
+
+---
+
+## Complete Usage Examples
+
+### Basic Payment Flow for Authorized Users
+
+```javascript
+// Example: Create payment and redirect user
+async function createPaymentForUser(subscriptionId) {
+    try {
+        console.log("Creating payment bill...");
+        
+        const billResult = await behindAPI.V20.payments.payture.billCreate(
+            subscriptionId
+        );
+        
+        if (billResult.success) {
+            console.log("✓ Bill created successfully!");
+            console.log(`Bill ID: ${billResult.data.bill_id}`);
+            console.log(`Payment URL: ${billResult.data.bill.payUrl}`);
+            
+            // Redirect user to payment page
+            window.location.href = billResult.data.bill.payUrl;
+            
+            return billResult.data;
+        } else {
+            console.log(`✗ Failed to create bill: ${billResult.message}`);
+            return null;
+        }
+    } catch (error) {
+        console.error("Error creating payment:", error);
+        return null;
+    }
+}
+
+// Usage
+const paymentData = await createPaymentForUser(
+    "550e8400-e29b-41d4-a716-446655440001"
+);
+```
+
+### Guest Checkout with Custom Redirect
+
+```javascript
+// Example: Create payment for guest user with custom redirect
+async function createGuestPayment(subscriptionId, userId, returnUrl) {
+    try {
+        console.log("Creating guest payment bill...");
+        
+        const billResult = await behindAPI.V20.payments.payture.billCreateUnauthorised(
+            subscriptionId,
+            userId,
+            returnUrl,
+            {
+                source: "landing_page",
+                campaign: "spring_sale_2024"
+            }
+        );
+        
+        if (billResult.success) {
+            console.log("✓ Guest bill created successfully!");
+            console.log(`Bill ID: ${billResult.data.bill_id}`);
+            console.log(`Payment URL: ${billResult.data.bill.payUrl}`);
+            
+            // Store bill_id in session for later status checking
+            sessionStorage.setItem('pending_bill_id', billResult.data.bill_id);
+            
+            // Redirect to payment
+            window.location.href = billResult.data.bill.payUrl;
+            
+            return billResult.data;
+        } else {
+            console.log(`✗ Failed to create guest bill: ${billResult.message}`);
+            return null;
+        }
+    } catch (error) {
+        console.error("Error creating guest payment:", error);
+        return null;
+    }
+}
+
+// Usage
+const guestPayment = await createGuestPayment(
+    "550e8400-e29b-41d4-a716-446655440001",
+    "aa0e8400-e29b-41d4-a716-446655440005",
+    "https://mysite.com/thank-you"
+);
+```
+
+### Page Access Purchase with Extended Data
+
+```javascript
+// Example: Purchase subscription with page access
+async function purchasePageAccess(subscriptionId, userId, pageId) {
+    try {
+        console.log("Creating page access purchase...");
+        
+        // Create bill with page access information
+        const billResult = await behindAPI.V20.payments.payture.billCreateUnauthorised(
+            subscriptionId,
+            userId,
+            "https://mysite.com/access-granted",
+            {
+                pageId: "ck4jrtawdA3Ed4"
+            }
+        );
+        
+        if (!billResult.success) {
+            console.log(`✗ Failed to create bill: ${billResult.message}`);
+            return { success: false, error: billResult.message };
+        }
+        
+        console.log("✓ Bill created with page access!");
+        console.log(`Bill ID: ${billResult.data.bill_id}`);
+        console.log(`Page ID: ck4jrtawdA3Ed4`);
+        
+        // Store for later verification
+        sessionStorage.setItem('pending_bill_id', billResult.data.bill_id);
+        sessionStorage.setItem('pending_page_id', 'ck4jrtawdA3Ed4');
+        
+        // Redirect to payment
+        window.location.href = billResult.data.bill.payUrl;
+        
+        return {
+            success: true,
+            billId: billResult.data.bill_id,
+            pageId: 'ck4jrtawdA3Ed4',
+            paymentUrl: billResult.data.bill.payUrl
+        };
+        
+    } catch (error) {
+        console.error("Error purchasing page access:", error);
+        return { success: false, error: error.message };
+    }
+}
+
+// Usage
+const pageAccessPurchase = await purchasePageAccess(
+    "550e8400-e29b-41d4-a716-446655440001",
+    "aa0e8400-e29b-41d4-a716-446655440005",
+    "ck4jrtawdA3Ed4"
+);
+```
+
+### Gift Purchase Workflow
+
+```javascript
+// Example: Purchase a gift subscription
+async function purchaseGift(giftSubscriptionId, buyerId, recipientEmail) {
+    try {
+        console.log("Creating gift purchase...");
+        
+        // Create bill with gift recipient information
+        const billResult = await behindAPI.V20.payments.payture.billCreateUnauthorised(
+            giftSubscriptionId,
+            buyerId,
+            "https://mysite.com/gift-complete",
+            {
+                giftRecipient: recipientEmail,
+                giftType: "subscription",
+                giftMessage: "Enjoy your subscription!"
+            }
+        );
+        
+        if (!billResult.success) {
+            console.log(`✗ Failed to create gift bill: ${billResult.message}`);
+            return { success: false, error: billResult.message };
+        }
+        
+        console.log("✓ Gift bill created!");
+        console.log(`Bill ID: ${billResult.data.bill_id}`);
+        
+        // Redirect to payment
+        window.location.href = billResult.data.bill.payUrl;
+        
+        return {
+            success: true,
+            billId: billResult.data.bill_id,
+            paymentUrl: billResult.data.bill.payUrl
+        };
+        
+    } catch (error) {
+        console.error("Error purchasing gift:", error);
+        return { success: false, error: error.message };
+    }
+}
+
+// Usage
+const giftPurchase = await purchaseGift(
+    "550e8400-e29b-41d4-a716-446655440001",
+    "aa0e8400-e29b-41d4-a716-446655440005",
+    "recipient@example.com"
+);
+```
+
+### Payment Status Monitoring
+
+```javascript
+// Example: Check payment status with polling
+async function monitorPaymentStatus(billId, maxAttempts = 10, intervalMs = 3000) {
+    let attempts = 0;
+    
+    const checkStatus = async () => {
+        try {
+            console.log(`Checking payment status (attempt ${attempts + 1}/${maxAttempts})...`);
+            
+            const statusResult = await behindAPI.V20.payments.payture.billStatus(billId);
+            
+            if (!statusResult.success) {
+                console.log(`✗ Status check failed: ${statusResult.message}`);
+                return { success: false, error: statusResult.message };
+            }
+            
+            const status = statusResult.data.status;
+            console.log(`Current status: ${status}`);
+            
+            if (status === "PAID" || status === "DONE") {
+                console.log("✓ Payment completed successfully!");
+                
+                // Check for gift code
+                if (statusResult.data.bill_info.gift) {
+                    console.log(`Gift code: ${statusResult.data.bill_info.gift.code}`);
+                }
+                
+                return {
+                    success: true,
+                    status: status,
+                    billInfo: statusResult.data.bill_info
+                };
+            }
+            
+            if (status === "AMOUNT_MISMATCH") {
+                console.log("✗ Payment amount mismatch detected!");
+                return {
+                    success: false,
+                    error: "Amount mismatch",
+                    status: status
+                };
+            }
+            
+            // Still pending, continue polling
+            attempts++;
+            if (attempts < maxAttempts) {
+                await new Promise(resolve => setTimeout(resolve, intervalMs));
+                return checkStatus();
+            } else {
+                console.log("⚠ Maximum attempts reached, payment still pending");
+                return {
+                    success: false,
+                    error: "Timeout",
+                    status: "PENDING"
+                };
+            }
+            
+        } catch (error) {
+            console.error("Error checking payment status:", error);
+            return { success: false, error: error.message };
+        }
+    };
+    
+    return checkStatus();
+}
+
+// Usage
+const billId = "cc0e8400-e29b-41d4-a716-446655440009";
+const paymentResult = await monitorPaymentStatus(billId);
+
+if (paymentResult.success) {
+    console.log("Payment confirmed!");
+    if (paymentResult.billInfo.gift) {
+        console.log(`Gift code: ${paymentResult.billInfo.gift.code}`);
+    }
+} else {
+    console.log(`Payment not completed: ${paymentResult.error}`);
+}
+```
+
+### Payment Return Handler with Page Access
+
+```javascript
+// Example: Handle user return from payment gateway
+async function handlePaymentReturn() {
+    try {
+        // Get bill_id from URL or session
+        const urlParams = new URLSearchParams(window.location.search);
+        const billId = urlParams.get('bill_id') || 
+                       sessionStorage.getItem('pending_bill_id');
+        const pageId = sessionStorage.getItem('pending_page_id');
+        
+        if (!billId) {
+            console.log("No bill ID found");
+            return { success: false, error: "No bill ID" };
+        }
+        
+        console.log("Checking payment status for return...");
+        
+        // Check the bill status
+        const statusResult = await behindAPI.V20.payments.payture.billStatus(billId);
+        
+        if (!statusResult.success) {
+            console.log(`✗ Failed to check status: ${statusResult.message}`);
+            return {
+                success: false,
+                error: statusResult.message
+            };
+        }
+        
+        const status = statusResult.data.status;
+        const billInfo = statusResult.data.bill_info;
+        
+        // Clear stored data
+        sessionStorage.removeItem('pending_bill_id');
+        sessionStorage.removeItem('pending_page_id');
+        
+        if (status === "PAID" || status === "DONE") {
+            console.log("✓ Payment successful!");
+            
+            // Handle gift code if present
+            if (billInfo.gift) {
+                return {
+                    success: true,
+                    status: status,
+                    paymentType: "gift",
+                    giftCode: billInfo.gift.code,
+                    message: "Payment successful! Your gift code is ready."
+                };
+            }
+            
+            // Handle page access if present
+            if (pageId) {
+                return {
+                    success: true,
+                    status: status,
+                    paymentType: "page_access",
+                    pageId: pageId,
+                    message: "Payment successful! Your page access has been granted."
+                };
+            }
+            
+            return {
+                success: true,
+                status: status,
+                paymentType: "subscription",
+                message: "Payment successful! Your subscription is now active."
+            };
+        } else if (status === "PENDING") {
+            console.log("⚠ Payment still pending");
+            return {
+                success: false,
+                status: "PENDING",
+                message: "Payment is still being processed. Please wait..."
+            };
+        } else if (status === "AMOUNT_MISMATCH") {
+            console.log("✗ Payment amount mismatch");
+            return {
+                success: false,
+                status: status,
+                message: "Payment amount doesn't match. Please contact support."
+            };
+        } else {
+            console.log(`⚠ Unknown status: ${status}`);
+            return {
+                success: false,
+                status: status,
+                message: "Unknown payment status. Please contact support."
+            };
+        }
+        
+    } catch (error) {
+        console.error("Error handling payment return:", error);
+        return {
+            success: false,
+            error: error.message
+        };
+    }
+}
+
+// Usage on return page
+window.addEventListener('load', async () => {
+    const result = await handlePaymentReturn();
+    
+    if (result.success) {
+        document.getElementById('status').textContent = result.message;
+        
+        if (result.paymentType === "gift" && result.giftCode) {
+            document.getElementById('gift-code').textContent = result.giftCode;
+            document.getElementById('gift-section').style.display = 'block';
+        } else if (result.paymentType === "page_access" && result.pageId) {
+            document.getElementById('page-info').textContent = 
+                `You now have access to page: ${result.pageId}`;
+            document.getElementById('page-section').style.display = 'block';
+        }
+    } else {
+        document.getElementById('status').textContent = 
+            result.message || "Payment not completed";
+    }
+});
+```
+
+### Complete Purchase Flow with Error Handling
+
+```javascript
+// Example: Complete payment flow from creation to confirmation
+async function completePurchaseFlow(subscriptionId, userId, options = {}) {
+    const flow = {
+        billId: null,
+        paymentUrl: null,
+        status: null,
+        error: null
+    };
+    
+    try {
+        console.log("=== STARTING PURCHASE FLOW ===");
+        
+        // Step 1: Prepare extended data
+        const extendedData = {};
+        if (options.pageId) {
+            extendedData.pageId = options.pageId;
+        }
+        if (options.giftRecipient) {
+            extendedData.giftRecipient = options.giftRecipient;
+        }
+        if (options.customData) {
+            Object.assign(extendedData, options.customData);
+        }
+        
+        // Step 2: Create bill
+        console.log("\n1. Creating payment bill...");
+        let billResult;
+        
+        if (options.isGuest) {
+            billResult = await behindAPI.V20.payments.payture.billCreateUnauthorised(
+                subscriptionId,
+                userId,
+                options.redirectUrl || "https://mysite.com/payment-return",
+                extendedData
+            );
+        } else {
+            billResult = await behindAPI.V20.payments.payture.billCreate(
+                subscriptionId
+            );
+        }
+        
+        if (!billResult.success) {
+            console.log(`✗ Bill creation failed: ${billResult.message}`);
+            flow.error = billResult.message;
+            return flow;
+        }
+        
+        flow.billId = billResult.data.bill_id;
+        flow.paymentUrl = billResult.data.bill.payUrl;
+        
+        console.log(`✓ Bill created: ${flow.billId}`);
+        console.log(`Payment URL: ${flow.paymentUrl}`);
+        
+        // Step 3: Store bill_id for later verification
+        sessionStorage.setItem('current_bill_id', flow.billId);
+        sessionStorage.setItem('bill_created_at', Date.now());
+        
+        if (options.pageId) {
+            sessionStorage.setItem('pending_page_id', options.pageId);
+        }
+        
+        // Step 4: Open payment in new window or redirect
+        console.log("\n2. Opening payment gateway...");
+        const paymentWindow = window.open(flow.paymentUrl, '_blank');
+        
+        if (!paymentWindow) {
+            console.log("⚠ Popup blocked, redirecting in current window...");
+            window.location.href = flow.paymentUrl;
+            return flow;
+        }
+        
+        // Step 5: Monitor payment status
+        console.log("\n3. Monitoring payment status...");
+        const monitoringResult = await monitorPaymentWindow(
+            flow.billId,
+            paymentWindow
+        );
+        
+        flow.status = monitoringResult.status;
+        
+        if (monitoringResult.success) {
+            console.log("✓ Payment completed successfully!");
+            sessionStorage.removeItem('current_bill_id');
+            sessionStorage.removeItem('bill_created_at');
+            sessionStorage.removeItem('pending_page_id');
+        } else {
+            console.log(`✗ Payment not completed: ${monitoringResult.error}`);
+            flow.error = monitoringResult.error;
+        }
+        
+        return flow;
+        
+    } catch (error) {
+        console.error("Error in purchase flow:", error);
+        flow.error = error.message;
+        return flow;
+    }
+}
+
+// Helper function to monitor payment window
+async function monitorPaymentWindow(billId, paymentWindow) {
+    return new Promise((resolve) => {
+        let attempts = 0;
+        const maxAttempts = 60;
+        
+        const interval = setInterval(async () => {
+            attempts++;
+            
+            if (paymentWindow.closed) {
+                clearInterval(interval);
+                const statusResult = await behindAPI.V20.payments.payture.billStatus(billId);
+                
+                if (statusResult.success && 
+                    (statusResult.data.status === "PAID" || statusResult.data.status === "DONE")) {
+                    resolve({
+                        success: true,
+                        status: statusResult.data.status,
+                        billInfo: statusResult.data.bill_info
+                    });
+                } else {
+                    resolve({
+                        success: false,
+                        error: "Payment window closed without completion",
+                        status: statusResult.data?.status || "UNKNOWN"
+                    });
+                }
+                return;
+            }
+            
+            if (attempts % 2 === 0) {
+                const statusResult = await behindAPI.V20.payments.payture.billStatus(billId);
+                
+                if (statusResult.success && 
+                    (statusResult.data.status === "PAID" || statusResult.data.status === "DONE")) {
+                    clearInterval(interval);
+                    paymentWindow.close();
+                    resolve({
+                        success: true,
+                        status: statusResult.data.status,
+                        billInfo: statusResult.data.bill_info
+                    });
+                    return;
+                }
+            }
+            
+            if (attempts >= maxAttempts) {
+                clearInterval(interval);
+                resolve({
+                    success: false,
+                    error: "Payment monitoring timeout",
+                    status: "PENDING"
+                });
+            }
+        }, 5000);
+    });
+}
+
+// Usage examples
+
+// Standard purchase
+const standardPurchase = await completePurchaseFlow(
+    "550e8400-e29b-41d4-a716-446655440001",
+    "aa0e8400-e29b-41d4-a716-446655440005",
+    {
+        isGuest: true
+    }
+);
+
+// Purchase with page access
+const pageAccessPurchase = await completePurchaseFlow(
+    "550e8400-e29b-41d4-a716-446655440001",
+    "aa0e8400-e29b-41d4-a716-446655440005",
+    {
+        isGuest: true,
+        pageId: "ck4jrtawdA3Ed4",
+        redirectUrl: "https://mysite.com/access-granted"
+    }
+);
+
+// Gift purchase
+const giftPurchase = await completePurchaseFlow(
+    "550e8400-e29b-41d4-a716-446655440001",
+    "aa0e8400-e29b-41d4-a716-446655440005",
+    {
+        isGuest: false,
+        giftRecipient: "recipient@example.com",
+        redirectUrl: "https://mysite.com/gift-sent"
+    }
+);
+
+console.log("=== PURCHASE RESULT ===");
+console.log(pageAccessPurchase);
+```
+
+---
+
+## Best Practices
+
+1. **Bill ID Storage**: Always store the bill_id after creation for status verification and troubleshooting.
+
+2. **Status Polling**: Implement reasonable polling intervals (3-5 seconds) when monitoring payment status to avoid overwhelming the API.
+
+3. **Error Handling**: Always check the `success` property and handle various status values (PENDING, PAID, DONE, AMOUNT_MISMATCH).
+
+4. **Redirect URLs**: When using custom redirect URLs with `billCreateUnauthorised`, ensure they are properly formatted and accessible.
+
+5. **Extended Data**: Use the `extended` parameter to store additional context about the purchase:
+    - `pageId` (e.g., "ck4jrtawdA3Ed4") for granting page access after payment
+    - Gift recipient information for gift purchases
+    - Source tracking and campaign data
+    - Any custom metadata needed for your business logic
+
+6. **Amount Verification**: Always verify the payment amount matches your expected amount to prevent fraudulent transactions.
+
+7. **Gift Codes**: For gift purchases, ensure proper handling of the gift code returned after successful payment.
+
+8. **Page Access**: When including `pageId` in extended data, the system automatically grants user access to the specified page upon successful payment (for direct subscription types).
+
+9. **Session Management**: Clear stored bill IDs and session data after successful payment completion.
+
+10. **User Experience**: Provide clear feedback during payment processing and handle popup blockers gracefully.
+
+11. **Security**: Never store sensitive payment information locally. Always use the Payture gateway for payment processing.
+
+---
+
+## Payment Status Flow
+
+```
+PENDING → PAID → DONE
+         ↓
+    AMOUNT_MISMATCH
+```
+
+- **PENDING**: Initial state after bill creation, payment not completed
+- **PAID**: Payment completed on Payture side, amount verified
+- **DONE**: Payment processed and subscription/gift activated
+- **AMOUNT_MISMATCH**: Payment completed but amount doesn't match expected value
+
+---
+
+## Extended Data Use Cases
+
+The `extended` parameter in `billCreateUnauthorised` supports various use cases:
+
+### Page Access Purchase
+
+```javascript
+// Grant access to specific page after payment
+const result = await behindAPI.V20.payments.payture.billCreateUnauthorised(
+    subscriptionId,
+    userId,
+    redirectUrl,
+    {
+        pageId: "ck4jrtawdA3Ed4"
+    }
+);
+```
+
+### Gift Purchase with Recipient Info
+
+```javascript
+// Store gift recipient information
+const result = await behindAPI.V20.payments.payture.billCreateUnauthorised(
+    subscriptionId,
+    userId,
+    redirectUrl,
+    {
+        giftRecipient: "friend@example.com",
+        giftMessage: "Happy Birthday!",
+        giftOccasion: "birthday"
+    }
+);
+```
+
+### Marketing Campaign Tracking
+
+```javascript
+// Track purchase source and campaign
+const result = await behindAPI.V20.payments.payture.billCreateUnauthorised(
+    subscriptionId,
+    userId,
+    redirectUrl,
+    {
+        source: "facebook_ad",
+        campaign: "spring_sale_2024",
+        referrer: "influencer_abc",
+        utm_source: "social",
+        utm_medium: "paid",
+        utm_campaign: "spring24"
+    }
+);
+```
+
+---
+
+## Authorization Requirements
+
+- `billCreate`: Requires valid user session (`need_authorization: true`)
+- `billCreateUnauthorised`: No authorization required (`need_authorization: false`)
+- `billStatus`: No authorization required (`need_authorization: false`)
+
+The `billCreateUnauthorised` and `billStatus` methods can be called without user authentication, making them suitable for guest checkouts and status verification.
+
+---
+
+## Integration Notes
+
+The Payture Payments API integrates with:
+
+- **Subscription System**: Bills are created for subscription products and activate subscriptions upon payment
+- **Gift System**: Supports gift purchases with automatic code generation and email notifications
+- **Email System**: Sends invoices and gift notifications through the mailer API
+- **Woololo API**: Can grant page access for specific purchase types when `pageId` is provided in extended data
+- **Database**: Stores bill records, tracks status, and manages payment history
+
+### Page Access Integration
+
+When creating a bill with `pageId` in the extended data:
+1. The bill is created with the page access information stored
+2. Upon successful payment (PAID status)
+3. For "direct" subscription product types, the system automatically grants user access to the specified page
+4. Access is granted using the Woololo API with access_type 'ALL_USERS'
+
+---
+
+## Error Handling
+
+All methods return a response object with a `success` boolean property. When `success` is `false`, a `message` property contains the error description.
+
+```javascript
+// Comprehensive error handling example
+async function safePaymentOperation(subscriptionId, userId, pageId = null) {
+    try {
+        // Validate input parameters
+        if (!subscriptionId || !userId) {
+            return {
+                success: false,
+                error: "Missing required parameters"
+            };
+        }
+        
+        // Validate UUID format
+        const uuidRegex = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+        if (!uuidRegex.test(subscriptionId) || !uuidRegex.test(userId)) {
+            return {
+                success: false,
+                error: "Invalid UUID format"
+            };
+        }
+        
+        // Prepare extended data
+        const extendedData = {};
+        if (pageId) {
+            extendedData.pageId = pageId;
+        }
+        
+        // Create bill
+        const billResult = await behindAPI.V20.payments.payture.billCreateUnauthorised(
+            subscriptionId,
+            userId,
+            "https://mysite.com/return",
+            extendedData
+        );
+        
+        if (!billResult.success) {
+            console.error("API Error:", billResult.message);
+            return {
+                success: false,
+                error: billResult.message
+            };
+        }
+        
+        return {
+            success: true,
+            billId: billResult.data.bill_id,
+            paymentUrl: billResult.data.bill.payUrl,
+            pageId: pageId
+        };
+        
+    } catch (error) {
+        console.error("Unexpected error:", error);
+        return {
+            success: false,
+            error: "An unexpected error occurred"
+        };
+    }
+}
+
+// Usage with comprehensive error handling
+const result = await safePaymentOperation(
+    "550e8400-e29b-41d4-a716-446655440001",
+    "aa0e8400-e29b-41d4-a716-446655440005",
+    "ck4jrtawdA3Ed4"
+);
+
+if (result.success) {
+    console.log("Bill created:", result.billId);
+    if (result.pageId) {
+        console.log("Page access will be granted:", result.pageId);
+    }
+    window.location.href = result.paymentUrl;
+} else {
+    console.error("Operation failed:", result.error);
+    // Show user-friendly error message
+    alert("Unable to create payment. Please try again.");
+}
+```
+
+---
+
+## Common Error Scenarios
+
+### Empty Bill ID
+```javascript
+const result = await behindAPI.V20.payments.payture.billStatus("");
+
+// Response:
+{
+    success: false,
+    message: "bill_id can not be empty"
+}
+```
+
+### Invalid UUID Format
+```javascript
+// Always validate UUIDs before making API calls
+const uuidRegex = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+
+if (!uuidRegex.test(subscriptionId)) {
+    console.error("Invalid subscription ID format");
+    return { success: false, error: "Invalid UUID format" };
+}
+```
+
+### Payment Amount Mismatch
+```javascript
+// The system detects when payment amount doesn't match expected amount
+const statusResult = await behindAPI.V20.payments.payture.billStatus(billId);
+
+if (statusResult.data?.status === "AMOUNT_MISMATCH") {
+    console.error("Payment amount verification failed");
+    // Contact support or retry payment
+}
+```
+
+### Network Timeout
+```javascript
+// Implement timeout handling for API calls
+async function createBillWithTimeout(subscriptionId, userId, timeoutMs = 30000) {
+    const timeoutPromise = new Promise((_, reject) => {
+        setTimeout(() => reject(new Error("Request timeout")), timeoutMs);
+    });
+    
+    const billPromise = behindAPI.V20.payments.payture.billCreateUnauthorised(
+        subscriptionId,
+        userId,
+        "https://mysite.com/return"
+    );
+    
+    try {
+        const result = await Promise.race([billPromise, timeoutPromise]);
+        return result;
+    } catch (error) {
+        console.error("Timeout or error:", error);
+        return { success: false, error: error.message };
+    }
+}
+```
+
+---
+
+## Advanced Usage Patterns
+
+### Multi-Currency Support
+```javascript
+// Handle different currencies based on user location
+async function createInternationalPayment(subscriptionId, userId, userCountry) {
+    const currencyMap = {
+        'RU': { currency: 'RUB', redirectUrl: 'https://mysite.ru/return' },
+        'US': { currency: 'USD', redirectUrl: 'https://mysite.com/return' },
+        'EU': { currency: 'EUR', redirectUrl: 'https://mysite.eu/return' }
+    };
+    
+    const config = currencyMap[userCountry] || currencyMap['RU'];
+    
+    const result = await behindAPI.V20.payments.payture.billCreateUnauthorised(
+        subscriptionId,
+        userId,
+        config.redirectUrl,
+        {
+            currency: config.currency,
+            country: userCountry
+        }
+    );
+    
+    return result;
+}
+```
+
+### Retry Logic for Failed Payments
+```javascript
+// Implement retry mechanism with exponential backoff
+async function createBillWithRetry(subscriptionId, userId, maxRetries = 3) {
+    let lastError;
+    
+    for (let attempt = 1; attempt <= maxRetries; attempt++) {
+        try {
+            console.log(`Payment creation attempt ${attempt}/${maxRetries}`);
+            
+            const result = await behindAPI.V20.payments.payture.billCreateUnauthorised(
+                subscriptionId,
+                userId,
+                "https://mysite.com/return"
+            );
+            
+            if (result.success) {
+                console.log("✓ Payment created successfully");
+                return result;
+            }
+            
+            lastError = result.message;
+            
+        } catch (error) {
+            lastError = error.message;
+            console.error(`Attempt ${attempt} failed:`, error);
+        }
+        
+        // Wait before retrying (exponential backoff)
+        if (attempt < maxRetries) {
+            const waitTime = Math.pow(2, attempt) * 1000;
+            console.log(`Waiting ${waitTime}ms before retry...`);
+            await new Promise(resolve => setTimeout(resolve, waitTime));
+        }
+    }
+    
+    return {
+        success: false,
+        error: `Failed after ${maxRetries} attempts: ${lastError}`
+    };
+}
+```
+
+### Payment Analytics Tracking
+```javascript
+// Track payment events for analytics
+async function createTrackedPayment(subscriptionId, userId, analyticsData) {
+    const startTime = Date.now();
+    
+    const result = await behindAPI.V20.payments.payture.billCreateUnauthorised(
+        subscriptionId,
+        userId,
+        "https://mysite.com/return",
+        {
+            ...analyticsData,
+            sessionId: generateSessionId(),
+            deviceType: getDeviceType(),
+            referrer: document.referrer
+        }
+    );
+    
+    const duration = Date.now() - startTime;
+    
+    // Send analytics event
+    trackEvent('payment_initiated', {
+        billId: result.data?.bill_id,
+        subscriptionId: subscriptionId,
+        success: result.success,
+        duration: duration,
+        ...analyticsData
+    });
+    
+    return result;
+}
+
+function trackEvent(eventName, eventData) {
+    // Your analytics implementation
+    console.log(`Analytics: ${eventName}`, eventData);
+}
+
+function generateSessionId() {
+    return `session_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;
+}
+
+function getDeviceType() {
+    const ua = navigator.userAgent;
+    if (/mobile/i.test(ua)) return 'mobile';
+    if (/tablet/i.test(ua)) return 'tablet';
+    return 'desktop';
+}
+```
+
+### Webhook Handler for Payment Notifications
+```javascript
+// Server-side webhook handler example (Node.js/Express)
+app.post('/webhooks/payture', async (req, res) => {
+    try {
+        const { bill_id, status, amount } = req.body;
+        
+        // Verify webhook authenticity (implement your verification logic)
+        if (!verifyWebhookSignature(req)) {
+            return res.status(401).json({ error: 'Invalid signature' });
+        }
+        
+        // Check payment status
+        const statusResult = await behindAPI.V20.payments.payture.billStatus(bill_id);
+        
+        if (statusResult.success && statusResult.data.status === "DONE") {
+            // Payment completed, update your systems
+            await updateUserSubscription(bill_id);
+            
+            // Send confirmation email
+            await sendPaymentConfirmation(bill_id);
+            
+            res.status(200).json({ success: true });
+        } else {
+            res.status(200).json({ success: false, status: statusResult.data?.status });
+        }
+        
+    } catch (error) {
+        console.error('Webhook error:', error);
+        res.status(500).json({ error: 'Internal server error' });
+    }
+});
+```
+
+### Subscription Management Dashboard
+```javascript
+// Build a dashboard showing all user payments
+async function buildPaymentDashboard(userId) {
+    const dashboard = {
+        activeSubscriptions: [],
+        pendingPayments: [],
+        completedPayments: [],
+        giftCodes: [],
+        totalSpent: 0
+    };
+    
+    try {
+        // Fetch user's bills from your database
+        const userBills = await fetchUserBills(userId);
+        
+        for (const bill of userBills) {
+            const statusResult = await behindAPI.V20.payments.payture.billStatus(
+                bill.bill_id
+            );
+            
+            if (!statusResult.success) continue;
+            
+            const billData = {
+                billId: bill.bill_id,
+                amount: statusResult.data.bill_info.amount / 100,
+                status: statusResult.data.status,
+                createdAt: bill.created_at
+            };
+            
+            switch (statusResult.data.status) {
+                case "PENDING":
+                    dashboard.pendingPayments.push(billData);
+                    break;
+                case "DONE":
+                case "PAID":
+                    dashboard.completedPayments.push(billData);
+                    dashboard.totalSpent += billData.amount;
+                    
+                    if (statusResult.data.bill_info.gift) {
+                        dashboard.giftCodes.push({
+                            ...billData,
+                            giftCode: statusResult.data.bill_info.gift.code
+                        });
+                    } else {
+                        dashboard.activeSubscriptions.push(billData);
+                    }
+                    break;
+            }
+        }
+        
+        return dashboard;
+        
+    } catch (error) {
+        console.error("Error building dashboard:", error);
+        return dashboard;
+    }
+}
+
+// Usage
+const dashboard = await buildPaymentDashboard("aa0e8400-e29b-41d4-a716-446655440005");
+console.log("Payment Dashboard:", dashboard);
+```
+
+---
+
+## Testing
+
+### Test Environment Setup
+```javascript
+// Configure test environment
+const TEST_CONFIG = {
+    subscriptionId: "550e8400-e29b-41d4-a716-446655440001",
+    testUserId: "test-user-000000000000000000000001",
+    testPageId: "ck4jrtawdA3Ed4",
+    testRedirectUrl: "https://test.mysite.com/return"
+};
+
+// Run payment flow test
+async function testPaymentFlow() {
+    console.log("=== TESTING PAYMENT FLOW ===\n");
+    
+    // Test 1: Create bill
+    console.log("Test 1: Creating test bill...");
+    const billResult = await behindAPI.V20.payments.payture.billCreateUnauthorised(
+        TEST_CONFIG.subscriptionId,
+        TEST_CONFIG.testUserId,
+        TEST_CONFIG.testRedirectUrl,
+        {
+            pageId: TEST_CONFIG.testPageId,
+            test: true
+        }
+    );
+    
+    console.log(billResult.success ? "✓ PASS" : "✗ FAIL");
+    if (!billResult.success) return;
+    
+    const billId = billResult.data.bill_id;
+    console.log(`Bill ID: ${billId}\n`);
+    
+    // Test 2: Check initial status
+    console.log("Test 2: Checking initial bill status...");
+    const initialStatus = await behindAPI.V20.payments.payture.billStatus(billId);
+    console.log(initialStatus.success ? "✓ PASS" : "✗ FAIL");
+    console.log(`Status: ${initialStatus.data?.status}\n`);
+    
+    // Test 3: Check with empty bill_id
+    console.log("Test 3: Testing empty bill_id validation...");
+    const emptyTest = await behindAPI.V20.payments.payture.billStatus("");
+    console.log(!emptyTest.success ? "✓ PASS" : "✗ FAIL");
+    console.log(`Error message: ${emptyTest.message}\n`);
+    
+    console.log("=== TEST COMPLETE ===");
+}
+
+// Run tests
+testPaymentFlow();
+```
+
+---
+
+## Troubleshooting
+
+### Common Issues and Solutions
+
+**Issue: Payment window blocked by popup blocker**
+```javascript
+// Solution: Provide fallback to direct redirect
+const paymentWindow = window.open(paymentUrl, '_blank');
+
+if (!paymentWindow || paymentWindow.closed) {
+    alert("Please allow popups for this site to complete payment");
+    // Fallback to same-window redirect
+    window.location.href = paymentUrl;
+}
+```
+
+**Issue: Payment status remains PENDING after successful payment**
+```javascript
+// Solution: Implement proper status polling with logging
+async function debugPaymentStatus(billId) {
+    console.log(`Debugging bill: ${billId}`);
+    
+    const result = await behindAPI.V20.payments.payture.billStatus(billId);
+    
+    console.log("API Response:", JSON.stringify(result, null, 2));
+    console.log("Status:", result.data?.status);
+    console.log("Bill Status:", result.data?.bill_info?.bill_status);
+    console.log("Amount:", result.data?.bill_info?.amount);
+    
+    return result;
+}
+```
+
+**Issue: Amount mismatch errors**
+```javascript
+// Solution: Log and verify amounts at each step
+async function verifyPaymentAmount(billId, expectedAmount) {
+    const result = await behindAPI.V20.payments.payture.billStatus(billId);
+    
+    if (result.success) {
+        const actualAmount = result.data.bill_info.amount / 100; // Convert from kopecks
+        console.log(`Expected: ${expectedAmount}, Actual: ${actualAmount}`);
+        
+        if (Math.abs(actualAmount - expectedAmount) > 0.01) {
+            console.error("Amount mismatch detected!");
+            return false;
+        }
+    }
+    
+    return true;
+}
+```
+
+**Issue: Lost bill_id after page refresh**
+```javascript
+// Solution: Implement persistent storage
+function saveBillId(billId) {
+    // Store in multiple places for redundancy
+    sessionStorage.setItem('pending_bill_id', billId);
+    localStorage.setItem('last_bill_id', billId);
+    
+    // Store with timestamp for cleanup
+    const billData = {
+        billId: billId,
+        timestamp: Date.now()
+    };
+    localStorage.setItem('bill_data', JSON.stringify(billData));
+}
+
+function retrieveBillId() {
+    // Try session storage first
+    let billId = sessionStorage.getItem('pending_bill_id');
+    
+    // Fallback to local storage
+    if (!billId) {
+        billId = localStorage.getItem('last_bill_id');
+    }
+    
+    // Check if bill is recent (within 24 hours)
+    const billData = JSON.parse(localStorage.getItem('bill_data') || '{}');
+    const hoursSinceCreation = (Date.now() - billData.timestamp) / (1000 * 60 * 60);
+    
+    if (hoursSinceCreation > 24) {
+        console.warn("Bill ID is more than 24 hours old");
+    }
+    
+    return billId;
+}
+```
+
+---
+
+## Security Considerations
+
+1. **Never expose sensitive data**: Don't log or store payment card details
+2. **Validate all inputs**: Always validate UUIDs and URLs before API calls
+3. **Use HTTPS**: Ensure all redirect URLs use HTTPS protocol
+4. **Implement CSRF protection**: Use tokens for payment initiation
+5. **Rate limiting**: Implement rate limiting to prevent abuse
+6. **Verify webhooks**: Always verify webhook signatures
+7. **Session security**: Use secure session storage mechanisms
+8. **Audit logging**: Log all payment operations for security audits
+
+```javascript
+// Example: Secure payment initiation
+async function securePaymentInit(subscriptionId, userId, csrfToken) {
+    // Verify CSRF token
+    if (!verifyCsrfToken(csrfToken)) {
+        return { success: false, error: "Invalid security token" };
+    }
+    
+    // Sanitize inputs
+    const sanitizedSubId = sanitizeUuid(subscriptionId);
+    const sanitizedUserId = sanitizeUuid(userId);
+    
+    // Check rate limit
+    if (isRateLimited(userId)) {
+        return { success: false, error: "Too many requests. Please try again later." };
+    }
+    
+    // Create bill with audit log
+    const result = await behindAPI.V20.payments.payture.billCreateUnauthorised(
+        sanitizedSubId,
+        sanitizedUserId,
+        "https://secure.mysite.com/return"
+    );
+    
+    // Log the operation
+    auditLog({
+        action: 'payment_initiated',
+        userId: sanitizedUserId,
+        billId: result.data?.bill_id,
+        success: result.success,
+        timestamp: new Date().toISOString()
+    });
+    
+    return result;
+}
+```
+
+---
+
+## API Reference Summary
+
+| Method | Authorization Required | Parameters | Returns |
+|--------|----------------------|------------|---------|
+| `billCreate` | Yes | subscriptionId | bill_id, payUrl |
+| `billCreateUnauthorised` | No | subscriptionId, userId, redirectUrl, extended | bill_id, payUrl |
+| `billStatus` | No | billId | bill_info, status |
+
+---
+
+## Support and Resources
+
+For additional help:
+- **API Documentation**: Refer to the main EasyJob API documentation
+- **Error Codes**: Check Payture's official error code documentation
+- **Support**: Contact your technical support team for integration assistance
+- **Testing**: Use test environment before production deployment