# Visa Commercial Fraud Solutions

## Visa Commercial Supplier Validation

### Product Overview

Visa Commercial Supplier Validation enables issuers to restrict commercial card usage to specific, validated suppliers through a robust database that maps buyers' intended suppliers to Visa's network data. This targeted approach helps issuers make informed authorization decisions and reduces fraud risk, particularly in automated payment environments where manual authentication is not feasible. The service is particularly valuable for organizations seeking to enhance B2B payment security, minimize fraud risk, and ensure compliance with payment authorization best practices.

This service targets issuers and fintechs managing B2B payments, with particular value in B2B travel scenarios where precise supplier-level controls are essential for fraud prevention and authorization accuracy.

### Supplier Validation API List

Use the Supplier Validation Service to build and maintain a repository of trusted suppliers for virtual commercial card payments. Clients can register new trusted suppliers, update existing supplier attributes, and retrieve validated supplier information, including Acquirer BIN and Card Acceptor ID (CAID). The validated supplier data can then be used to establish or update payment controls through B2B Payment Controls APIs or B2B Payables APIs, ensuring that virtual card payments are authorized exclusively for verified, trusted suppliers.

- Register Supplier
- Update Supplier
- Retrieve Supplier

### Supplier Validation Getting Started

This page provides information needed to begin integrating with Visa Commercial Supplier Validation. 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](https://developer.visa.com/pages/working-with-visa-apis/visa-developer-quick-start-guide#section2) 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

**Additional Requirements:** Ensure you have access to historical authorization transaction data containing supplier information, as this data will be used in API requests for supplier validation.

#### Environment Hosts & URL Recipe

Visa Commercial Supplier Validation APIs are available at the following base URL:

```json

```

Example endpoint for supplier registration:

```json

```

#### Headers and Authentication

Visa Commercial Supplier Validation requires Two-Way SSL (Mutual Authentication) for secure connections. Additionally, each request must include custom headers:

- **ClientId**: Unique identification of the financial institution (provided by Visa during onboarding)
- **CorrelationId**: Header used to trace API calls from VDP to backend systems

For detailed authentication setup, see the Authentication Methods section of this documentation.

#### First API Call

Test your integration by registering a supplier. The Register Supplier API is the logical starting point for supplier validation workflows:

```json

```

**Expected Response Codes:**

- **200 OK**: Successful operation - supplier registered and trust information returned
- **400 Bad Request**: Validation errors in request data
- **401 Unauthorized**: Authentication errors
- **500 Internal Server Error**: Unexpected server error

A successful response indicates your integration is properly configured and you can proceed with supplier management operations.

### Supplier Validation Things to Know

Understanding the underlying business logic and system constraints for successful supplier validation integration.

#### Introduction

Successful integration with Visa Commercial Supplier Validation requires understanding the underlying business logic that drives fraud prevention through supplier-specific authorization controls. Understanding these foundational concepts ensures your integration aligns with Visa's network data validation processes.

#### Resource Hierarchy and Dependencies

| Resource | Role | Dependency |
| --- | --- | --- |
| Supplier Registration | Creates validated supplier information | Requires valid Acquirer BIN and Card Acceptor ID (CAID) belonging to the supplier |
| Supplier Retrieval | Provides validity status of the supplier information | Depends on prior supplier registration and Visa Network data |
| Supplier Updates | Modifies supplier validation status | Requires existing validated supplier |
| Authorization Controls | Enforces supplier restrictions | Depends on validated supplier data |

#### Core Business Rules

- **Historical Data Requirement:** You must have supplier information from historical authorization transactions to use in API requests for validation.
- **Authorization Decision Capability:** Your system must be capable of using validated supplier information to make authorization decisions during transaction processing.
- **Unique Supplier Mapping:** Each supplier can have multiple Acquirer BIN and CAID combinations, but each combination represents a specific trust relationship.
- **Validated Status Management:** Supplier validity can be established or removed at the supplier level.

#### Guardrails and Limitations

**Data Requirements:**

- Request ID cannot exceed 50 characters
- Issuer ID must be 8 digits
- Buyer ID cannot exceed 25 characters
- Buyer Supplier ID cannot exceed 30 characters
- Acquirer BIN must be 6-8 digits
- CAID (Card Acceptor ID) must be 1-15 alphanumeric characters

**System Constraints:**

- Usage limits and throttling expectations are not publicly disclosed and are managed at the platform level
- API responses are synchronous with standard REST patterns

**Authentication Requirements:**

Two-Way SSL (Mutual Authentication) required for all connections

**Environment Considerations:**

- All integrations must go through VDC portal across three environments: **Sandbox** > **Certification** > **Production** > .
- VDP product team approval required for environment promotions.
- PCI protocol and certification requirements apply to this service.

### How to Use Supplier Validation

Comprehensive workflows for managing supplier validation from registration to authorization control implementation.

#### Workflow Overview

Visa Commercial Supplier Validation supports two primary business workflows that work together to provide comprehensive fraud prevention. The supplier repository workflow establishes validated supplier relationships, while the authorization control workflow enforces payment restrictions based on validated supplier data.

All three APIs (Register, Update, and Retrieve) are required to properly maintain supplier validation information and implement effective fraud prevention controls.

#### Supplier Repository Workflow

Follow these steps to establish and maintain your supplier repository:

1. **Retrieve Supplier Data:** Extract Acquirer BIN, Card Acceptor ID, Buyer ID, and Supplier ID from your system's historical transaction data.
2. **Submit to Visa:** Use the Register Supplier API (/suppliervalidation/register) to submit supplier data to Visa for validation and enrichment.
3. **Receive Enriched Data Confirmation:** Visa enriches your supplier details with matched VisaNet information and returns confirmation.
4. **Maintain Supplier Information:** Use the Update Supplier API (/suppliervalidation/update) to modify validated status and the Retrieve Supplier API (/suppliervalidation/retrieve) to validate existing supplier information.

#### Authorization Control Workflow

Implement supplier-based authorization controls using validated supplier data:

1. **Issue Virtual Card:** Issue a Visa Commercial Virtual Card to the buyer for supplier-specific transactions.
2. **Establish Controls:** Configure optional Visa Commercial Payment Controls by integrating to Visa Commercial Payment Controls APIs or Visa B2B Virtual Account Payment Method and using the validated supplier information to restrict usage to approved suppliers.
3. **Supplier Transaction:** The buyer provides virtual card information to the supplier for payment processing.
4. **Payment Request Processing:** When the supplier submits a payment request, the system receives authorization details including Acquirer BIN and Card Acceptor ID.
5. **Validation Check:** Verify the transaction's Acquirer BIN and Card Acceptor ID validity using Retrieve API.
6. **Authorization Decision:** Authorize the transaction only upon successful verification of supplier validation data. If optional Visa Commercial Payment Controls is configured, Visa will automatically validate and make authorization decisions.

Authorization control depends on having up-to-date validated supplier information.

#### Common Supplier Management Tasks

**Register New Supplier:**

Use `/suppliervalidation/register` to create new validated supplier relationships. This endpoint validates supplier information against Visa's network data and establishes validated relationships with associated Acquirer BIN and CAID combinations.

**Retrieve Supplier Information:**

Use `/suppliervalidation/retrieve` to get validated status of the Acquirer BIN/CAID mappings.

**Update Supplier Trust:**

Use `/suppliervalidation/update` to modify supplier validated status.

#### Integration Best Practices

- **Verify Complete Setup:** Confirm you can setup and maintain supplier information using all three APIs before proceeding to production.
- **Leverage Historical Data:** Use your existing authorization transaction history to identify suppliers for initial registration and validation.
- **Validate Data Enrichment:** Ensure you can successfully retrieve and use the validated status and associated IDs returned by Visa.
- **Implement Error Handling:** Design robust error handling for validation failures and authentication errors, particularly for the extensive VSERR-* error code family.
- **Authorization Integration:** Verify your system can effectively use validated supplier information to make real-time authorization decisions.

### Supplier Validation Authentication Methods

Visa Commercial Supplier Validation requires Two-Way SSL mutual authentication and custom headers for secure API connections.

#### Authentication Overview

Visa Commercial Supplier Validation uses Two-Way SSL (Mutual Authentication) as the primary security protocol for securing connections between your system and Visa's APIs. This approach ensures both the client and server authenticate each other, providing enhanced security for supplier validation operations.

In addition to Two-Way SSL, each API request must include custom headers for client identification and request tracing.

#### Credential Acquisition

Obtain your authentication credentials through the Visa Developer Center:

1. Create a Visa Developer Account and project
2. Request Two-Way SSL certificates for mutual authentication
3. Receive credentials and certificates for SSL usage within your Visa Developer Account
4. Sign the Participation Agreement for production eligibility
5. Submit promotion requests to higher-level environments through the Visa Developer Center

#### Two-Way SSL Setup

Configure Two-Way SSL mutual authentication for secure connections:

1. Install the client certificate provided by Visa in your application
2. Configure your HTTP client to present the certificate during TLS handshake
3. Verify the server certificate matches Visa's expected certificate chain
4. Ensure your application validates the mutual authentication process

For detailed Two-Way SSL implementation guidance, visit the [Two-way SSL Guide](https://developer.visa.com/pages/working-with-visa-apis/two-way-ssl).

#### Required HTTP Headers

Include the following mandatory headers in every API request:

**RequestId Header:**

- **Purpose:** Trace API calls from VDP to backend systems
- **Format:** 1-50 characters, alphanumeric with underscores and hyphens
- **Requirement:** Generate unique request ID for each request
- **Example:** `RequestId: REQ-12345-67890-ABCDE`

#### Testing Authentication Setup

Verify your authentication configuration using a simple API call:

```json

```

A successful response indicates your Two-Way SSL setup and headers are correctly configured.

#### Environment Authentication Differences

**Development Environment (Sandbox):**

- Use sandbox certificates provided in your VDC account
- Base URL: `https://sandbox.api.visa.com`

**Certification Environment:**

- Requires VDP and VPC product team approval for access
- Use certification-specific certificates
- Complete detailed test plan provided by Visa

**Production Environment:**

- Requires signed Participation Agreement
- Use production certificates with enhanced security protocols
- PCI protocol and certification requirements apply

### Supplier Validation Error Codes

Product-specific error codes and troubleshooting guidance for Visa Commercial Supplier Validation APIs.

#### Error Code Overview

Visa Commercial Supplier Validation APIs return product-specific error codes with the prefix VSERR- in addition to standard HTTP status codes. These error codes provide detailed information about validation failures, authentication issues, and business logic errors.

For general Visa Developer Platform error codes, refer to the standard VDP error documentation. This section covers supplier validation-specific error codes only.

#### Supplier Validation Errors

| Error Code ID | Error Code Description |
| --- | --- |
| VSERR-0001 | Invalid request |
| VSERR-1002 | Message Id cannot be blank |
| VSERR-1003 | Message Id cannot exceed 36 characters |
| VSERR-1004 | Issuer Id cannot be blank |
| VSERR-1005 | Issuer Id cannot exceed 8 characters |
| VSERR-1006 | Buyer Id cannot be blank |
| VSERR-1007 | Buyer Id cannot exceed 25 characters |
| VSERR-1008 | Buyer Supplier Id cannot be blank |
| VSERR-1009 | Buyer Supplier Id cannot exceed 30 characters |
| VSERR-1019 | Acquirer BIN cannot be blank |
| VSERR-1020 | CAID cannot be blank |
| VSERR-1021 | Contact information cannot be blank |
| VSERR-1022 | Need to have valid BIN,CAIDS for update |
| VSERR-1023 | Cannot find the Supplier |
| VSERR-1024 | Supplier is untrusted. Please use register API to trust the supplier |
| VSERR-1025 | Please use register API to trust acquirer BIN & CAID |
| VSERR-2001 | Client ID is missing in the request header |
| VSERR-2002 | Invalid Client ID provided |
| VSERR-2003 | Client not found |
| VSERR-2004 | Client is not authorized to access this resource |
| VSERR-9999 | An unexpected error occurred |
| CD1000 | Success |
| CDI001 | Internal service failure |
| CDI071 | Request Data Invalid |
| CDI092 | No matching records found |

#### Error Response Format

Error responses follow a consistent JSON structure:

```json

```

**Response Fields:**

- **errorCode:** Product-specific error identifier (VSERR-xxxx)
- **requestId:** Original message ID from your request
- **statusCode:** HTTP status code
- **errorMessage:** Detailed error description
- **statusDescription:** HTTP status description

#### Common Troubleshooting Scenarios

**Supplier Registration Failures:**

- Verify all required fields (requestId, issuerId, buyerId, buyerSupplierId, acquirerBin, caid) are provided
- Ensure field length constraints are met

**Authentication Issues:**

- Verify Two-Way SSL certificate installation and configuration
- Confirm production eligibility requirements are met

**Validated Status Problems:**

- Register suppliers before attempting updates or retrievals
- Verify BIN and CAID combinations are valid
- Use retrieve API to check current validated status before modifications

#### Error Handling Best Practices

- **Implement Retry Logic:** For temporary failures (5xx errors), implement exponential backoff retry patterns
- **Log Request IDs:** Always log RequestId values for troubleshooting and support requests
- **Validate Before Submit:** Pre-validate request data against field constraints to avoid validation errors
- **Handle Trust Status:** Design workflows to handle supplier validated status changes and registration requirements
- **Monitor Error Patterns:** Track error code patterns to identify systemic integration issues