Visa Commercial Fraud Solutions

Visa Commercial Payment Controls lets clients set controls on commercial card accounts to protect commercial payments and limit spending at the card level. Clients register existing card accounts and then apply dynamic, near real-time rules (for example: spending, merchant category, location, channel, and business hours), so authorization decisions align to business use cases.

The primary audience includes Fintechs, issuers, or processors who can use these services on behalf of an issuer and their portfolio, for B2B payments ranging from Commercial to Small Business card portfolios. The service can be used with physical plastic cards or virtual cards and is supported for contactless transactions.

Account Management Service

Use the Account Management Service to create accounts within the ranges specified during the onboarding of an issuer or commercial client. This service also lets you add payment controls, manage account contacts, update company information, delete accounts, and retrieve account details.

• Create Account
• Get Account
• Update Account
• Delete Account

Rules Management Service

After registering a card with VPC, you can use the Rules Management Service to manage payment controls for that card. The service includes operations to set, delete, retrieve, block, disable, and enable rules. These operations let you configure controls, review existing rule configurations, block an account, and temporarily disable or re-enable rules as needed.

• Set Rules
• Get Rules
• Delete Rules
• Block Account
• Disable Enable Rules

Reporting Management Service

The Reporting Management Service lets you retrieve transaction and notification details for a card.

• Get Notification History
• Set Notification History

Intelligent Payment Controls

The Intelligent Payment Controls (IPC) system uses generative AI to evaluate user prompts and recommend the most appropriate controls for commercial card transactions. Based on the provided input, IPC suggests a tailored set of controls that can be reviewed and confirmed before being applied.

• Get Suggested Rules
• Set Suggested Rules

Notification Service

The Notification Service lets issuers, fintechs, and users choose whether to receive optional email or SMS alerts when VPC blocks or approves a transaction authorization request. Notifications are sent to the contacts specified when the card account is created through the Account Management Service.

This service must be enabled during issuer and fintech onboarding to Visa Commercial Payment Controls (VPC).

This page provides information needed to begin integrating with Visa Commercial Payment Controls (VPC). Review the prerequisites, configure authentication and environment settings, and make your first API call.

Before you begin using Visa Commercial Payment Controls 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 Authorization: Participation must be done on behalf of an issuer and their portfolio
• Third-Party Agent Setup: If you are not the issuer directly, the issuer must grant authorization for your entity to act as an agent for the issuer
• Contracting Requirements: A Visa Representative will discuss contracting requirements during implementation
• Production Authorization: An issuer will be required prior to moving to production, and all API calls will be made on behalf of an issuer acting as a third-party agent

Technical prerequisites include:

• Issuer and Third-Party Configuration: Issuer and third-party agent (Fintech) should be onboarded and configured through VCS Hub
• Account Number Ranges: Account number ranges must be pre-configured during VPC implementation
• VisaNet Processing: Transactions must flow through VisaNet for authorization controls to be applied

Sandbox Environment:

Production Environment:

URL Construction Pattern:

Example URLs:

• Account Management: /vpc/v1/account/create
• Rules Management: /vpc/v1/rules/set
• Report Management: /vpc/v1/report/get-transaction-history
• Intelligent Payment Controls: /vpc/v1/vpcgenai/get

Visa Commercial Payment Controls uses Two-Way SSL (mutual authentication) with Message Level Encryption due to the sensitive nature of account information being sent.

Required Headers:

• Content-Type: application/json
• Accept: application/json
• Authorization: Basic {base64-encoded-credentials}

For detailed authentication setup, including Message Level Encryption configuration for account information protection, see the Authentication Methods section.

Test your integration by creating an account in the system. This is typically the first step in setting up payment controls for a card.

Endpoint: POST /vpc/v1/account/create

Sample Request:

Expected Response Codes:

• 200 OK: Successfully created Account
• 400 Bad Request: An invalid account number has been entered

Next Steps:

After successful account creation, proceed to configure initial payment control rules using the Rules Management APIs. Use the Report Management APIs to monitor transaction authorization decisions and rule effectiveness.

Essential business rules, technical constraints, and integration considerations for successful payment control implementation on commercial card accounts.

