Payment Sandbox

The Payment Sandbox feature simulates payment flows for Apple Pay, Google Pay, and PayPal, allowing you to test payment integrations without real money or production payment processors. This feature mocks the Payment Request API and Apple Pay Session to provide a realistic testing environment.

Overview

This feature provides three modes for payment simulation:

• Off: Disables payment simulation entirely
• Virtual (Mock): Generates mock payment UI and responses locally
• Gateway (API Integration): Integrates with platform API for advanced payment routing (Pro tier)

Target Users

• Frontend developers implementing payment flows
• QA engineers testing payment integrations
• E-commerce developers testing checkout flows
• Security researchers testing payment security

Use Cases

• Test Apple Pay integration without real cards
• Test Google Pay button and flow
• Test PayPal checkout integration
• Test payment error handling
• Validate payment UI on mobile devices
• Debug payment method detection

How It Works

Technical Implementation

The feature intercepts payment APIs in the MAIN world:

window.ApplePaySession // Apple Pay API
window.PaymentRequest // Payment Request API (Google Pay, PayPal)

Apple Pay Simulation

MockApplePaySession Class:

• Replaces window.ApplePaySession with mock implementation
• Implements key methods:
  • canMakePayments() → Returns true
  • supportsVersion(version) → Returns true for versions ≤ 12
  • begin() → Triggers merchant validation and shows mock UI
  • completeMerchantValidation() → Mock merchant session
  • completePayment(status) → Mock payment completion
  • abort() → Mock session abort

Payment Flow:

1. Site calls new ApplePaySession(version, paymentRequest)
2. Mock session initializes with request details
3. begin() called → triggers onvalidatemerchant with mock validation URL
4. Merchant validation completed with mock session
5. Mock payment UI displayed (iOS-style sheet)
6. User approves → onpaymentauthorized triggered with mock token
7. Payment completed with mock payment data

Payment Request API Simulation

MockPaymentRequest Class:

• Replaces window.PaymentRequest when feature is active
• Implements Payment Request API for Google Pay and PayPal
• Returns mock response with:
  • Mock payment token
  • Mock payment method details
  • Mock transaction ID
  • complete() method for status updates

Payment Flow:

1. Site calls new PaymentRequest(methodData, details, options)
2. Mock request created if feature active
3. show() called → displays mock payment UI
4. Merchant validation mocked (if callback provided)
5. Mock payment UI displayed (iOS-style sheet)
6. User approves → resolves with mock response
7. Site calls complete(status) to finalize

Mock Payment UI

The feature renders a high-fidelity iOS-style payment sheet:

UI Components:

• Backdrop blur overlay
• Bottom sheet with rounded corners
• Header with payment method title (Apple Pay/Google Pay/PayPal)
• Total amount display
• Payment method card (network, last 4 digits, name)
• Pay button with brand color and icon

Brand Colors:

