LogoLogo
Explore with DeepWikiJoin Slack CommunityContact Us
  • About Hyperswitch
    • Introduction
    • Payments Suite
    • Payments Modules
      • Cost Observability
      • Revenue Recovery
      • Vault
        • Server to Server Vault tokenization
        • Vault SDK Integration
      • Intelligent Routing
      • Reconciliation
        • Getting Started with Recon
      • Alternate Payment Method Widgets
        • Hyperwidget Integration Guide
    • Roadmap - Q2 2025
      • Previous Roadmap - Q1 2025
      • Previous Roadmap - Q4 2024
      • Previous Roadmap - Q3 2024
      • Previous Roadmap - Q2 2024
      • Previous roadmap - Q1 2024
      • Previous roadmap - Q4 2023
  • Use-Cases
    • For SaaS Businesses
    • For B2B SaaS Businesses
    • For E-Commerce Businesses
    • For Marketplace/Platforms
  • Explore Hyperswitch
    • Payment Orchestration
      • Accept Payments
        • Connectors
          • Activate Connector on Hyperswitch
          • Try a Payment
          • Available Connectors
            • ACI
            • Adyen
            • Airwallex
            • Authorizedotnet
            • Bambora
            • Bank of America
            • Billwerk
            • Bluesnap
            • Braintree
            • Checkout
            • Coinbase
            • Cybersource
              • Apple Pay
              • Google Pay
            • dLocal
            • Fiserv
            • GlobalPayments
            • GoCardless
            • Klarna
            • Mollie
            • MultiSafepay
            • Nuvei
            • OpenNode
            • Paypal
            • PayU
            • Prophetpay
            • Rapyd
            • Shift4
            • Stripe
            • TrustPay
            • Volt
            • Worldline
            • Worldpay
            • Zen
            • Netcetera
              • Authenticating Payments via Netcetera Through HyperSwitch SDK
        • Setup Payment Methods
          • Cards
          • Wallets
            • Apple Pay
              • Web Domain
              • iOS Application
            • Google Pay
            • PayPal
          • Pay Later
          • Banks
            • Bank Debits
            • Bank Redirects
            • Bank Transfers
            • Open Banking
          • Crypto
          • Test Credentials
        • Payment Links
          • Configurations
          • Create Payment Links
          • Secure Payment Links
          • Setup Custom Domain
        • Save a Payment Method
        • Manual Capture
        • Incremental Authorization
        • Tokenization & Card Vault
          • Network Tokenisation
        • Supported Payment Workflows
        • Co-badged Cards
        • Webhooks
      • Process Payouts
        • Getting Started with Payouts
        • Using Saved Payment Methods
        • Smart Router for Payouts
        • Smart Retries in Payout
        • Payout Links
      • Smart Routing
        • Rule Based Routing
        • Volume Based Routing
        • Default Fallback Routing
      • Smart Retries
        • 3DS Step-up Retries
      • 3DS / Strong Customer Authentication
        • Setting up 3DS Decision Manager
        • Native 3DS Authentication
        • External Authentication for 3DS
      • Fraud & Risk Management
        • Activating FRM in Hyperswitch
        • Fraud Blocklist
      • Subscriptions
        • PG Agnostic Card Forwarding
        • Zero Amount Authorization
      • Split Payments
        • Stripe Split Payments
        • Adyen Split Payments
        • Xendit Split Payments
    • Checkout Experience
      • Customizable and Native Integrations
        • Web
          • Node And React
          • Customization
          • Error Codes
          • Node and HTML
          • Vanilla JS and REST API Integration
        • Android
          • Kotlin with Node Backend
          • Customization
          • Features
        • iOS
          • Swift with Node Backend
          • Customization
          • Features
        • React Native
          • React Native with Node Backend
          • Card Widget
          • Customization
        • Flutter
          • Flutter with Node Backend
          • Customization
        • Headless SDK
        • Server Setup
      • Click To Pay
        • Visa Click to Pay: V1 to V2 Migration
      • Payment Methods Management
    • Payment Operations
      • Managing Accounts and Profiles
        • ⚙️Control Centre Account setup
        • Hyperswitch Account Structure
      • Manage Your Team
      • Analytics & operations
        • Exporting payments data
      • Disputes / Chargebacks
      • Surcharge
        • Surcharge Setup guide
      • Multi-Tenancy
      • Data migration
        • Import data to Hyperswitch
        • Export data from Hyperswitch
    • Security and Compliance
      • PCI Compliance
      • Data Security
      • GDPR compliance
      • Identity and Access Management
    • E-commerce Platform Plugins by Hyperswitch
      • 🔌WooCommerce Plugin
        • Setup
        • Roadmap
        • Compatibility
        • FAQs
      • Saleor App
        • Setup
      • Automatic Tax calculation for Express Checkout wallets
  • Hyperswitch open source
    • Overview
      • Run Hyperswitch Locally Using Docker
        • Run Additional Services
      • Development Environment Setup
        • Backend
          • Configure and Run the Application
          • Try out APIs
        • SDK (Frontend)
        • Control Center
    • Deploy on AWS
      • Deploy on AWS using CloudFormation
      • Component-wise Deployment
        • Deploy app server
        • Deploy Control Center
        • Deploy web client
          • Production ready deployment
          • Integrate web client on your web app
          • Playground deployment for prototyping (optional)
        • Deploy Card Vault
          • Production ready deployment on AWS
          • Cloud setup guide
    • Deploy on Kubernetes
      • Deploy on GCP Using Helm Charts
      • Deploy on Azure Using Helm Charts
    • Exploration Guide
    • Account setup
      • Using Hyperswitch Control Center
      • Test a payment
      • Using postman
    • Troubleshooting
  • Testing Payments
  • Check list for Production
    • Going live
      • For SaaS Setup
      • For On-Prem Setup
        • Monitoring
        • PCI compliance
          • Get started
          • Completing the SAQ
        • Data Security
        • Updates
  • Learn more
    • API Reference
    • Connectors Supported
    • SDK Reference
      • React
      • JS
      • Custom Events
    • Hyperswitch architecture
      • Router
      • Storage
      • A Payments Switch with virtually zero overhead
    • Payment flows
    • Blog
  • Community Guidelines
Powered by GitBook

Compliance

  • Vulnerability Disclosure
  • PCI DSS 4.0
  • ISO 27001:2022

Community

  • Slack
  • Discord
  • GitHub Discussion
On this page
  • Seamless Migration with Hyperswitch
  • Integration Methods
  • Quick Start
  • New V2 Features
  • Authentication Methods
  • Migration Checklist
  • Best Practices
  • Performance Considerations
  • Common Issues and Solutions
  • Security Considerations
  • Testing Guide
  • Monitoring and Analytics
  • Support and Resources

Was this helpful?

  1. Explore Hyperswitch
  2. Checkout Experience
  3. Click To Pay

Visa Click to Pay: V1 to V2 Migration

Visa Click to Pay is evolving to provide a better checkout experience with enhanced security features and improved performance. This guide will help you migrate from V1 to V2 in less than 30 minutes.

Last updated 4 months ago

Was this helpful?

The evolution from Click to Pay V1 to V2 represents a fundamental shift in digital payment capabilities, addressing key merchant and consumer pain points while setting new standards for security and user experience. V2 introduces significant architectural improvements and feature enhancements that align with the industry's movement toward passwordless authentication and seamless checkout experiences. This transformation comes at a crucial time when digital commerce demands both frictionless transactions and robust security measures.

Feature Aspect

V1

V2

🔐 Security Features

⛔️ card data handling, prone to fraud.

✅ tokenization and biometric authentication, meeting FIDO standards.

🚀 Speed of Payment

⛔️ Requires multiple steps - OTPs are used for cardholder verification during online transactions, adding an extra layer of security but also introducing additional steps in the checkout process