Understanding the underlying business logic and technical requirements of Visa Commercial Payment Controls is critical for successful integration. This solution enables dynamic, near real-time rule application for commercial card accounts, requiring careful attention to rule management patterns, authorization flow dependencies, and VisaNet processing requirements.

This table shows the key resources and their dependencies in the Visa Commercial Payment Controls system:

Follow these core business rules to prevent integration failures:

• VisaNet Processing Requirement: For the service to work, transactions must flow through VisaNet for authorization; authorization controls can only be applied to transactions on Visa branded cards that are processed through VisaNet
• On-Us Transaction Handling: For On-Us transactions or domestic processing scenarios, issuers/processors need to integrate through Visa Transaction Exchange (VTEX) and make a call out to VisaNet to apply the controls during authorization processing
• Issuer Authorization Requirement: Participation must be done on behalf of an issuer and their portfolio, with proper authorization for third-party agents
• Account Registration Precedence: Registering cards (Create Account) is required before setting any rules other than the Block Rule
• Rule Activation Immediacy: Rules are active immediately upon setting and apply to subsequent authorization requests
• Full Refresh Pattern: Set Rules API requires sending all rules to be applied in a single request (full refresh)
• Case-Insensitive Request Fields: API request fields are case-insensitive. All required fields must be present, but field order is flexible.
• Timezone Handling: GMT is used by default for time-based rules. A timezone override is available — specify a supported timezone when configuring channel and time-based rules. See Supported Time Zones for valid values.

Understand these system constraints when designing your integration:

• Payload Size Limitations: Each account can have multiple rules if the payload doesn't exceed 30720 bytes maximum size. The Rules Management error codes include "Payload size exceeds maximum allowed size of 30720 bytes."
• Historical Data Constraints: Report Management APIs have a 90-day historical data limit for transaction and notification history retrieval.
• Sandbox Environment Limitations: The sandbox environment provides only static values and a limited subset of possible requests. Clients cannot execute all API functionality or see the full list of accurate error codes through the API explorer in sandbox.
• Multi-Party Participation Scope: Services can be used by multiple parties including fintechs, issuers, or processors; however, participation must be done on behalf of an issuer and their portfolio. Supports physical plastic cards, virtual cards, and contactless transactions for B2B payments ranging from Commercial to Small Business card portfolios.

Special authentication requirements apply to Payment Controls APIs:

• Two-Way SSL Requirement: Visa Developer secures connections with clients using Two-Way SSL (mutual authentication)
• Message-Level Encryption: Required for API usage due to the sensitive nature of account information being sent
• Credential Management: Credentials and certificates for both SSL and message-level encryption are provided within the Visa Developer account

Important considerations for development and testing:

• API Specification Authority: Clients should code using the API specifications (including error codes) rather than mimicking the API explorer behavior in sandbox
• Production Environment Setup: Account ranges must be pre-configured during VPC implementation before production use
• Notification Templates: Notification templates require implementation setup and testing in production environment
• Real-time Processing: Production environment supports real-time transaction processing with immediate rule application
• Testing Limitations: Sandbox provides limited testing scenarios; comprehensive testing requires production-like data and configurations

Follow these proven integration patterns for optimal results:

• Sequential Setup Pattern: Follow the required sequence: Account > Rules > Monitoring > .
• State Management: Track account keys, and rule configurations for subsequent operations.
• Error Handling: Implement comprehensive error handling for rule validation and authorization decision processing.
• Notification Integration: Configure notification systems for payment control alerts and authorization decisions.
• Reporting Integration: Implement regular transaction and notification history analysis for rule optimization.
• AI-Assisted Enhancement: Leverage Intelligent Payment Controls for data-driven rule suggestions.

Integration is successful when these outcomes are achieved:

• Account Registration: Successful registration of existing card accounts in the payment controls system
• Rule Application: Payment control rules are successfully configured and applied to authorization processing
• Real-world Authorization Control: Rules effectively influence authorization decisions for actual transactions
• Notification System: Proper delivery of payment control authorization notifications
• Business Outcome Achievement: Protection of commercial payments and effective spending limitation according to business use cases

Avoid these common challenges based on system design:

• Workflow Sequence Violations: Attempting to set non-Block rules before account registration
• Sandbox Over-Reliance: Depending solely on sandbox API explorer behavior instead of API specifications
• VisaNet Processing Assumptions: Not accounting for On-Us transaction scenarios requiring VTEX integration
• Payload Size Overruns: Exceeding 30720 bytes limit when configuring complex rule sets
• Full Refresh Misunderstanding: Not sending complete rule sets when using Set Rules API
• Authentication Setup Issues: Improper Two-Way SSL or message-level encryption configuration
• Expecting Individual Rule Deletion: The Delete Rules operation removes ALL rules for an account — individual rule removal is not available. Use Block Account as an alternative when all transaction processing must be stopped.

Additional struggle and integration mistake patterns will be documented as more client feedback becomes available.

Learn the primary workflows for implementing dynamic payment controls on B2B card portfolios through account registration and rule management.

Visa Commercial Payment Controls supports two primary categories of workflows: onboarding workflows for establishing card controls and ongoing management workflows for dynamic rule adjustments. The typical client journey begins with adding card account, progresses through initial rule configuration, and continues with ongoing rule management and transaction monitoring.

The complete workflow enables clients to protect commercial payments and limit spending at the card level through dynamic, near real-time rules that align authorization decisions with business use cases.

The onboarding workflow establishes the foundation for payment control operations:

1. Account Setup: Register existing card accounts. This step is required before setting any rules other than the Block Rule.

2. Initial Rule Configuration: Configure initial payment control rules per business use case. Use Set Rules API which performs a full refresh requiring all rules to be applied in a single request.

3. Validation and Testing Verify account setup and rule implementation using GET operations to confirm configuration.

The ongoing management workflow handles dynamic rule adjustments and monitoring:

1. Account Information Management Manage card account information including updates to account details and contact information.

To permanently remove an account and all associated rules and notifications:

2. Dynamic Rule Management Manage payment controls in near real-time including spending rules, merchant category rules, location, channel, and business hours restrictions.

3. Transaction Monitoring: Use GET functionality to pull card/account details, retrieve existing rules and spend usage, and view decline/authorization data.

4. AI-Assisted Rule Generation: Use Intelligent Payment Controls to generate AI-suggested rules. Submit a usage description to Get Suggested Rules, which evaluates the prompt and returns recommended controls along with a Rule Set ID. Pass the Rule Set ID — with any optional modifications — to Set Suggested Rules to apply the controls. The card account must exist before using these APIs.

Implement different types of payment control rules based on business requirements:

• Spending Rules: Set transaction amount limits and spending velocity controls to prevent excessive spending. Configure daily, weekly, or monthly spending limits per card account.

  Use Cases: Employee expense limits, vendor payment controls, departmental budget enforcement.

  Currency specification is required for spending rules. All spending rules for a given account must use the same currency. See Supported Currencies for valid currency codes.

• Merchant Category Rules: Control which merchant categories are allowed or blocked for specific card accounts. Use MCC (Merchant Category Code) based restrictions.

  Use Cases: Restricting entertainment expenses, limiting fuel purchases, controlling office supply vendors.

• Location-Based Rules: Implement geographic restrictions based on country, region, or specific location parameters.

  Use Cases: Domestic-only transactions, regional business restrictions, travel-specific controls.

• Channel and Time-Based Rules: Configure channel restrictions (online, in-store, ATM) and business hours limitations for transaction approval.

  Use Cases: Business hours enforcement, channel-specific restrictions, contactless payment controls.

  GMT is used by default; a timezone override is available. See Supported Time Zones for valid timezone values.

Follow these patterns for effective rule management:

• Full Refresh Pattern: The Set Rules API requires sending all rules to be applied in a single request, performing a full refresh of existing rules
• Rule Activation: Rules are active immediately upon setting and apply to subsequent authorization requests
• Payload Limitations: Each account can have multiple rules as long as the payload doesn't exceed 30720 bytes maximum size
• Block Rule Exception: Block rules can be set during account registration, while all other rules require account registration first
• Notification Integration: Configure notifications to monitor authorization decisions

