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.
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.
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.
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.
Before you begin using Visa Commercial Virtual Authentication APIs, complete the standard VDP setup requirements:
Additionally, ensure you meet the product-specific eligibility requirements:
Sandbox Environment:
Start a Project
API Overview
API Reference
Base URL: https://sandbox.api.visa.com
Production Environment:
Base URL: https://api.visa.com
URL Construction Pattern:
{baseURL}/vca/v1/{resource-path}
Example URLs:
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:
For detailed authentication setup, including MLE configuration for account number protection, see the Authentication Methods section.
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:
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.
Essential business rules, technical constraints, and integration considerations for successful 3DS authentication implementation.
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.
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 |
Follow these core business rules to prevent integration failures:
Understand these system constraints when designing your integration:
Special authentication requirements apply to Virtual Authentication APIs:
Follow these proven integration patterns for optimal results:
Your integration is successful when these outcomes are achieved:
Based on pilot program feedback, avoid these common challenges:
Additional common struggle and integration mistake patterns will be documented as pilot programs provide more operational feedback.
Learn the primary workflows for implementing 3DS authentication for commercial virtual cards through the Commercial Directory and Authentication APIs.
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.
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/create
3. Get User Mapping: Request data for previously submitted user mapping records to verify setup or troubleshoot issues.
POST /vca/v1/user-mappings/update
4. 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/update
5. Delete User Mapping: Remove previously submitted user mapping records when cards are deactivated or user access is revoked.
POST /vca/v1/user-mappings/delete
6. Check Request Status: Monitor the processing status of directory operations using the request ID returned from asynchronous operations.
GET /vca/v1/user-mappings/request-status
7. 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/response
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-type
3. 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/initiate
4. 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/request
For 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/result
6. 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/result
7. Save Authentication Record: Record the authentication result for compliance and audit purposes.
POST /vca/v1/commercial-auth-data/authentication-record
8. Complete Transaction: The ACS provider verifies the end user and provides response to merchant site with the fully authenticated response, completing the authentication process.
Implement different authentication methods based on user setup and security requirements:
Requirements: Ability to send OTP to cardholder email address or phone number.
Requirements: Mobile app capability to support biometric authentication of cardholders.
Commercial Directory operations use asynchronous processing patterns. Follow these best practices:
Validate successful integration by completing these key workflows:
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.
Enhanced security authentication using Two-way SSL with Message Level Encryption for APIs containing account numbers in the Virtual Authentication solution.
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.
Obtain the required credentials through the standard VDP eligibility process with additional Virtual Authentication requirements:
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.
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.
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:
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.
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.
Validate your authentication setup using these testing approaches:
Recommended Test Sequence:
Authentication configuration remains consistent across environments:
Environment-Specific Considerations:
Common authentication issues and resolutions:
Product-specific error codes and troubleshooting guidance for Commercial Directory and 3DS Authentication operations.
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.
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.
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. |
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. |
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. |
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:
Commercial Directory operations use asynchronous processing with specific error handling patterns:
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"
}
]
}
Based on pilot program feedback, these error patterns indicate common integration issues:
Additional error patterns and troubleshooting guidance will be updated as pilot programs provide more operational data.
Implement these error handling strategies for robust Virtual Authentication integration: