Visa Commercial Virtual Authentication
Product Overview
Visa Commercial Virtual Authentication is a 3DS authentication solution enabling Third Parties to securely verify the identity of commercial card users. It works by storing cardholder details in the Visa Commercial Directory, routing authentication requests from an Access Control Server (ACS), and confirming the cardholder against the directory. The service then applies the authentication method stored—such as one-time passcode (OTP) or biometric—ensuring a smooth, secure experience while reducing fraud and acceptance issues.
The primary audiences for this solution are Issuers and Fintechs who need to reduce CNP fraud and protect chargeback rights by authenticating virtual cardholders before authorization, and Companies who need to ensure only authorized employees, travelers, or contractors can use issued virtual cards for online purchases.
Visa Commercial Virtual Authentication API List
Commercial Directory
Use the Commercial Directory to manage the user-to-account mappings that enable 3DS authentication for commercial virtual card programs. Before a cardholder can be authenticated at checkout, their account number, user ID, and preferred authentication method must be registered in the directory. This service uses an asynchronous model—each request returns an immediate acknowledgment with a unique request ID, and results are either delivered to a callback URL or retrieved by polling. The service supports batch operations of up to 250 records per request.
- Create User Mapping
- Get User Mapping
- Update User Mapping
- Delete User Mapping
- Get Request Status
Commercial 3DS Authentication
The Commercial 3DS Authentication service manages the 3-D Secure (3DS) step-up authentication workflow for commercial virtual cards. When a cardholder initiates an online transaction, this service determines the available authentication method for the account—such as one-time passcode (OTP) or biometric—and triggers the appropriate challenge. After the challenge is completed, the service records the final authentication outcome.
- Get Authentication Method
- Initiate Authentication
- Submit Validation Result
- Save Authentication Record
Virtual Authentication Getting Started
This page provides information needed to begin integrating with Visa Commercial Virtual Authentication. Review the prerequisites, configure authentication and environment settings, and make your first API call.
Prerequisites
Before you begin using Visa Commercial Virtual Authentication APIs, complete the standard VDP setup requirements:
- Review the Visa Developer Quick Start Guide for account setup and API credential configuration
- Obtain your API credentials (User ID, Password, Certificate) from the Visa Developer Portal
- Configure your development environment for API integration
Additionally, ensure you meet the product-specific eligibility requirements:
- Issuer Status: You must be an Issuer or any Fintech acting on behalf of an Issuer
- Participation Agreement: Issuers are required to sign a Participation Agreement to use the APIs
- Cardholder Information: You must have information on cardholders to support authentication processes
- OTP Delivery Capability: You must have the ability to send OTP numbers to cardholder email addresses or phone numbers
- Mobile App: You must have a Mobile App to support Biometric authentication of cardholders
Environment Hosts & URL Recipe
Sandbox Environment:
Base URL: https://sandbox.api.visa.comProduction Environment:
Base URL: https://api.visa.comURL Construction Pattern:
{baseURL}/vca/v1/{resource-path}Example URLs:
- Commercial Directory: /vca/v1/user-mappings/create
- Commercial 3DS Authentication: /vca/v1/commercial-lookup/credential-type
Headers and Authentication
Visa Commercial Virtual Authentication uses Two-way SSL with Message Level Encryption (MLE) for APIs that contain account numbers. This provides enhanced security for sensitive cardholder data.
Required Headers:
- Content-Type: application/json
- Accept: application/json
- Authorization: Basic {base64-encoded-credentials}
For detailed authentication setup, including MLE configuration for account number protection, see the Authentication Methods section.
First API Call
Test your integration by creating a user mapping in the Commercial Directory. This is typically the first step in setting up 3DS authentication for a virtual card user.
Endpoint: POST /vca/v1/user-mappings/create
Sample Request:
POST /vca/v1/user-mappings/create
Content-Type: application/json
{
"sequenceNumber": "1",
"userMappings": [
{
"accountNumber": "4000000000001001",
"userId": "testuser123",
"authenticationMethod": "OTP",
"expirationDate": "2025-12-31"
}
]
}Expected Response Codes:
- 202 Accepted: Request successfully submitted for processing
- 400 Bad Request: Invalid request format or missing required fields
- 401 Unauthorized: Authentication failure
- 500 Internal Server Error: System processing error
Success Indicator:
Your integration is successful when a cardholder can be authenticated at the time of a card-not-present transaction via an eCommerce site using these APIs. The complete workflow includes user mapping creation, authentication method setup, and successful authentication challenge completion.
Virtual Authentication Things to Know
Essential business rules, technical constraints, and integration considerations for successful 3DS authentication implementation.
Introduction
Understanding the underlying business logic and technical requirements of Visa Commercial Virtual Authentication is critical for successful integration. This solution combines Commercial Directory management with real-time 3DS authentication challenges, requiring careful attention to asynchronous processing patterns and authentication method capabilities.
Resource Hierarchy
The following table shows the key resources and their dependencies in the Virtual Authentication system:
| Resource | Role | Dependency |
|---|---|---|
| Company/Issuer | Authentication Authority | Must have signed Participation Agreement |
| User Mapping | Identity Correlation | Requires valid account number and user ID |
| Authentication Method | Challenge Configuration | Depends on user mapping and technical capabilities |
| Authentication Record | Audit Trail | Created after successful challenge completion |
| Cardholder Transaction | Business Outcome | Requires complete authentication workflow |
Core Business Rules
Follow these core business rules to prevent integration failures:
- Authentication Prerequisites: You must have cardholder information to support authentication processes before creating user mappings
- OTP Delivery Capability: You must have the technical ability to send OTP numbers to cardholder email addresses or phone numbers
- Biometric Support: You must have a mobile application capable of supporting biometric authentication of cardholders
- User-to-Account Relationship: Each account can only map to one user at a time in the Commercial Directory
- Authentication Method Consistency: The authentication method specified in user mapping must match your technical capabilities
- Transaction Timing: Authentication challenges must be completed within the transaction timeframe
Guardrails & Limitations
Understand these system constraints when designing your integration:
- Batch Processing Limits: Maximum 250 user mappings per Commercial Directory request. Use batch operations efficiently to minimize API calls while staying within limits.
- Asynchronous Processing Requirements: Commercial Directory operations use asynchronous processing. Implement proper polling mechanisms or callback handling to track operation completion.
- Authentication Method Technical Requirements: OTP authentication requires SMS or email delivery capability. Biometric authentication requires mobile app with biometric capture functionality.
- Sequence Number Management: Unique sequence numbers are required for request correlation in bulk operations. Implement proper sequence number generation and tracking.
- Account Number Patterns: Account numbers must follow specific validation patterns. Ensure proper format validation before submitting user mappings.
Authentication Method Considerations
Special authentication requirements apply to Virtual Authentication APIs:
- Two-way SSL with MLE: APIs containing account numbers require Message Level Encryption for enhanced security
- Certificate Management: Proper certificate configuration is essential for Two-way SSL communication
- Request Correlation: Authentication requests must be properly correlated with user mappings for successful processing
- Challenge Response Timing: Authentication challenges have time limits that must be respected during implementation
Integration Patterns
Follow these proven integration patterns for optimal results:
- Event-Driven Architecture: Use callback URLs for asynchronous Commercial Directory operations when available
- State Management: Track user mapping IDs and authentication states throughout the workflow
- Error Handling: Implement comprehensive error handling for both synchronous and asynchronous operations
- Testing Strategy: Test both OTP and Biometric authentication paths in sandbox environment before production
- Compliance Tracking: Maintain authentication records for audit and compliance requirements
Success Indicators
Your integration is successful when these outcomes are achieved:
- Directory Operations: Successful creation, retrieval, update, and deletion of user mapping records
- Authentication Challenges: Successful completion of both OTP and Biometric authentication workflows
- Real-world Validation: Cardholder authentication during actual eCommerce transactions
- Event Processing: Proper handling of authentication requests and OTP delivery events
- Business Outcomes: Reduced fraud exposure and improved transaction approval rates for commercial virtual cards
Common Integration Pitfalls
Based on pilot program feedback, avoid these common challenges:
- Incomplete Prerequisites: Attempting authentication setup without proper cardholder information or delivery capabilities
- Asynchronous Processing Misunderstanding: Expecting synchronous responses from Commercial Directory operations
- Authentication Method Mismatch: Configuring authentication methods that don't match technical capabilities
- Sequence Number Conflicts: Reusing sequence numbers in bulk operations leading to correlation issues
- Certificate Configuration: Improper Two-way SSL or MLE setup causing authentication failures
Additional common struggle and integration mistake patterns will be documented as pilot programs provide more operational feedback.
How to Use Virtual Authentication
Learn the primary workflows for implementing 3DS authentication for commercial virtual cards through the Commercial Directory and Authentication APIs.
Workflow Overview
Visa Commercial Virtual Authentication supports two primary business workflows: Commercial Directory management for user mapping setup and Commercial 3DS Authentication for real-time cardholder verification. The typical client journey starts with user onboarding through directory mapping, then progresses to authentication challenges during eCommerce transactions.
The complete workflow enables companies to ensure only authorized employees, travelers, or contractors can use issued virtual cards for online purchases, while providing issuers with fraud prevention and chargeback protection.
Commercial Directory Workflow
The Commercial Directory workflow establishes user-to-account mappings that enable subsequent authentication processes:
1. User Onboarding Setup: Issuer/Corporate works with Fintech to ensure user is onboarded to the Fintech platform. An authorized user (Corporate employee or contractor) is assigned a virtual card.
2. Create User Mapping: Submit user mapping details to the Visa Commercial Directory, including account number, user ID, authentication method, and expiration date.
POST /vca/v1/user-mappings/create3. Get User Mapping: Request data for previously submitted user mapping records to verify setup or troubleshoot issues.
POST /vca/v1/user-mappings/update4. Update User Mapping: Update the end date, time zone, and authentication method type for an account number and user ID record when user preferences or security requirements change.
POST /vca/v1/user-mappings/update5. Delete User Mapping: Remove previously submitted user mapping records when cards are deactivated or user access is revoked.
POST /vca/v1/user-mappings/delete6. Check Request Status: Monitor the processing status of directory operations using the request ID returned from asynchronous operations.
GET /vca/v1/user-mappings/request-status7. Push User Mapping Response - Client Outbound Events: Provides response for user mapping operations (create, read, update, and delete) for API calls where callback option has been enabled.
POST /vca/v1/user-mapping/responseCommercial 3DS Authentication Workflow
The authentication workflow handles real-time cardholder verification during transactions:
1. Transaction Initiation: User enters card number in an online portal which initiates the Step-up authentication to ACS provider.
2. Authentication Method Lookup: ACS requests authentication method from VCS Orchestrator, which retrieves user details from the Visa Commercial Directory.
POST /vca/v1/commercial-lookup/credential-type3. InitiateAuthentication Challenge: Based on the authentication method (OTP or Biometric), the ACS provider will initiate the appropriate challenge process.
POST /vca/v1/commercial-step-up/auth/initiate4. Handle Authentication Method - Client Outbound Event: The Service transmits the authentication request from the ACS to the integrating party for end user authentication.
POST /vca/v1/auth/requestFor Biometric Authentication: Fintech performs authentication and submits results.
For OTP Authentication: Fintech receives OTP number and delivers it to cardholder via preferred method (SMS or email). User enters OTP in eCommerce interface.
5. Submit Validation Result: Submit the authentication outcome to complete the verification process.
POST /vca/v1/commercial-validate/result6. Push Biometric Authentication Result - ACS Provider Outbound Event: Service will forward the biometric authentication result received from the Fintech to ACS provider, enabling them to continue the authentication process.
POST /vca/v1/biometric/result7. Save Authentication Record: Record the authentication result for compliance and audit purposes.
POST /vca/v1/commercial-auth-data/authentication-record8. Complete Transaction: The ACS provider verifies the end user and provides response to merchant site with the fully authenticated response, completing the authentication process.
Authentication Method Implementation
Implement different authentication methods based on user setup and security requirements:
- OTP (One-Time Passcode) Method: Fintech receives OTP number from the
system and delivers it to the cardholder via their preferred method (e.g. SMS to
phone number or email). The cardholder enters the OTP in the eCommerce
authentication interface to complete verification.
Requirements: Ability to send OTP to cardholder email address or phone number.
- Biometric Authentication Method: Fintech performs biometric
authentication through their mobile application and submits the authentication
results to the system for verification.
Requirements: Mobile app capability to support biometric authentication of cardholders.
Asynchronous Processing Best Practices
Commercial Directory operations use asynchronous processing patterns. Follow these best practices:
- Handle 202 Accepted Responses: Directory operations return 202 Accepted with a requestId for tracking
- Implement Polling: Use the request status endpoint to check operation completion
- Configure Callbacks: Set up callback URLs for automatic status notifications when available
- Handle Batch Operations: Support up to 250 user mappings per request for efficient bulk processing
- Manage Sequence Numbers: Use unique sequence numbers for request correlation in bulk operations
Integration Success Validation
Validate successful integration by completing these key workflows:
- Commercial Directory Success: Successfully create, retrieve, update, and delete user mapping records
- Authentication Challenge Success: Complete end-to-end authentication for both OTP and Biometric methods
- Real-world Validation: Cardholder successfully authenticates during actual eCommerce transaction
- Event Handling: Properly receive and process authentication requests and OTP delivery requirements
The ultimate success indicator is when a cardholder can be authenticated at the time of a card-not-present transaction via an eCommerce site using these APIs, resulting in reduced fraud exposure and improved transaction approval rates.
Virtual Authentication Authentication Methods
Enhanced security authentication using Two-way SSL with Message Level Encryption for APIs containing account numbers in the Virtual Authentication solution.
Enhanced Authentication Overview
Visa Commercial Virtual Authentication implements Two-way SSL with Message Level Encryption (MLE) for APIs that contain account numbers. This enhanced security approach provides additional protection for sensitive cardholder data during Commercial Directory operations and authentication challenges.
The enhanced authentication combines standard VDP authentication patterns with product-specific encryption requirements to ensure maximum security for commercial virtual card authentication workflows.
Credential Acquisition
Obtain the required credentials through the standard VDP eligibility process with additional Virtual Authentication requirements:
- Issuer Status Verification: Confirm you are an Issuer or Fintech acting on behalf of an Issuer
- Participation Agreement: Complete and sign the required Participation Agreement for Virtual Authentication APIs
- Standard VDP Credentials: Obtain User ID, Password, and Certificate from the Visa Developer Portal
- MLE Certificate: Request Message Level Encryption certificate for account number protection
- Two-way SSL Configuration: Configure mutual authentication certificates for enhanced security
Authentication Setup Instructions
Configure your system for Two-way SSL with MLE authentication:
Install both the standard VDP certificate and the MLE certificate in your application's certificate store. Ensure proper certificate chain validation.
Configure your HTTP client for Two-way SSL (mutual authentication) with certificate-based client authentication enabled.
Implement Message Level Encryption for request payloads containing account numbers. This applies to Commercial Directory APIs that handle cardholder data.
Identify which API endpoints require MLE encryption based on payload content. Generally, any endpoint accepting account numbers requires encryption.
HTTP Header Construction
Construct proper HTTP headers for authenticated Virtual Authentication requests:
Content-Type: application/json
Accept: application/json
Authorization: Basic {base64-encoded-credentials}
x-pay-token: {encrypted-payload-when-MLE-required}Header Details:
- Authorization: Standard Basic authentication using VDP credentials
- x-pay-token: Include when MLE encryption is required for account number protection
- Content-Type: Always application/json for Virtual Authentication APIs
Message Level Encryption Implementation
Implement MLE encryption for APIs containing account numbers:
Identify requests containing account numbers that require MLE encryption:
Encrypt the request payload using your MLE certificate and include the encrypted payload in the x-pay-token header.
Send the encrypted payload in the header while maintaining standard JSON structure for non-sensitive fields in the request body.
Testing Authentication Connectivity
Validate your authentication setup using these testing approaches:
- Certificate Validation: Test Two-way SSL connectivity using a simple API call to verify mutual authentication
- MLE Encryption Test: Verify MLE encryption/decryption using a Commercial Directory operation in sandbox
- Header Verification: Confirm all required headers are properly constructed and accepted by the API
- Error Response Handling: Test authentication failure scenarios to ensure proper error handling
Recommended Test Sequence:
- Test basic Two-way SSL connectivity with a GET operation
- Test MLE encryption with a simple user mapping creation
- Verify end-to-end authentication workflow with test credentials
Environment Authentication Variations
Authentication configuration remains consistent across environments:
- Sandbox Environment: Use sandbox-specific certificates and credentials. MLE encryption is required but uses test encryption keys. All authentication workflows can be tested safely.
- Production Environment: Use production certificates with live MLE encryption keys. Participation Agreement must be fully executed before production access is granted.
Environment-Specific Considerations:
- Certificate management varies between sandbox and production
- MLE encryption keys are environment-specific
- Authentication endpoints remain consistent across environments
- No regional variations in authentication requirements identified
Authentication Troubleshooting
Common authentication issues and resolutions:
- Certificate Errors: Verify Two-way SSL certificate installation and mutual authentication configuration
- MLE Encryption Failures: Confirm MLE certificate validity and proper payload encryption
- 401 Unauthorized: Check Basic authentication credentials and header construction
- SSL Handshake Failures: Verify mutual authentication certificate configuration
- Missing x-pay-token: Ensure MLE encryption is implemented for account number-containing requests
Virtual Authentication Error Codes
Product-specific error codes and troubleshooting guidance for Commercial Directory and 3DS Authentication operations.
Error Handling Overview
Visa Commercial Virtual Authentication provides extensive product-specific error codes beyond standard VDP errors. These custom error codes support both Commercial Directory operations and Commercial 3DS Authentication workflows, with specific error handling for asynchronous processing patterns.
Error responses include detailed information for troubleshooting authentication challenges, user mapping issues, and system processing problems specific to virtual card authentication workflows.
Standard VDP Error Reference
In addition to the product-specific error codes documented below, Virtual Authentication APIs also return standard VDP error codes. Refer to the standard VDP error documentation for common HTTP status codes and general API error patterns.
Standard VDP errors typically cover authentication failures, malformed requests, and general system unavailability conditions that apply across all VDP APIs.
Commercial Directory Error Codes
Error codes specific to Commercial Directory operations for user mapping management:
| ERROR CODE | DESCRIPTION | CAUSE | RESOLUTION |
|---|---|---|---|
| VCMRS-CDS-ERR-4000 | General processing error | System processing failure during user mapping operation | Retry the operation after a brief delay. If persistent, contact support. |
| VCMRS-CDS-ERR-4019 | Invalid field value | User mapping contains invalid data format or values | Validate account number format, user ID, and authentication method values. |
| VCMRS-CDS-INFO-2002 | Success operation confirmation | User mapping operation completed successfully | No action required. Operation successful. |
Authentication Validation Error Codes
Validation-specific error codes for 3DS authentication processes:
| ERROR CODE | DESCRIPTION | CAUSE | RESOLUTION |
|---|---|---|---|
| VSERR-1002 | Invalid account number format | Account number does not match required pattern | Verify account number follows expected format and belongs to valid BIN range. |
| VSERR-1003 | User mapping not found | No user mapping exists for the provided account and user ID | Create user mapping in Commercial Directory before authentication. |
| VSERR-1004 | Authentication method mismatch | Requested authentication method does not match user mapping | Verify authentication method in user mapping or update mapping. |
| VSERR-1005 | Invalid user ID format | User ID contains invalid characters or format | Ensure user ID meets format requirements and character constraints. |
| VSERR-1025 | Validation processing timeout | Authentication validation exceeded time limits | Retry authentication with proper timing considerations. |
Authentication System Error Codes
System-specific errors related to authentication infrastructure and processing:
| ERROR CODE | DESCRIPTION | CAUSE | RESOLUTION |
|---|---|---|---|
| VSERR-2001 | Authentication service unavailable | Temporary authentication system unavailability | Implement retry logic with exponential backoff. |
| VSERR-2002 | OTP delivery failure | Unable to deliver OTP to cardholder contact information | Verify cardholder contact details and delivery method capabilities. |
| VSERR-2003 | Biometric authentication unavailable | Mobile app or biometric service not accessible | Ensure mobile app connectivity and biometric service availability. |
| VSERR-2004 | Authentication challenge expired | Authentication challenge timeout exceeded | Initiate new authentication challenge with proper timing. |
Error Response Format
Virtual Authentication APIs return structured error responses with consistent formatting:
{
"errorCode": "VSERR-1003",
"errorMessage": "User mapping not found",
"details": {
"accountNumber": "4***************",
"userId": "user123",
"requestId": "req_abc123456",
"timestamp": "2026-03-31T15:30:00Z"
},
"suggestedAction": "Create user mapping in Commercial Directory before authentication"
}Response Fields:
- errorCode: Specific product error code for programmatic handling
- errorMessage: Human-readable error description
- details: Context-specific information for troubleshooting
- suggestedAction: Recommended resolution steps
Asynchronous Processing Error Handling
Commercial Directory operations use asynchronous processing with specific error handling patterns:
- 202 Accepted with Later Errors: Initial request may be accepted but fail during processing
- Request Status Polling: Use request status endpoint to check for processing errors
- Callback Error Notifications: Configure callback URLs to receive error notifications
- Batch Operation Errors: Individual items in batch operations may succeed or fail independently
Batch Error Response Example:
{
"status": "207 Multi-Status",
"sequenceNumber": "1",
"results": [
{
"userMappingId": "mapping1",
"status": "SUCCESS",
"message": "User mapping created successfully"
},
{
"userMappingId": "mapping2",
"status": "ERROR",
"errorCode": "VSERR-1002",
"message": "Invalid account number format"
}
]
}Common Integration Error Patterns
Based on pilot program feedback, these error patterns indicate common integration issues:
- Repeated VSERR-1003 Errors: Indicates user mapping workflow not properly implemented
- VSERR-2002 OTP Failures: Suggests cardholder contact information or delivery capability issues
- VCMRS-CDS-ERR-4019 Pattern: Points to data validation problems in user mapping creation
- Authentication Timeout Errors: May indicate asynchronous processing misunderstanding
- Certificate-Related Errors: Often caused by improper Two-way SSL or MLE configuration
Additional error patterns and troubleshooting guidance will be updated as pilot programs provide more operational data.
Error Handling Best Practices
Implement these error handling strategies for robust Virtual Authentication integration:
- Retry Logic: Implement exponential backoff for transient system errors (VSERR-2001)
- Validation Before Submission: Pre-validate data formats to avoid VSERR-1002 and VCMRS-CDS-ERR-4019
- Dependency Checking: Verify user mappings exist before authentication challenges
- Timeout Management: Respect authentication challenge timing to avoid VSERR-2004
- Comprehensive Logging: Log error codes and request IDs for troubleshooting support
- User Experience: Provide meaningful error messages to end users without exposing technical details