Implement comprehensive monitoring using reporting operations:

• Transaction History Analysis: Use transaction history reporting after authorizations/declines occur to evaluate rule effectiveness. Notification configuration is not required to use Get Transaction History.
• Notification History Tracking: Monitor notification delivery to ensure stakeholders receive timely alerts. Get Notification History requires prior notification configuration — contacts must be specified during account creation.
• Spend Usage Monitoring: Use Get Rules to retrieve all active controls with consumed spending amounts and authorization counts for specific rule types. Track spending patterns and rule triggers to optimize control configurations.
• Decline Analysis: Analyze authorization decline patterns to identify potential business impact
• Pagination Handling: Use pageNumber parameter and isLastDataSet field for comprehensive data retrieval

Validate successful integration through these key indicators:

• Account Registration Success: Successfully register existing card accounts in the system
• Rule Configuration Success: Successfully set and retrieve payment control rules with immediate activation
• Real-world Authorization Control: Verify that rules are applied correctly during actual transaction authorization processes
• Notification Delivery: Confirm notification system delivers alerts for rule-based authorization decisions
• Reporting Functionality: Successfully retrieve transaction history and notification history

The ultimate success indicator is when payment control rules effectively protect commercial payments and limit spending according to business use cases, with proper monitoring and reporting capabilities in place.

Enhanced security authentication using Two-Way SSL with Message Level Encryption for sensitive account information in Payment Controls operations.

Visa Commercial Payment Controls requires enhanced authentication due to the sensitive nature of account information being sent. The solution implements Two-Way SSL (mutual authentication) combined with Message Level Encryption to provide maximum security for commercial card account data during payment control operations.

This enhanced authentication approach goes beyond standard VDP authentication patterns to ensure that sensitive commercial card portfolio information remains protected throughout all API interactions.

Obtain the required credentials through the standard VDP eligibility process with additional Payment Controls requirements:

1. Issuer Authorization: Confirm participation is done on behalf of an issuer and their portfolio
2. Third-Party Agent Setup: If not the issuer directly, obtain issuer authorization for your entity to act as an agent
3. Visa Representative Coordination: Work with Visa Representative during implementation to discuss contracting requirements
4. VDP Account Setup: Obtain credentials and certificates for both SSL and message-level encryption from your Visa Developer Portal account
5. Production Authorization: Ensure issuer authorization is completed before moving to production

Configure your system for Two-Way SSL with Message Level Encryption authentication:

Configure your HTTP client for Two-Way SSL (mutual authentication) using the SSL certificate provided in your Visa Developer Portal account. Ensure proper certificate chain validation and mutual authentication setup.

Implement Message Level Encryption for request payloads containing account information. Use the MLE certificate provided in your Visa Developer Portal account for payload encryption.

Identify which API operations require MLE encryption based on sensitive account data presence:

Maintain both SSL and MLE certificates with proper renewal procedures to prevent authentication disruptions.

1. Two-Way SSL Configuration

   Configure your HTTP client for Two-Way SSL (mutual authentication) using the SSL certificate provided in your Visa Developer Portal account. Ensure proper certificate chain validation and mutual authentication setup.

2. Message Level Encryption Setup

   Implement Message Level Encryption for request payloads containing account information. Use the MLE certificate provided in your Visa Developer Portal account for payload encryption.

3. Account Information Identification

   Identify which API operations require MLE encryption based on sensitive account data presence:

   • Account Management operations (create, update, get)
   • Rules Management operations with account references
   • Contact Management operations with account associations
   • Report Management operations returning account details
4. Certificate Management

   Maintain both SSL and MLE certificates with proper renewal procedures to prevent authentication disruptions.

Construct proper HTTP headers for authenticated Payment Controls requests:

Header Details:

• Authorization: Standard Basic authentication using VDP credentials
• Content-Type: Always application/json for Payment Controls APIs
• Accept: Always application/json for Payment Controls APIs

Implement MLE encryption for APIs containing sensitive account information:

Sensitive Data Identification: Apply MLE encryption to requests containing:

Encrypt the complete request payload using your MLE certificate and include the encrypted payload in the x-pay-token header while maintaining proper JSON structure for non-sensitive metadata fields.