• Apple Pay: Black (#000)
• Google Pay: Blue (#4285F4)
• PayPal: PayPal Blue (#0070ba)

Interaction:

• Cancel button (X) → rejects payment
• Pay button → shows loading spinner → approves after 1.2s delay

Mock Payment Data

Token Structure:

{
  paymentData: {
    version: 'EC_v1',
    data: 'EMULUXE_FULL_MOCK_' + timestamp,
    signature: 'MOCK_SIG',
    header: {}
  },
  paymentMethod: {
    displayName: 'Visa 1234',
    network: 'Visa',
    type: 'debit'
  },
  transactionIdentifier: 'EMULUXE_TXN_' + timestamp
}

Architecture-Specific Implementation

Web Platform (Primary)

Location: src/engines/payment-sandbox-engine.js

The Web Platform implementation includes:

• Dynamic script injection into simulated pages
• Platform API integration for Gateway mode
• Session-based configuration management
• Real-time mode switching via postMessage

Key Features:

• Platform API base URL derived from script source
• Test card configuration from platform
• Session cleanup on page unload

Chrome Extension

Location: engine/payment-sandbox-engine.js

The extension implementation mirrors the platform with:

• MAIN world injection via content scripts
• chrome.storage for test card configuration
• Extension panel for payment settings
• Background script for API relay

Key Differences:

• Uses chrome.runtime messaging
• Test card stored in extension storage
• Integrates with device simulation context

VS Code Extension

Location: src/extension.ts (UI controls only)

The VS Code extension provides:

• UI controls for mode selection (Off/Virtual/Gateway)
• Payment method selection (Apple Pay/Google Pay/PayPal)
• Test card configuration
• Delegates actual simulation to platform

Integration: Sends commands to platform via vscode.postMessage, which then injects the engine.

Testing Guide

Enabling the Feature

Web Platform:

1. Open Device Settings panel
2. Navigate to "Payment Sandbox" section
3. Select mode: Off, Virtual, or Gateway
4. Select payment method: Apple Pay, Google Pay, or PayPal
5. Configure test card details if needed
6. For Gateway mode, ensure Pro tier and valid authentication

Chrome Extension:

1. Click Emuluxe toolbar icon
2. Expand "Payment Sandbox" control
3. Use segmented control to select mode
4. Choose payment method from dropdown
5. Configure test card if needed

VS Code Extension:

1. Open Emuluxe panel (Cmd+Alt+E)
2. Navigate to Device Features
3. Toggle Payment Sandbox controls
4. Select payment method from dropdown
5. Configure test card in sidebar

Testing Apple Pay Flows

Steps:

1. Enable Payment Sandbox in Virtual mode
2. Select "Apple Pay" as payment method
3. Navigate to Apple Pay demo site
4. Click Apple Pay button
5. Mock payment sheet appears
6. Verify total amount display
7. Click "Pay with Apple Pay"
8. Verify loading spinner
9. Payment approved with mock token

Expected Behavior:

• Apple Pay button enabled (canMakePayments returns true)
• Payment sheet appears with iOS styling
• Merchant validation succeeds
• Mock token generated and returned
• Payment completes successfully

Testing Google Pay Flows

Steps:

1. Enable Payment Sandbox in Virtual mode
2. Select "Google Pay" as payment method
3. Navigate to Google Pay demo site
4. Click Google Pay button
5. Mock payment sheet appears (Google Pay blue theme)
6. Verify total amount display
7. Click "Pay with Google Pay"
8. Verify loading spinner
9. Payment approved with mock token

Expected Behavior:

• Google Pay button enabled
• Payment Request API intercepted
• Mock payment sheet with Google Pay branding
• Mock token with Google Pay method
• Payment completes successfully

Testing PayPal Integration

Steps:

1. Enable Payment Sandbox in Virtual mode
2. Select "PayPal" as payment method
3. Navigate to PayPal demo site
4. Click PayPal button
5. Mock payment sheet appears (PayPal blue theme)
6. Verify total amount display
7. Click "Pay with PayPal"
8. Verify loading spinner
9. Payment approved with mock token

Expected Behavior:

• PayPal button enabled
• Payment Request API intercepted
• Mock payment sheet with PayPal branding
• Mock token with PayPal method
• Payment completes successfully

Testing Payment Validation

Test Cases:

1. Valid Payment: Approve payment → success callback triggered
2. Cancel Payment: Click X → failure callback triggered
3. Invalid Amount: Test with zero/negative amounts
4. Missing Details: Test with incomplete payment request
5. Network Error: Simulate network failure in Gateway mode

Verification:

• Check console for payment flow logs
• Verify token structure in response
• Test error handling in application
• Validate UI states (loading, success, error)

Common Issues and Troubleshooting

Issue: Apple Pay button disabled

• Cause: Apple Pay Session not mocked or feature not enabled
• Fix: Enable Payment Sandbox, select Apple Pay, reload page

Issue: Payment sheet doesn't appear

• Cause: Payment Request not intercepted or mode is Off
• Fix: Check mode is Virtual/Gateway, verify feature enabled

Issue: Payment fails with validation error

• Cause: Merchant validation not mocked correctly
• Fix: Check console for validation logs, verify mock implementation

Issue: Test card not configured

• Cause: Test card details missing from configuration
• Fix: Configure test card in platform settings or extension panel

Issue: Gateway mode fails with "Plan limit reached"

• Cause: Free tier attempting Gateway mode
• Fix: Upgrade to Pro tier or use Virtual mode

Issue: Payment token invalid format

• Cause: Token generation failed or structure mismatch
• Fix: Check console for token generation logs, verify token format

Recommended Testing Sites

Apple Pay Testing

Apple Pay Demo - https://applepaydemo.apple.com/

• Official Apple Pay demonstration
• Test Apple Pay button and flow
• Verify merchant validation
• Check payment sheet appearance

Stripe Apple Pay Demo - https://stripe.com/docs/apple-pay

• Stripe's Apple Pay integration demo
• Test with Stripe Elements
• Verify token handling
• Check error states

Google Pay Testing

Google Pay Demo - https://pay.google.com/gp/p/home

• Official Google Pay demo environment
• Test Google Pay button
• Verify Payment Request API
• Check payment method detection

Google Pay API Demo - https://developers.google.com/pay/api/web/guides/test-and-debug

• Google's official testing guide
• Test card configurations
• Verify payment flow
• Check test environments

PayPal Testing

PayPal Sandbox - https://developer.paypal.com/dashboard/accounts/sandbox

• PayPal's official sandbox environment
• Test PayPal checkout
• Verify payment flow
• Check test account integration

PayPal Demo - https://www.paypal.com/us/webapps/mpp/checkout/demo

• PayPal's checkout demo
• Test PayPal button
• Verify payment sheet
• Check integration

E-commerce Demo Sites

Shopify Demo Store - https://demo.shopify.com/

• Full e-commerce checkout flow
• Test multiple payment methods
• Verify cart and checkout
• Check mobile responsiveness

BigCommerce Demo - https://www.bigcommerce.com/demo/

• E-commerce platform demo
• Test payment integration
• Verify checkout flow
• Check error handling

Benefits for Users

Test Payment Flows Without Real Money

• No risk of accidental charges
• No need for test cards
• Instant payment simulation
• No dependency on payment processors

Test Payment Method Detection

• Verify Apple Pay detection logic
• Test Google Pay availability checks
• Check PayPal integration
• Validate fallback behavior

Debug Payment UI Issues

• Inspect payment sheet rendering
• Test button states and styling
• Verify mobile responsiveness
• Check accessibility features

Test Error Handling Scenarios

• Simulate payment failures
• Test network errors
• Validate error messages
• Check retry logic

Cross-Platform Consistency

• Same behavior across Web Platform, Extension, and VS Code
• Reproducible payment flows
• Consistent mock data
• No reliance on real payment infrastructure

Realistic Payment Experience

• iOS-style payment sheet
• Brand-specific colors and icons
• Loading states and animations
• Authentic user interaction flow