@gmisoftware/react-native-pay 0.0.12 → 0.0.14

package/android/src/main/java/com/margelo/nitro/pay/GooglePayRequestBuilder.kt

@@ -3,22 +3,27 @@ package com.margelo.nitro.pay
 import com.google.android.gms.wallet.WalletConstants
 import org.json.JSONArray
 import org.json.JSONObject
+import java.util.Locale
 
 /**
  * Builder for Google Pay API request objects
  */
 object GooglePayRequestBuilder {
+    private val googlePayPriceLocale = Locale.US
     
     /**
      * Creates an IsReadyToPay request
      */
-    fun createIsReadyToPayRequest(): JSONObject {
+    fun createIsReadyToPayRequest(existingPaymentMethodRequired: Boolean? = null): JSONObject {
         return JSONObject().apply {
             put("apiVersion", PaymentConstants.API_VERSION)
             put("apiVersionMinor", PaymentConstants.API_VERSION_MINOR)
             put("allowedPaymentMethods", JSONArray().apply {
                 put(createBaseCardPaymentMethod())
             })
+            existingPaymentMethodRequired?.let {
+                put("existingPaymentMethodRequired", it)
+            }
         }
     }
     
@@ -29,6 +34,8 @@ object GooglePayRequestBuilder {
         request: PaymentRequest,
         environment: Int
     ): JSONObject {
+        validatePaymentRequest(request, environment)
+
         return JSONObject().apply {
             put("apiVersion", PaymentConstants.API_VERSION)
             put("apiVersionMinor", PaymentConstants.API_VERSION_MINOR)
@@ -51,7 +58,7 @@ object GooglePayRequestBuilder {
             put("merchantName", request.merchantName ?: PaymentConstants.DEFAULT_MERCHANT_NAME)
             // Add merchant ID only for PRODUCTION environment
             if (environment == WalletConstants.ENVIRONMENT_PRODUCTION) {
-                put("merchantId", request.merchantIdentifier)
+                put("merchantId", request.googlePayMerchantId)
             }
         }
     }
@@ -88,20 +95,42 @@ object GooglePayRequestBuilder {
         request: PaymentRequest,
         environment: Int
     ): JSONObject {
+        val isProduction = environment == WalletConstants.ENVIRONMENT_PRODUCTION
+        val gateway = if (isProduction) {
+            request.googlePayGateway!!.trim()
+        } else {
+            request.googlePayGateway?.trim().takeUnless { it.isNullOrEmpty() }
+                ?: PaymentConstants.DEFAULT_GATEWAY
+        }
+        val gatewayMerchantId = if (isProduction) {
+            request.googlePayGatewayMerchantId!!.trim()
+        } else {
+            request.googlePayGatewayMerchantId?.trim().takeUnless { it.isNullOrEmpty() }
+                ?: PaymentConstants.DEFAULT_GATEWAY_MERCHANT_ID
+        }
+
         return JSONObject().apply {
             put("type", PaymentConstants.TOKENIZATION_PAYMENT_GATEWAY)
             put("parameters", JSONObject().apply {
-                val isProduction = environment == WalletConstants.ENVIRONMENT_PRODUCTION
-                put("gateway", request.googlePayGateway ?: PaymentConstants.DEFAULT_GATEWAY)
-                put(
-                    "gatewayMerchantId",
-                    request.googlePayGatewayMerchantId 
-                        ?: if (isProduction) request.merchantIdentifier 
-                        else PaymentConstants.DEFAULT_GATEWAY_MERCHANT_ID
-                )
+                put("gateway", gateway)
+                put("gatewayMerchantId", gatewayMerchantId)
             })
         }
     }
+
+    private fun validatePaymentRequest(request: PaymentRequest, environment: Int) {
+        if (environment != WalletConstants.ENVIRONMENT_PRODUCTION) return
+
+        require(!request.googlePayMerchantId.isNullOrBlank()) {
+            "googlePayMerchantId is required in PRODUCTION"
+        }
+        require(!request.googlePayGateway.isNullOrBlank()) {
+            "googlePayGateway is required in PRODUCTION"
+        }
+        require(!request.googlePayGatewayMerchantId.isNullOrBlank()) {
+            "googlePayGatewayMerchantId is required in PRODUCTION"
+        }
+    }
     
     /**
      * Creates transaction info
@@ -111,7 +140,7 @@ object GooglePayRequestBuilder {
         
         return JSONObject().apply {
             put("totalPriceStatus", PaymentConstants.TOTAL_PRICE_STATUS_FINAL)
-            put("totalPrice", String.format("%.2f", totalAmount))
+            put("totalPrice", formatPrice(totalAmount))
             put("totalPriceLabel", PaymentConstants.TOTAL_PRICE_LABEL_DEFAULT)
             put("currencyCode", request.currencyCode)
             put("countryCode", request.countryCode)
@@ -138,11 +167,15 @@ object GooglePayRequestBuilder {
                         else 
                             PaymentConstants.PENDING_TYPE
                     )
-                    put("price", String.format("%.2f", item.amount))
+                    put("price", formatPrice(item.amount))
                 })
             }
         }
     }
+
+    private fun formatPrice(amount: Double): String {
+        return String.format(googlePayPriceLocale, "%.2f", amount)
+    }
     
     /**
      * Creates allowed auth methods

package/android/src/main/java/com/margelo/nitro/pay/HybridPaymentHandler.kt

@@ -5,6 +5,7 @@ import android.content.Intent
 import android.util.Log
 import com.facebook.react.bridge.ActivityEventListener
 import com.facebook.react.bridge.ReactApplicationContext
+import com.google.android.gms.tasks.Tasks
 import com.google.android.gms.wallet.AutoResolveHelper
 import com.google.android.gms.wallet.IsReadyToPayRequest
 import com.google.android.gms.wallet.PaymentData
@@ -14,6 +15,7 @@ import com.google.android.gms.wallet.Wallet
 import com.google.android.gms.wallet.WalletConstants
 import com.margelo.nitro.core.Promise
 import com.margelo.nitro.NitroModules
+import java.util.concurrent.TimeUnit
 
 /**
  * Hybrid implementation of PaymentHandler for Google Pay on Android
@@ -38,15 +40,23 @@ class HybridPaymentHandler : HybridPaymentHandlerSpec(), ActivityEventListener {
     
     override fun payServiceStatus(): PayServiceStatus {
         return try {
-            val request = IsReadyToPayRequest.fromJson(
-                GooglePayRequestBuilder.createIsReadyToPayRequest().toString()
-            )
-            
             val client = createPaymentsClient(currentEnvironment)
-            client.isReadyToPay(request) // Trigger async check
-            
-            // Return optimistic status (actual check is async)
-            PayServiceStatus(canMakePayments = true, canSetupCards = true)
+            val canSetupCards = isReadyToPay(
+                client = client,
+                requestJson = GooglePayRequestBuilder.createIsReadyToPayRequest(
+                    existingPaymentMethodRequired = false
+                )
+            )
+            val canMakePayments = isReadyToPay(
+                client = client,
+                requestJson = GooglePayRequestBuilder.createIsReadyToPayRequest(
+                    existingPaymentMethodRequired = true
+                )
+            )
+            PayServiceStatus(
+                canMakePayments = canMakePayments,
+                canSetupCards = canSetupCards
+            )
         } catch (e: Exception) {
             Log.e(PaymentConstants.TAG_PAYMENT_HANDLER, "Error checking status", e)
             PayServiceStatus(canMakePayments = false, canSetupCards = false)
@@ -143,6 +153,15 @@ class HybridPaymentHandler : HybridPaymentHandlerSpec(), ActivityEventListener {
             GooglePayEnvironment.TEST, null -> WalletConstants.ENVIRONMENT_TEST
         }
     }
+
+    private fun isReadyToPay(
+        client: PaymentsClient,
+        requestJson: org.json.JSONObject
+    ): Boolean {
+        val request = IsReadyToPayRequest.fromJson(requestJson.toString())
+        val task = client.isReadyToPay(request)
+        return Tasks.await(task, 5, TimeUnit.SECONDS) ?: false
+    }
     
     private fun launchPaymentUI(
         paymentDataRequest: org.json.JSONObject,

package/ios/HybridPaymentHandler.swift

@@ -6,21 +6,31 @@ import NitroModules
 
 private enum ErrorMessage {
     static let paymentCancelled = "Payment cancelled by user"
+    static let paymentDismissed = "Payment sheet was dismissed before authorization"
+    static let missingMerchantIdentifier = "No Apple Pay merchant identifier configured"
     static let unableToPresent = "Unable to present payment authorization"
     static let unableToCreate = "Unable to create payment authorization"
 }
 
+private enum BundleKey {
+    static let applePayMerchantIdentifiers = "ReactNativePayApplePayMerchantIdentifiers"
+}
+
 // MARK: - Payment Request Builder
 
 private struct PaymentRequestBuilder {
     
-    static func build(from request: PaymentRequest) -> PKPaymentRequest {
+    static func build(from request: PaymentRequest) -> PKPaymentRequest? {
+        guard let merchantIdentifier = resolveMerchantIdentifier(from: request) else {
+            return nil
+        }
+
         let paymentRequest = PKPaymentRequest()
         
-        paymentRequest.merchantIdentifier = request.merchantIdentifier
+        paymentRequest.merchantIdentifier = merchantIdentifier
         paymentRequest.countryCode = request.countryCode
         paymentRequest.currencyCode = request.currencyCode
-        paymentRequest.paymentSummaryItems = buildPaymentItems(request.paymentItems)
+        paymentRequest.paymentSummaryItems = buildPaymentItems(for: request)
         paymentRequest.merchantCapabilities = buildMerchantCapabilities(request.merchantCapabilities)
         paymentRequest.supportedNetworks = buildSupportedNetworks(request.supportedNetworks)
         
@@ -32,9 +42,33 @@ private struct PaymentRequestBuilder {
         
         return paymentRequest
     }
+
+    private static func resolveMerchantIdentifier(from request: PaymentRequest) -> String? {
+        if let overrideIdentifier = request.applePayMerchantIdentifier?.trimmingCharacters(in: CharacterSet.whitespacesAndNewlines),
+           !overrideIdentifier.isEmpty {
+            return overrideIdentifier
+        }
+
+        if let merchantIdentifiers = Bundle.main.object(
+            forInfoDictionaryKey: BundleKey.applePayMerchantIdentifiers
+        ) as? [String] {
+            return merchantIdentifiers.first {
+                !$0.trimmingCharacters(in: CharacterSet.whitespacesAndNewlines).isEmpty
+            }
+        }
+
+        if let merchantIdentifier = Bundle.main.object(
+            forInfoDictionaryKey: BundleKey.applePayMerchantIdentifiers
+        ) as? String {
+            let trimmedIdentifier = merchantIdentifier.trimmingCharacters(in: CharacterSet.whitespacesAndNewlines)
+            return trimmedIdentifier.isEmpty ? nil : trimmedIdentifier
+        }
+
+        return nil
+    }
     
-    private static func buildPaymentItems(_ items: [PaymentItem]) -> [PKPaymentSummaryItem] {
-        return items.map { item in
+    private static func buildPaymentItems(for request: PaymentRequest) -> [PKPaymentSummaryItem] {
+        let lineItems = request.paymentItems.map { item in
             let pkItem = PKPaymentSummaryItem(
                 label: item.label,
                 amount: NSDecimalNumber(decimal: Decimal(item.amount))
@@ -42,6 +76,29 @@ private struct PaymentRequestBuilder {
             pkItem.type = item.type == .final ? .final : .pending
             return pkItem
         }
+
+        guard request.paymentItems.count > 1 else {
+            return lineItems
+        }
+
+        let totalAmount = request.paymentItems.reduce(Decimal.zero) { partialResult, item in
+            partialResult + Decimal(item.amount)
+        }
+        let totalLabel: String
+        if let merchantName = request.merchantName?
+            .trimmingCharacters(in: CharacterSet.whitespacesAndNewlines),
+           !merchantName.isEmpty {
+            totalLabel = merchantName
+        } else {
+            totalLabel = "Total"
+        }
+        let totalItem = PKPaymentSummaryItem(
+            label: totalLabel,
+            amount: NSDecimalNumber(decimal: totalAmount)
+        )
+        totalItem.type = .final
+
+        return lineItems + [totalItem]
     }
     
     private static func buildMerchantCapabilities(_ capabilities: [String]) -> PKMerchantCapability {
@@ -129,10 +186,16 @@ private struct PaymentTokenConverter {
 private class PaymentDelegate: NSObject, PKPaymentAuthorizationViewControllerDelegate {
     private weak var paymentHandler: HybridPaymentHandler?
     private var paymentAuthorized: Bool = false
+    private var presentationDate: Date?
+    private let userDismissThreshold: TimeInterval = 0.75
     
     init(paymentHandler: HybridPaymentHandler) {
         self.paymentHandler = paymentHandler
     }
+
+    func markPresented() {
+        presentationDate = Date()
+    }
     
     func paymentAuthorizationViewController(
         _ controller: PKPaymentAuthorizationViewController,
@@ -163,11 +226,19 @@ private class PaymentDelegate: NSObject, PKPaymentAuthorizationViewControllerDel
     func paymentAuthorizationViewControllerDidFinish(_ controller: PKPaymentAuthorizationViewController) {
         controller.dismiss(animated: true) {
             if !self.paymentAuthorized {
+                let errorMessage: String
+                if let presentationDate = self.presentationDate,
+                   Date().timeIntervalSince(presentationDate) >= self.userDismissThreshold {
+                    errorMessage = ErrorMessage.paymentCancelled
+                } else {
+                    errorMessage = ErrorMessage.paymentDismissed
+                }
+
                 let result = PaymentResult.init(
                     success: false,
                     transactionId: nil,
                     token: nil,
-                    error: ErrorMessage.paymentCancelled
+                    error: errorMessage
                 )
                 self.paymentHandler?.handlePaymentResult(result)
             }
@@ -216,7 +287,10 @@ class HybridPaymentHandler: HybridPaymentHandlerSpec {
     // MARK: - Private Methods
     
     private func performPayment(request: PaymentRequest, completion: @escaping (PaymentResult) -> Void) {
-        let paymentRequest = PaymentRequestBuilder.build(from: request)
+        guard let paymentRequest = PaymentRequestBuilder.build(from: request) else {
+            completion(createErrorResult(ErrorMessage.missingMerchantIdentifier))
+            return
+        }
         
         paymentCompletion = completion
         currentPaymentRequest = paymentRequest
@@ -229,12 +303,14 @@ class HybridPaymentHandler: HybridPaymentHandlerSpec {
         
         paymentAuthVC.delegate = delegate
         
-        guard let rootViewController = UIApplication.shared.windows.first?.rootViewController else {
+        guard let rootViewController = getRootViewController() else {
             completion(createErrorResult(ErrorMessage.unableToPresent))
             return
         }
         
-        rootViewController.present(paymentAuthVC, animated: true)
+        rootViewController.present(paymentAuthVC, animated: true) {
+            self.delegate?.markPresented()
+        }
     }
     
     private func createErrorResult(_ error: String) -> PaymentResult {
@@ -245,4 +321,35 @@ class HybridPaymentHandler: HybridPaymentHandlerSpec {
             error: error
         )
     }
+
+    private func getRootViewController() -> UIViewController? {
+        let scenes = UIApplication.shared.connectedScenes
+            .compactMap { $0 as? UIWindowScene }
+            .filter { $0.activationState == .foregroundActive }
+
+        let rootViewController = scenes
+            .flatMap(\.windows)
+            .first(where: \.isKeyWindow)?
+            .rootViewController
+
+        return topViewController(from: rootViewController)
+    }
+
+    private func topViewController(from viewController: UIViewController?) -> UIViewController? {
+        guard let viewController else { return nil }
+
+        if let navigationController = viewController as? UINavigationController {
+            return topViewController(from: navigationController.visibleViewController)
+        }
+
+        if let tabBarController = viewController as? UITabBarController {
+            return topViewController(from: tabBarController.selectedViewController)
+        }
+
+        if let presentedViewController = viewController.presentedViewController {
+            return topViewController(from: presentedViewController)
+        }
+
+        return viewController
+    }
 }

package/lib/hooks/__tests__/usePaymentCheckout.integration.test.d.ts

@@ -0,0 +1 @@
+export {};

package/lib/hooks/__tests__/usePaymentCheckout.integration.test.js

@@ -0,0 +1,191 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const react_native_1 = require("@testing-library/react-native");
+const mockPayServiceStatus = jest.fn();
+const mockStartPayment = jest.fn();
+jest.mock('react-native-nitro-modules', () => ({
+    NitroModules: {
+        createHybridObject: jest.fn(() => ({
+            payServiceStatus: (...args) => mockPayServiceStatus(...args),
+            startPayment: (...args) => mockStartPayment(...args),
+        })),
+    },
+}));
+const usePaymentCheckout_1 = require("../usePaymentCheckout");
+describe('usePaymentCheckout integration', () => {
+    beforeEach(() => {
+        mockPayServiceStatus.mockReturnValue({
+            canMakePayments: true,
+            canSetupCards: true,
+        });
+        mockStartPayment.mockReset();
+    });
+    const renderCheckout = () => (0, react_native_1.renderHook)(() => (0, usePaymentCheckout_1.usePaymentCheckout)({}));
+    it('loads payment service status on mount', async () => {
+        const { result } = renderCheckout();
+        await (0, react_native_1.waitFor)(() => {
+            expect(result.current.isCheckingStatus).toBe(false);
+        });
+        expect(result.current.canMakePayments).toBe(true);
+        expect(result.current.canSetupCards).toBe(true);
+    });
+    it('falls back to unavailable status when status check fails', async () => {
+        mockPayServiceStatus.mockImplementationOnce(() => {
+            throw new Error('Native status failure');
+        });
+        const consoleSpy = jest.spyOn(console, 'error').mockImplementation(() => { });
+        const { result } = renderCheckout();
+        await (0, react_native_1.waitFor)(() => {
+            expect(result.current.isCheckingStatus).toBe(false);
+        });
+        expect(result.current.canMakePayments).toBe(false);
+        expect(result.current.canSetupCards).toBe(false);
+        expect(consoleSpy).toHaveBeenCalled();
+        consoleSpy.mockRestore();
+    });
+    it('manages cart operations and total correctly', async () => {
+        const { result } = renderCheckout();
+        await (0, react_native_1.waitFor)(() => {
+            expect(result.current.isCheckingStatus).toBe(false);
+        });
+        (0, react_native_1.act)(() => {
+            result.current.addItem('Coffee', 4.5);
+            result.current.addItems([
+                { label: 'Sandwich', amount: 8.25 },
+                { label: 'Tip', amount: 1.25, type: 'pending' },
+            ]);
+        });
+        expect(result.current.items).toEqual([
+            { label: 'Coffee', amount: 4.5, type: 'final' },
+            { label: 'Sandwich', amount: 8.25, type: 'final' },
+            { label: 'Tip', amount: 1.25, type: 'pending' },
+        ]);
+        expect(result.current.total).toBeCloseTo(14);
+        (0, react_native_1.act)(() => {
+            result.current.updateItem(0, { amount: 5 });
+        });
+        expect(result.current.items[0]?.amount).toBe(5);
+        expect(result.current.total).toBeCloseTo(14.5);
+        (0, react_native_1.act)(() => {
+            result.current.removeItem(1);
+        });
+        expect(result.current.items.map((item) => item.label)).toEqual([
+            'Coffee',
+            'Tip',
+        ]);
+        (0, react_native_1.act)(() => {
+            result.current.clearItems();
+        });
+        expect(result.current.items).toEqual([]);
+        expect(result.current.total).toBe(0);
+    });
+    it('provides default fallback payment item when cart is empty', () => {
+        const { result } = renderCheckout();
+        expect(result.current.paymentRequest.paymentItems).toEqual([
+            { label: 'Total', amount: 0, type: 'final' },
+        ]);
+        expect(result.current.paymentRequest.countryCode).toBe('US');
+        expect(result.current.paymentRequest.currencyCode).toBe('USD');
+    });
+    it('rejects startPayment when cart is empty', async () => {
+        const { result } = renderCheckout();
+        let paymentResult = 'not-called';
+        await (0, react_native_1.act)(async () => {
+            paymentResult = await result.current.startPayment();
+        });
+        expect(paymentResult).toBeNull();
+        expect(result.current.error?.message).toBe('Cart is empty');
+        expect(mockStartPayment).not.toHaveBeenCalled();
+    });
+    it('handles successful payments', async () => {
+        const nativeSuccess = { success: true, transactionId: 'tx_123' };
+        mockStartPayment.mockResolvedValueOnce(nativeSuccess);
+        const { result } = renderCheckout();
+        (0, react_native_1.act)(() => {
+            result.current.addItem('Coffee', 4.99);
+        });
+        let paymentResult = null;
+        await (0, react_native_1.act)(async () => {
+            paymentResult = await result.current.startPayment();
+        });
+        expect(mockStartPayment).toHaveBeenCalledTimes(1);
+        expect(mockStartPayment).toHaveBeenCalledWith(expect.objectContaining({
+            paymentItems: [{ label: 'Coffee', amount: 4.99, type: 'final' }],
+        }));
+        expect(paymentResult).toEqual(nativeSuccess);
+        expect(result.current.result).toEqual(nativeSuccess);
+        expect(result.current.error).toBeNull();
+        expect(result.current.isProcessing).toBe(false);
+    });
+    it('sets an error when native payment response has success=false', async () => {
+        mockStartPayment.mockResolvedValueOnce({
+            success: false,
+            error: 'Declined by issuer',
+        });
+        const { result } = renderCheckout();
+        (0, react_native_1.act)(() => {
+            result.current.addItem('Order', 9.99);
+        });
+        await (0, react_native_1.act)(async () => {
+            await result.current.startPayment();
+        });
+        expect(result.current.error?.message).toBe('Declined by issuer');
+        expect(result.current.result).toEqual({
+            success: false,
+            error: 'Declined by issuer',
+        });
+    });
+    it('forwards Apple Pay override and Google Pay config when provided', async () => {
+        mockStartPayment.mockResolvedValueOnce({ success: true });
+        const { result } = (0, react_native_1.renderHook)(() => (0, usePaymentCheckout_1.usePaymentCheckout)({
+            applePayMerchantIdentifier: 'merchant.com.apple.override',
+            googlePayMerchantId: 'google-pay-merchant-id',
+            googlePayEnvironment: 'PRODUCTION',
+            googlePayGateway: 'stripe',
+            googlePayGatewayMerchantId: 'gateway-merchant-id',
+        }));
+        (0, react_native_1.act)(() => {
+            result.current.addItem('Order', 12);
+        });
+        await (0, react_native_1.act)(async () => {
+            await result.current.startPayment();
+        });
+        expect(mockStartPayment).toHaveBeenCalledWith(expect.objectContaining({
+            applePayMerchantIdentifier: 'merchant.com.apple.override',
+            googlePayMerchantId: 'google-pay-merchant-id',
+            googlePayEnvironment: 'PRODUCTION',
+            googlePayGateway: 'stripe',
+            googlePayGatewayMerchantId: 'gateway-merchant-id',
+        }));
+    });
+    it('uses generic error for non-Error thrown values', async () => {
+        mockStartPayment.mockRejectedValueOnce('native crash');
+        const { result } = renderCheckout();
+        (0, react_native_1.act)(() => {
+            result.current.addItem('Order', 12);
+        });
+        let paymentResult = 'not-null';
+        await (0, react_native_1.act)(async () => {
+            paymentResult = await result.current.startPayment();
+        });
+        expect(paymentResult).toBeNull();
+        expect(result.current.error?.message).toBe('Payment processing failed');
+    });
+    it('resets transient checkout state', async () => {
+        mockStartPayment.mockResolvedValueOnce({ success: false, error: 'Failed' });
+        const { result } = renderCheckout();
+        (0, react_native_1.act)(() => {
+            result.current.addItem('Order', 3);
+        });
+        await (0, react_native_1.act)(async () => {
+            await result.current.startPayment();
+        });
+        expect(result.current.error).not.toBeNull();
+        (0, react_native_1.act)(() => {
+            result.current.reset();
+        });
+        expect(result.current.error).toBeNull();
+        expect(result.current.result).toBeNull();
+        expect(result.current.isProcessing).toBe(false);
+    });
+});

package/lib/hooks/usePaymentCheckout.d.ts

@@ -1,13 +1,56 @@
 import type { PaymentRequest, PaymentResult, PaymentItem, GooglePayEnvironment } from '../types';
+/**
+ * Configuration for `usePaymentCheckout`.
+ */
 export interface UsePaymentCheckoutConfig {
-    merchantIdentifier: string;
+    /**
+     * Merchant name shown by payment providers that support displaying it.
+     * Used primarily by Google Pay.
+     */
     merchantName?: string;
+    /**
+     * ISO 3166-1 alpha-2 country code for the transaction.
+     * Defaults to `'US'`.
+     */
     countryCode?: string;
+    /**
+     * ISO 4217 currency code for all payment items.
+     * Defaults to `'USD'`.
+     */
     currencyCode?: string;
+    /**
+     * Supported card networks for the payment sheet.
+     * Defaults to `['visa', 'mastercard', 'amex', 'discover']`.
+     */
     supportedNetworks?: string[];
+    /**
+     * Merchant capabilities passed to Apple Pay.
+     * Defaults to `['3DS']`.
+     */
     merchantCapabilities?: string[];
+    /**
+     * Optional Apple Pay Merchant ID override.
+     * When omitted, iOS reads the Merchant ID from the app entitlements.
+     */
+    applePayMerchantIdentifier?: string;
+    /**
+     * Google Pay merchant ID used in Android production requests.
+     * Not needed for iOS.
+     */
+    googlePayMerchantId?: string;
+    /**
+     * Google Pay environment for Android requests.
+     * Use `'TEST'` for sandbox flows and `'PRODUCTION'` for live payments.
+     */
     googlePayEnvironment?: GooglePayEnvironment;
+    /**
+     * Payment gateway identifier for Google Pay tokenization.
+     * Examples include `'stripe'`, `'braintree'`, and `'adyen'`.
+     */
     googlePayGateway?: string;
+    /**
+     * Merchant ID provided by your payment gateway for Google Pay tokenization.
+     */
     googlePayGatewayMerchantId?: string;
 }
 export interface UsePaymentCheckoutReturn {
@@ -41,7 +84,8 @@ export interface UsePaymentCheckoutReturn {
  * - Payment processing
  * - State management
  *
- * @param config - Payment configuration
+ * @param config - Hook configuration including locale, supported networks,
+ * Apple Pay override, and Google Pay gateway settings.
  * @returns Complete payment checkout interface
  *
  * @example
@@ -58,9 +102,9 @@ export interface UsePaymentCheckoutReturn {
  *     isProcessing,
  *     error,
  *   } = usePaymentCheckout({
- *     merchantIdentifier: 'merchant.com.example',
  *     currencyCode: 'USD',
  *     countryCode: 'US',
+ *     googlePayMerchantId: 'your_google_pay_merchant_id',
  *   })
  *
  *   // Add single item