✅ V2 integrates advanced authentication methods, such as biometrics and device recognition, reducing the reliance on OTPs. This shift enhances security while streamlining the user experience by minimizing interruptions during checkout.Biometric authentication reduces checkout time by 50%.

🛜 Integration

⛔️ Separate APIs and infrastructure for different card networks.

✅ Unified integration across multiple card network

🙎🏻‍♂️ User Experience

⛔️ Authentication requires username/password login for:

  • Initial service access

  • New device verification

  • Adding new cards

  • Accessing saved cards

⛔️ Separate authentication needed across different devices

⛔️ No device recognition capabilities

✅ Hybrid authentication approach:

  • Initial email/mobile verification still required

  • Optional biometric authentication for returning users

  • Payment passkey support being rolled out (not fully deployed)

  • Two-factor authentication for enhanced security

✅ Device-specific recognition:

  • "Remember me" option for trusted devices

  • Automatic recognition on returning to saved merchants

  • But requires initial setup per browser/device

💳 Push Provisioning

⛔️ Not supported. Users cannot add their cards directly to Click to Pay from the issuer's app.

✅ Supported. Issuers can enrol cardholders into Click to Pay directly from their banking app, streamlining the enrolment process.

🌏 Global Market Adoption

🚧 Limited deployment and compatibility with some regions and merchants.

✅ Available in 35+ countries, supported by major card networks

🔁 Recurring Payments

🚧 Limited support for saving credentials and managing recurring payments

✅ Built-in support for recurring payments and saved credentials

Seamless Migration with Hyperswitch

The migration to V2 is powered by Hyperswitch's specialized wrapper solution, ensuring a frictionless transition that protects your existing integration while unlocking next-generation features. Our wrapper automatically handles version detection, request/response mapping, and backward compatibility - eliminating the risk of business disruption during migration.

This guide will help you migrate from Visa Click to Pay SDK V1 to V2 in less than 30 minutes. Our wrapper maintains backward compatibility while giving you access to V2's enhanced features.

Integration Methods

Choose your integration path based on your business needs:

Method
Best For
Key Benefits
Considerations

PSP Integration

Small-medium businesses

• Fastest deployment • Minimal dev effort • PSP handles compliance

Limited customization

Acquirer Integration

Established merchants

• Moderate effort • Custom checkout • Existing bank relation

Shared compliance

Direct Integration

Large enterprises

• Full control • All features • Direct Visa support

Requires PCI-DSS

Decision factors: Dev resources, time to market, customization needs, compliance capabilities

Quick Start

Step 1: Install the Wrapper

npm install @visa/click-to-pay-wrapper

Step 2: Update Imports

// Old V1 Import
import { VisaSRCI } from '@visa/click-to-pay-v1';

// New V2 Import
import { VisaClickToPayWrapper } from '@visa/click-to-pay-wrapper';

Step 3: Initialize the SDK

// Old V1 Initialization
const visaCheckout = new VisaSRCI();
await visaCheckout.init({
    apikey: 'your_api_key',
    visaSrci: true
});

// New V2 Initialization
const visaCheckout = new VisaClickToPayWrapper({
    debug: true, // Optional: Enable debug logging
    apikey: 'your_api_key',
    srcInitiatorId: 'your_initiator_id',
    environment: 'production' // or 'sandbox' for testing
});
await visaCheckout.init();

Step 4: Update Configuration (if needed)

// Optional: Configure additional features
await visaCheckout.init({
    apiKey: 'your_api_key',
    environment: 'production',
    features: {
        biometrics: true,
        quickCheckout: true
    },
    locale: 'en-US' // Optional: Set preferred locale
});

Step 5: Implement Event Handlers (Optional)

// New event handling system
visaCheckout.on('checkout_started', (data) => {
    console.log('Checkout started:', data);
});

visaCheckout.on('payment_complete', (data) => {
    console.log('Payment complete:', data);
});

// Additional events available in V2
visaCheckout.on('authentication_required', (data) => {
    console.log('Authentication required:', data);
});

