react-amwal-pay 0.1.14 → 0.1.15

package/README.md

@@ -170,7 +170,10 @@ const config: AmwalPayConfig = {
   merchantReference: 'optional-merchant-reference', // optional: merchant reference for transaction tracking
   additionValues: { // optional: custom key-value pairs for SDK configuration
     merchantIdentifier: 'merchant.applepay.amwalpay', // for Apple Pay configuration
-    customKey: 'customValue' // add more as needed
+    useBottomSheetDesign: 'true', // use bottom sheet design (v2)
+    primaryColor: '#FF5733', // custom primary color
+    secondaryColor: '#33FF57', // custom secondary color
+    ignoreReceipt: 'false' // show receipt after transaction
   },
   onCustomerId(customerId) {
     console.log('Customer ID:', customerId);
@@ -236,7 +239,32 @@ The SDK supports `additionValues` parameter for passing custom key-value pairs t
 The SDK automatically provides default values:
 - `merchantIdentifier`: "merchant.applepay.amwalpay" (used for Apple Pay configuration)
 
-### Usage
+### Available Configuration Options
+
+You can customize the SDK behavior using the following `additionValues` keys:
+
+#### UI Customization
+- **`useBottomSheetDesign`**: `'true'` | `'false'` (default: `'false'`)
+  - Controls the payment screen design
+  - `'true'`: Uses the newer bottom sheet design (v2)
+  - `'false'`: Uses the original full-screen design
+
+- **`primaryColor`**: Hex color string (e.g., `'#FF5733'`)
+  - Sets the primary theme color for the SDK UI
+
+- **`secondaryColor`**: Hex color string (e.g., `'#33FF57'`)
+  - Sets the secondary theme color for the SDK UI
+
+#### Payment Flow
+- **`ignoreReceipt`**: `'true'` | `'false'` (default: `'false'`)
+  - Controls whether to show the receipt screen after transaction
+  - `'true'`: Skips the receipt display
+  - `'false'`: Shows the receipt screen
+
+- **`merchantIdentifier`**: String (default: `'merchant.applepay.amwalpay'`)
+  - Apple Pay merchant identifier for iOS
+
+### Usage Examples
 
 ```js
 // Using default additionValues (automatically applied)
@@ -245,18 +273,31 @@ const config = {
   // additionValues will automatically include merchantIdentifier
 };
 
-// Using custom additionValues
+// Using custom additionValues with UI customization
 const customConfig = {
   // ... other configuration
   additionValues: {
-    merchantIdentifier: 'merchant.custom.identifier',
-    customKey: 'customValue'
+    useBottomSheetDesign: 'true',
+    primaryColor: '#FF5733',
+    secondaryColor: '#33FF57',
+    ignoreReceipt: 'false',
+    merchantIdentifier: 'merchant.custom.identifier'
+  }
+};
+
+// Minimal configuration with bottom sheet design
+const minimalConfig = {
+  // ... other configuration
+  additionValues: {
+    useBottomSheetDesign: 'true'
   }
 };
 ```
 
 Custom `additionValues` will be merged with defaults, with custom values taking precedence.
 
+**Note:** All boolean values should be passed as strings (`'true'` or `'false'`).
+
 ## Configuration
 
 The `AmwalPayConfig` interface includes the following properties:

package/ios/ReactAmwalPay.swift

@@ -3,6 +3,70 @@ import amwalsdk
 import React
 import UIKit
 
+// MARK: - Container view controller that keeps SDK alive during 3DS presentation
+/// This container wraps the SDK view controller as a child
+/// When 3DS opens its WebView, it can present on top without dismissing the SDK
+class ShareableContainerViewController: UIViewController {
+    private let sdkViewController: UIViewController
+    
+    init(sdkViewController: UIViewController) {
+        self.sdkViewController = sdkViewController
+        super.init(nibName: nil, bundle: nil)
+    }
+    
+    required init?(coder: NSCoder) {
+        fatalError("init(coder:) has not been implemented")
+    }
+    
+    override func viewDidLoad() {
+        super.viewDidLoad()
+        
+        // Add SDK view controller as child - this keeps it alive during 3DS presentation
+        addChild(sdkViewController)
+        view.addSubview(sdkViewController.view)
+        sdkViewController.view.frame = view.bounds
+        sdkViewController.view.autoresizingMask = [.flexibleWidth, .flexibleHeight]
+        sdkViewController.didMove(toParent: self)
+        
+        view.backgroundColor = .clear
+        sdkViewController.view.backgroundColor = .clear
+        
+        // Enable presentation context to handle 3DS WebView presentation
+        // This is critical: allows 3DS WebView to present on top without dismissing the SDK
+        definesPresentationContext = true
+        providesPresentationContextTransitionStyle = true
+        
+        // Ensure the SDK view controller also allows nested presentations
+        // This prevents it from being dismissed when 3DS presents its WebView
+        sdkViewController.definesPresentationContext = true
+        sdkViewController.providesPresentationContextTransitionStyle = true
+    }
+    
+    override func viewDidAppear(_ animated: Bool) {
+        super.viewDidAppear(animated)
+        // Ensure container is ready for nested presentations
+    }
+    
+    private func topmostPresentedViewController() -> UIViewController {
+        var topController: UIViewController = self
+        while let presented = topController.presentedViewController {
+            topController = presented
+        }
+        return topController
+    }
+    
+    override func present(_ viewControllerToPresent: UIViewController, animated flag: Bool, completion: (() -> Void)? = nil) {
+        // If already presenting, present from the topmost controller
+        // This allows 3DS WebView to present on top without dismissing the SDK
+        if let presented = presentedViewController {
+            let topmost = topmostPresentedViewController()
+            topmost.present(viewControllerToPresent, animated: flag, completion: completion)
+        } else {
+            super.present(viewControllerToPresent, animated: flag, completion: completion)
+        }
+    }
+}
+
 // MARK: - Fix UIViewController presentation for share sheets
 public extension UIViewController {
     static let swizzlePresentOnce: Void = {
@@ -28,8 +92,18 @@ public extension UIViewController {
             }
         }
         
-        // Check if we're already presenting something
-        if self.presentedViewController != nil {
+        // Special handling for ShareableContainerViewController and its children
+        // If presenting from a child of ShareableContainerViewController, forward to container
+        if let container = findShareableContainer() {
+            if container != self {
+                // We're a child of the container, forward to container
+                container.swizzled_present(viewControllerToPresent, animated: flag, completion: completion)
+                return
+            }
+            // We ARE the container - allow nested presentations
+            // Don't auto-dismiss, just present on top
+        } else if self.presentedViewController != nil && !self.definesPresentationContext {
+            // Not a container, and already presenting - auto-dismiss
             print("⚠️ Already presenting, dismissing first...")
             self.dismiss(animated: false) { [weak self] in
                 self?.swizzled_present(viewControllerToPresent, animated: flag, completion: completion)
@@ -41,6 +115,21 @@ public extension UIViewController {
         self.swizzled_present(viewControllerToPresent, animated: flag, completion: completion)
     }
     
+    // Helper to find ShareableContainerViewController in parent hierarchy
+    private func findShareableContainer() -> ShareableContainerViewController? {
+        var current: UIViewController? = self
+        while let parent = current?.parent {
+            if let container = parent as? ShareableContainerViewController {
+                return container
+            }
+            current = parent
+        }
+        if let container = self as? ShareableContainerViewController {
+            return container
+        }
+        return nil
+    }
+    
     static func getTopMostViewController() -> UIViewController? {
         var topController: UIViewController?
         
@@ -65,6 +154,7 @@ public extension UIViewController {
 @objc(ReactAmwalPay)
 open class ReactAmwalPay: RCTEventEmitter {
     private var hasListeners = false
+    private var sdkWindow: UIWindow?  // Separate window for SDK to avoid modal dismissal issues
     
     // Initialize swizzling when the class is first loaded
     private static let initializeSwizzling: Void = {
@@ -197,6 +287,11 @@ open class ReactAmwalPay: RCTEventEmitter {
                        print("🟠 Response type: \(type(of: response))")
                        print("🟠 Response value: \(response ?? "nil")")
 
+                       // Dismiss SDK window when payment completes
+                       DispatchQueue.main.async {
+                           self?.dismissSDKWindow()
+                       }
+
                        // The SDK returns a JSON string, we need to parse it
                        if let responseString = response as? String,
                           let data = responseString.data(using: .utf8),
@@ -222,11 +317,41 @@ open class ReactAmwalPay: RCTEventEmitter {
                    }
                )
 
-               print("🟠 SDK ViewController created successfully")
-               print("🟠 About to present SDK ViewController...")
+               // Ensure transparency
+               sdkVC.view.backgroundColor = .clear
+               sdkVC.view.isOpaque = false
+               
+               // Wrap SDK view controller in container
+               let containerVC = ShareableContainerViewController(sdkViewController: sdkVC)
+               containerVC.view.backgroundColor = .clear
+
+               print("🟠 SDK ViewController wrapped in container")
+               print("🟠 Creating separate window for SDK...")
 
-               // Present modally (critical missing piece)
-               rootVC.present(sdkVC, animated: true)
+               // Create a separate window for the SDK
+               // This prevents modal presentation issues - SDK lives in its own window
+               // 3DS can present on top without affecting the SDK
+               if #available(iOS 13.0, *) {
+                   if let windowScene = UIApplication.shared.connectedScenes.first as? UIWindowScene {
+                       self.sdkWindow = UIWindow(windowScene: windowScene)
+                   }
+               } else {
+                   self.sdkWindow = UIWindow(frame: UIScreen.main.bounds)
+               }
+               
+               guard let sdkWindow = self.sdkWindow else {
+                   print("🟠 Failed to create SDK window, falling back to modal presentation")
+                   rootVC.present(containerVC, animated: true)
+                   return
+               }
+               
+               sdkWindow.rootViewController = containerVC
+               sdkWindow.windowLevel = .normal + 1  // Above main window
+               sdkWindow.backgroundColor = .clear
+               sdkWindow.isOpaque = false
+               sdkWindow.makeKeyAndVisible()
+               
+               print("🟠 SDK window created and made visible")
            } catch {
                print("Presentation failed: \(error.localizedDescription)")
                let errorData: [String: Any] = [
@@ -260,4 +385,12 @@ open class ReactAmwalPay: RCTEventEmitter {
     public override static func requiresMainQueueSetup() -> Bool {
         return true
     }
+    
+    // Dismiss SDK window when payment completes
+    private func dismissSDKWindow() {
+        print("🟠 Dismissing SDK window...")
+        sdkWindow?.isHidden = true
+        sdkWindow?.rootViewController = nil
+        sdkWindow = nil
+    }
 }

package/lib/module/NativeReactAmwalPay.js

@@ -18,7 +18,12 @@ export let TransactionType = /*#__PURE__*/function (TransactionType) {
   return TransactionType;
 }({});
 
-// This interface is for JavaScript side only, not for the native module spec
+/**
+ * Configuration interface for Amwal Pay SDK
+ *
+ * @interface AmwalPayConfig
+ * @description Complete configuration for initializing and starting a payment session
+ */
 
 // This is the configuration that will be passed to the native module
 

package/lib/module/NativeReactAmwalPay.js.map

@@ -1 +1 @@
-{"version":3,"names":["TurboModuleRegistry","Environment","Currency","TransactionType","getEnforcing"],"sourceRoot":"../../src","sources":["NativeReactAmwalPay.ts"],"mappings":";;AACA,SAASA,mBAAmB,QAAQ,cAAc;AAElD,WAAYC,WAAW,0BAAXA,WAAW;EAAXA,WAAW;EAAXA,WAAW;EAAXA,WAAW;EAAA,OAAXA,WAAW;AAAA;AAMvB,WAAYC,QAAQ,0BAARA,QAAQ;EAARA,QAAQ;EAAA,OAARA,QAAQ;AAAA;AAIpB,WAAYC,eAAe,0BAAfA,eAAe;EAAfA,eAAe;EAAfA,eAAe;EAAfA,eAAe;EAAA,OAAfA,eAAe;AAAA;;AAY3B;;AAmBA;;AAwBA,eAAeH,mBAAmB,CAACI,YAAY,CAAO,eAAe,CAAC","ignoreList":[]}
+{"version":3,"names":["TurboModuleRegistry","Environment","Currency","TransactionType","getEnforcing"],"sourceRoot":"../../src","sources":["NativeReactAmwalPay.ts"],"mappings":";;AACA,SAASA,mBAAmB,QAAQ,cAAc;AAElD,WAAYC,WAAW,0BAAXA,WAAW;EAAXA,WAAW;EAAXA,WAAW;EAAXA,WAAW;EAAA,OAAXA,WAAW;AAAA;AAMvB,WAAYC,QAAQ,0BAARA,QAAQ;EAARA,QAAQ;EAAA,OAARA,QAAQ;AAAA;AAIpB,WAAYC,eAAe,0BAAfA,eAAe;EAAfA,eAAe;EAAfA,eAAe;EAAfA,eAAe;EAAA,OAAfA,eAAe;AAAA;;AAY3B;AACA;AACA;AACA;AACA;AACA;;AAsDA;;AAwBA,eAAeH,mBAAmB,CAACI,YAAY,CAAO,eAAe,CAAC","ignoreList":[]}

package/lib/typescript/src/NativeReactAmwalPay.d.ts

@@ -17,23 +17,64 @@ export interface AmwalPayResponse {
     message: string;
     data?: Object;
 }
+/**
+ * Configuration interface for Amwal Pay SDK
+ *
+ * @interface AmwalPayConfig
+ * @description Complete configuration for initializing and starting a payment session
+ */
 export interface AmwalPayConfig {
+    /** Target environment (SIT, UAT, or PROD) */
     environment: Environment;
+    /** Secure hash for authentication */
     secureHash: string;
+    /** Transaction currency */
     currency: Currency;
+    /** Transaction amount as string (e.g., "100.000") */
     amount: string;
+    /** Merchant identifier */
     merchantId: string;
+    /** Terminal identifier */
     terminalId: string;
+    /** Locale for UI language ('en' or 'ar') */
     locale: string;
+    /** Optional customer identifier */
     customerId: string | null;
+    /** Type of transaction (NFC, CARD_WALLET, APPLE_PAY) */
     transactionType: TransactionType;
+    /** Optional session token (auto-fetched if not provided) */
     sessionToken?: string;
+    /** Optional transaction ID (auto-generated if not provided) */
     transactionId?: string;
+    /**
+     * Optional additional configuration values
+     *
+     * Supported keys:
+     * - `useBottomSheetDesign`: 'true' | 'false' - Use bottom sheet design (v2) instead of full screen
+     * - `ignoreReceipt`: 'true' | 'false' - Skip receipt display after transaction
+     * - `primaryColor`: Hex color string (e.g., '#FF5733') - Primary theme color
+     * - `secondaryColor`: Hex color string (e.g., '#33FF57') - Secondary theme color
+     * - `merchantIdentifier`: String - Apple Pay merchant identifier (default: 'merchant.applepay.amwalpay')
+     *
+     * @example
+     * ```typescript
+     * additionValues: {
+     *   useBottomSheetDesign: 'true',
+     *   primaryColor: '#1E88E5',
+     *   secondaryColor: '#FFC107',
+     *   ignoreReceipt: 'false',
+     *   merchantIdentifier: 'merchant.applepay.amwalpay'
+     * }
+     * ```
+     */
     additionValues?: {
         [key: string]: string;
     };
+    /** Optional merchant reference for transaction tracking */
     merchantReference?: string;
+    /** Callback for payment response */
     onResponse: (response: AmwalPayResponse) => void;
+    /** Callback for customer ID updates */
     onCustomerId: (customerId: string) => void;
 }
 export interface AmwalPayNativeConfig {

package/lib/typescript/src/NativeReactAmwalPay.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"NativeReactAmwalPay.d.ts","sourceRoot":"","sources":["../../../src/NativeReactAmwalPay.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAGhD,oBAAY,WAAW;IACrB,GAAG,QAAQ;IACX,GAAG,QAAQ;IACX,IAAI,SAAS;CACd;AAED,oBAAY,QAAQ;IAClB,GAAG,QAAQ;CACZ;AAED,oBAAY,eAAe;IACzB,GAAG,QAAQ;IACX,WAAW,gBAAgB;IAC3B,SAAS,cAAc;CACxB;AAED,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAGD,MAAM,WAAW,cAAc;IAC7B,WAAW,EAAE,WAAW,CAAC;IACzB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,QAAQ,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,eAAe,EAAE,eAAe,CAAC;IACjC,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,cAAc,CAAC,EAAE;QAAE,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAAA;KAAE,CAAC;IAC3C,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,UAAU,EAAE,CAAC,QAAQ,EAAE,gBAAgB,KAAK,IAAI,CAAC;IACjD,YAAY,EAAE,CAAC,UAAU,EAAE,MAAM,KAAK,IAAI,CAAC;CAC5C;AAGD,MAAM,WAAW,oBAAoB;IACnC,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,eAAe,EAAE,MAAM,CAAC;IACxB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,cAAc,CAAC,EAAE;QAAE,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAAA;KAAE,CAAC;IAC3C,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED,MAAM,WAAW,IAAK,SAAQ,WAAW;IAEvC,QAAQ,CAAC,MAAM,EAAE,oBAAoB,GAAG,IAAI,CAAC;IAC7C,WAAW,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACrC,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CACtC;;AAED,wBAAuE"}
+{"version":3,"file":"NativeReactAmwalPay.d.ts","sourceRoot":"","sources":["../../../src/NativeReactAmwalPay.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAGhD,oBAAY,WAAW;IACrB,GAAG,QAAQ;IACX,GAAG,QAAQ;IACX,IAAI,SAAS;CACd;AAED,oBAAY,QAAQ;IAClB,GAAG,QAAQ;CACZ;AAED,oBAAY,eAAe;IACzB,GAAG,QAAQ;IACX,WAAW,gBAAgB;IAC3B,SAAS,cAAc;CACxB;AAED,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;;;;GAKG;AACH,MAAM,WAAW,cAAc;IAC7B,6CAA6C;IAC7C,WAAW,EAAE,WAAW,CAAC;IACzB,qCAAqC;IACrC,UAAU,EAAE,MAAM,CAAC;IACnB,2BAA2B;IAC3B,QAAQ,EAAE,QAAQ,CAAC;IACnB,qDAAqD;IACrD,MAAM,EAAE,MAAM,CAAC;IACf,0BAA0B;IAC1B,UAAU,EAAE,MAAM,CAAC;IACnB,0BAA0B;IAC1B,UAAU,EAAE,MAAM,CAAC;IACnB,4CAA4C;IAC5C,MAAM,EAAE,MAAM,CAAC;IACf,mCAAmC;IACnC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,wDAAwD;IACxD,eAAe,EAAE,eAAe,CAAC;IACjC,4DAA4D;IAC5D,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,+DAA+D;IAC/D,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,cAAc,CAAC,EAAE;QAAE,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAAA;KAAE,CAAC;IAC3C,2DAA2D;IAC3D,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,oCAAoC;IACpC,UAAU,EAAE,CAAC,QAAQ,EAAE,gBAAgB,KAAK,IAAI,CAAC;IACjD,uCAAuC;IACvC,YAAY,EAAE,CAAC,UAAU,EAAE,MAAM,KAAK,IAAI,CAAC;CAC5C;AAGD,MAAM,WAAW,oBAAoB;IACnC,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,eAAe,EAAE,MAAM,CAAC;IACxB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,cAAc,CAAC,EAAE;QAAE,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAAA;KAAE,CAAC;IAC3C,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED,MAAM,WAAW,IAAK,SAAQ,WAAW;IAEvC,QAAQ,CAAC,MAAM,EAAE,oBAAoB,GAAG,IAAI,CAAC;IAC7C,WAAW,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACrC,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CACtC;;AAED,wBAAuE"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-amwal-pay",
-  "version": "0.1.14",
+  "version": "0.1.15",
   "description": "amwal pay",
   "main": "./lib/module/index.js",
   "types": "./lib/typescript/src/index.d.ts",

package/src/NativeReactAmwalPay.ts

@@ -4,7 +4,7 @@ import { TurboModuleRegistry } from 'react-native';
 export enum Environment {
   SIT = 'SIT',
   UAT = 'UAT',
-  PROD = 'PROD'
+  PROD = 'PROD',
 }
 
 export enum Currency {
@@ -14,7 +14,7 @@ export enum Currency {
 export enum TransactionType {
   NFC = 'NFC',
   CARD_WALLET = 'CARD_WALLET',
-  APPLE_PAY = 'APPLE_PAY'
+  APPLE_PAY = 'APPLE_PAY',
 }
 
 export interface AmwalPayResponse {
@@ -23,22 +23,62 @@ export interface AmwalPayResponse {
   data?: Object; // Changed from 'any' to 'Object'
 }
 
-// This interface is for JavaScript side only, not for the native module spec
+/**
+ * Configuration interface for Amwal Pay SDK
+ *
+ * @interface AmwalPayConfig
+ * @description Complete configuration for initializing and starting a payment session
+ */
 export interface AmwalPayConfig {
+  /** Target environment (SIT, UAT, or PROD) */
   environment: Environment;
+  /** Secure hash for authentication */
   secureHash: string;
+  /** Transaction currency */
   currency: Currency;
+  /** Transaction amount as string (e.g., "100.000") */
   amount: string;
+  /** Merchant identifier */
   merchantId: string;
+  /** Terminal identifier */
   terminalId: string;
+  /** Locale for UI language ('en' or 'ar') */
   locale: string;
+  /** Optional customer identifier */
   customerId: string | null;
+  /** Type of transaction (NFC, CARD_WALLET, APPLE_PAY) */
   transactionType: TransactionType;
+  /** Optional session token (auto-fetched if not provided) */
   sessionToken?: string;
+  /** Optional transaction ID (auto-generated if not provided) */
   transactionId?: string;
+  /**
+   * Optional additional configuration values
+   *
+   * Supported keys:
+   * - `useBottomSheetDesign`: 'true' | 'false' - Use bottom sheet design (v2) instead of full screen
+   * - `ignoreReceipt`: 'true' | 'false' - Skip receipt display after transaction
+   * - `primaryColor`: Hex color string (e.g., '#FF5733') - Primary theme color
+   * - `secondaryColor`: Hex color string (e.g., '#33FF57') - Secondary theme color
+   * - `merchantIdentifier`: String - Apple Pay merchant identifier (default: 'merchant.applepay.amwalpay')
+   *
+   * @example
+   * ```typescript
+   * additionValues: {
+   *   useBottomSheetDesign: 'true',
+   *   primaryColor: '#1E88E5',
+   *   secondaryColor: '#FFC107',
+   *   ignoreReceipt: 'false',
+   *   merchantIdentifier: 'merchant.applepay.amwalpay'
+   * }
+   * ```
+   */
   additionValues?: { [key: string]: string };
+  /** Optional merchant reference for transaction tracking */
   merchantReference?: string;
+  /** Callback for payment response */
   onResponse: (response: AmwalPayResponse) => void;
+  /** Callback for customer ID updates */
   onCustomerId: (customerId: string) => void;
 }