Implement proper decryption for encrypted response payloads containing sensitive account information returned by the APIs.

1. Sensitive Data Identification: Apply MLE encryption to requests containing:

   • Account numbers and account identifiers
   • Service keys and account references
   • Card portfolio information
   • Commercial card account details
2. Encryption Process

   Encrypt the complete request payload using your MLE certificate and include the encrypted payload in the x-pay-token header while maintaining proper JSON structure for non-sensitive metadata fields.

3. Response Processing

   Implement proper decryption for encrypted response payloads containing sensitive account information returned by the APIs.

Validate your authentication setup using these testing approaches:

• Two-Way SSL Validation: Test mutual authentication using a simple account management API call
• MLE Encryption Test: Verify MLE encryption/decryption using an account creation operation in sandbox
• Header Verification: Confirm all required headers are properly constructed and accepted
• Certificate Validation: Test both SSL and MLE certificate functionality before production deployment

Sandbox Testing Considerations:

Remember that the sandbox environment provides only static values and a limited subset of possible requests. Code using API specifications rather than mimicking sandbox API explorer behavior, as you cannot execute all API functionality or see the full list of accurate error codes through the sandbox explorer.

Authentication configuration considerations across environments:

• Sandbox Environment: Use sandbox-specific certificates for both SSL and MLE. Limited functionality testing available due to static values and restricted request subset.
• Production Environment: Use production certificates with live MLE encryption keys. Account ranges must be pre-configured during VPC implementation. Requires completed issuer authorization and contracting.

Environment-Specific Considerations:

• Certificate management varies between sandbox and production environments
• MLE encryption keys are environment-specific and cannot be interchanged
• Account range pre-configuration required for certification and production but not sandbox
• No regional variations in authentication requirements identified

Follow these security best practices for Payment Controls authentication:

• Certificate Security: Protect both SSL and MLE certificates with appropriate access controls and secure storage
• Key Rotation: Implement proper certificate renewal procedures to prevent authentication disruptions
• Payload Encryption: Always encrypt payloads containing account numbers, service keys, or other sensitive commercial card data
• Environment Separation: Maintain strict separation between sandbox and production certificates and credentials
• Access Controls: Implement proper access controls for certificate management and API credential storage

Common authentication issues and resolutions:

• SSL Handshake Failures: Verify Two-Way SSL certificate installation and mutual authentication configuration
• MLE Encryption Errors: Confirm MLE certificate validity and proper payload encryption implementation
• 401 Unauthorized: Check Basic authentication credentials, header construction, and certificate validity
• Certificate Validation Errors: Ensure proper certificate chain validation and environment-appropriate certificates
• Payload Decryption Issues: Verify MLE decryption implementation for response processing

Product-specific error codes and troubleshooting guidance for Payment Controls, Rules Management, and related commercial card portfolio operations.

Visa Commercial Payment Controls provides extensive product-specific error codes beyond standard VDP errors. These custom error codes support Payment Controls operations including account management, rules configuration, and reporting functionality, with specific error handling for commercial card scenarios.

Error responses include detailed information for troubleshooting payment control rule issues, account registration problems, and system processing challenges specific to commercial card management workflows.

In addition to the product-specific error codes documented below, Payment Controls 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.

Payment Controls APIs return structured error responses with consistent formatting:

Response Fields:

• errorCode: Specific product error code for programmatic handling
• errorMessage: Human-readable error description
• details: Context-specific information for troubleshooting including account references
• suggestedAction: Recommended resolution steps

Possible success response codes returned from Visa Commercial Payment Controls requests.

Implement these error handling strategies for robust Payment Controls integration:

• Workflow Sequence Validation: Account > Rules sequence before API calls
• Payload Size Monitoring: Monitor rule payload size to prevent errors
• Retry Logic: Implement exponential backoff for transient system errors
• Comprehensive Logging: Log error codes, request IDs, and sequence numbers for troubleshooting support
• API Specification Authority: Code against API specifications rather than sandbox explorer behavior

Error codes specific to commercial card account registration and management.

Error codes specific to payment control rules configuration and management.