visaCheckout.on('biometric_prompt', (data) => {
    console.log('Biometric authentication prompted:', data);
});

Step 6: Update Checkout Implementation

// Both V1 and V2 formats work with the wrapper
const checkoutResponse = await visaCheckout.checkout({
    amount: '100.00',
    currency: 'USD',
    merchantName: 'Test Store'
});

New V2 Features

Device Authentication Support

Before enabling biometric authentication, verify device capabilities:

// Check biometric availability
const checkBiometricSupport = async () => {
    const capabilities = await visaCheckout.checkDeviceCapabilities();
    if (capabilities.biometrics) {
        // Enable biometric flow
        await visaCheckout.enableBiometrics();
    } else {
        // Fallback authentication methods in order of preference:
        // 1. Device binding (Remember this device)
        // 2. OTP verification
        // 3. Password authentication
        await visaCheckout.enableFallbackAuth({
            preferDeviceBinding: true,
            allowOTP: true
        });
    }
};

Enable Biometric Authentication

if (visaCheckout.version === 'v2') {
    try {
        await visaCheckout.enableBiometrics();
        console.log('Biometrics enabled successfully');
    } catch (error) {
        console.error('Biometrics setup failed:', error);
        // Fallback to traditional authentication
    }
}

Quick Checkout

if (visaCheckout.version === 'v2') {
    try {
        const quickCheckoutResponse = await visaCheckout.quickCheckout(token);
        console.log('Quick checkout completed:', quickCheckoutResponse);
    } catch (error) {
        console.error('Quick checkout failed:', error);
        // Fallback to regular checkout
        const regularCheckoutResponse = await visaCheckout.checkout(options);
    }
}

Error Handling Guide

Common Error Scenarios:

// Network and Connection Errors
NETWORK_ERROR: 'Connection failed during API call'
TIMEOUT_ERROR: 'Request timed out'
API_ERROR: 'API endpoint not responding'

// Authentication Errors
AUTH_INVALID: 'Invalid authentication credentials'
AUTH_EXPIRED: 'Authentication session expired'
BIOMETRIC_FAILED: 'Biometric authentication failed'

// Transaction Errors
CARD_DECLINED: 'Card was declined'
INSUFFICIENT_FUNDS: 'Insufficient funds'
RISK_DECLINE: 'Transaction declined due to risk assessment'

Error Handling Best Practices:

try {
    const response = await visaCheckout.checkout(options);
    handleSuccess(response);
} catch (error) {
    switch(error.code) {
        case 'NETWORK_ERROR':
            await retryWithBackoff(3); // Retry up to 3 times
            break;
        case 'AUTH_EXPIRED':
            await refreshAuthSession();
            break;
        case 'BIOMETRIC_FAILED':
            await fallbackToOTP();
            break;
        // Add more specific error handling
    }
}

Authentication Methods

V2 supports multiple authentication methods:

// Configure authentication preferences
await visaCheckout.init({
    apiKey: 'your_api_key',
    environment: 'production',
    authentication: {
        preferBiometric: true, // Prefer biometric when available
        fallbackToPassword: true, // Allow password as fallback
        allowRememberMe: true // Enable "Remember Me" feature
    }
});

// Handle authentication events
visaCheckout.on('authentication_method_selected', (method) => {
    switch(method) {
        case 'biometric':
            console.log('User selected biometric authentication');
            break;
        case 'password':
            console.log('User selected password authentication');
            break;
        case 'otp':
            console.log('One-time password required');
            break;
    }
});

Migration Checklist

Best Practices

  1. Use the wrapper for gradual migration

  2. Test both V1 and V2 flows in sandbox first

  3. Enable new features progressively

  4. Implement proper error handling

  5. Monitor for any issues after deployment

  6. Use feature detection for V2-specific features

  7. Maintain fallback options for all new features

  8. Test across different browsers and devices

  9. Monitor performance metrics

  10. Keep error handling and logging comprehensive

Performance Considerations

Lazy Loading

// Lazy load the SDK when needed
const loadSDK = async () => {
    if (!window.visaCheckout) {
        await import('@visa/click-to-pay-wrapper');
    }
    return window.visaCheckout;
};

Resource Optimization

// Configure optimal resource loading
await visaCheckout.init({
    apiKey: 'your_api_key',
    environment: 'production',
    loading: {
        preload: ['essential'], // Preload essential components
        lazy: ['biometrics', 'analytics'], // Lazy load optional features
        timeout: 5000 // Set reasonable timeouts
    }
});

Common Issues and Solutions

Configuration Format Mismatch

// Solution: Use wrapper's normalizeConfig method
const config = visaCheckout.normalizeConfig(yourConfig);

Event Handling Differences

// Solution: Use wrapper's unified event system
visaCheckout.on('checkout_started', handleCheckoutStarted);

Response Format Differences

// Solution: Wrapper automatically handles conversion
const response = await visaCheckout.checkout(options);

Version Detection Issues

// Solution: Explicitly check version compatibility
if (!visaCheckout.isFeatureSupported('biometrics')) {
    // Fallback to traditional authentication
}

Session Management

// Solution: Implement proper session handling
visaCheckout.on('session_expired', async () => {
    await visaCheckout.refreshSession();
    // Retry the last operation
});

Security Considerations

PCI Compliance

The wrapper maintains PCI compliance while handling sensitive data:

// Configure secure data handling
await visaCheckout.init({
    apiKey: 'your_api_key',
    environment: 'production',
    security: {
        pciCompliant: true,
        tokenization: true,
        encryptPayload: true
    }
});

Data Protection

// Enable additional security features
await visaCheckout.init({
    apiKey: 'your_api_key',
    environment: 'production',
    security: {
        validateOrigin: true,
        strictCSP: true,
        requireHTTPS: true
    }
});

Testing Guide

Sandbox Testing

// Initialize in sandbox mode
const visaCheckout = new VisaClickToPayWrapper({
    apikey: 'your_sandbox_api_key',
    environment: 'sandbox',
    debug: true
});

// Test card numbers
const testCards = {
    success: '4111111111111111',
    decline: '4000000000000002',
    error: '4000000000000069'
};

Error Simulation

// Test error scenarios
await visaCheckout.simulateError('NETWORK_ERROR');
await visaCheckout.simulateError('AUTHENTICATION_FAILED');
await visaCheckout.simulateError('CARD_DECLINED');

Testing Recurring Payments

// Test recurring payment setup
const recurringTest = async () => {
    // Initial charge
    const initial = await visaCheckout.checkout({
        amount: '10.00',
        currency: 'USD',
        recurring: true,
        recurringType: 'subscription'
    });

    // Subsequent charge
    const recurring = await visaCheckout.recurringCharge({
        originalTransactionId: initial.transactionId,
        amount: '10.00'
    });
};

Monitoring and Analytics

Enable Analytics

await visaCheckout.init({
    apiKey: 'your_api_key',
    environment: 'production',
    analytics: {
        enabled: true,
        captureErrors: true,
        capturePerformance: true
    }
});

Custom Event Tracking

// Track custom events
visaCheckout.trackEvent({
    category: 'Checkout',
    action: 'Started',
    label: 'Quick Checkout Button',
    value: cartTotal
});

Support and Resources

For additional support:

  • Contact Visa support team at support@visa.com

  • Visit our developer portal at https://developer.visa.com

  • Join our developer community at https://community.visa.com

Documentation

Remember to test thoroughly in the sandbox environment before deploying to production, and enable new features gradually to ensure a smooth transition for your users.

- JavaScript SDK reference for implementing Click to Pay

- Comprehensive implementation guide and requirements

- Best practices and implementation paths for merchants and payment service providers

View detailed comparison →
API Reference
Integration Overview
Merchant & PSP Guide
Architecture diagram of Visa Click to Pay integration, showing how the Wrapper mediates between Client browser/app and Visa's Click to Pay server while supporting both V1 and V2 SDKs.