Getting Started

Visa Intelligent Commerce (VIC) enables Agent Providers, Wallet Providers, and Agent Enablers to securely conduct commerce on behalf of consumers using Visa credentials. The platform provides network-level controls, consumer-approved purchase instructions, agent validation, and tokenized payment credentials so that AI-powered commerce experiences can operate with transparency, trust, and accountability. The primary audience includes AI Agent Providers, Wallet Providers, Agent Enablers, and commerce platforms connecting directly to VIC.

Standard Visa Developer setup (use for all products):

Before you begin integration, complete the standard Visa Developer setup:

• Create a Visa Developer account
• Set up your development environment
• Review the Visa Developer Quick Start Guide

Product-specific requirements:

Production access requires onboarding to Visa Intelligent Commerce and completion of applicable Visa onboarding processes. You must become an approved participant within the VIC ecosystem and also need to onboard to the Trusted Agent Protocol (TAP), Visa Token Service (VTS), Visa Payment Passkeys (VPP), related certification programs, and compliance and security requirements. You must also complete registration through the Visa Agent Registry Service (VARS) so that Visa can validate your agent signatures and merchant encryption keys at the time of credential retrieval.

Card eligibility is limited to tokenizable, Cloud Token Framework (CTF)-enrolled credit, debit, and prepaid cards. Confirm the consumer's card meets these criteria before initiating enrollment.

You need, before your first call:

• A Visa-provisioned externalClientId (Token Requestor ID, TRID) and externalAppId (External Application Profile Identifier), obtained through VTS
• A Business Identifier (BID), obtained from your regional product team alongside your TRID. If you're a new Visa client, you'll need a new BID; if you already hold one, it can be reused when obtaining a new Token Requestor ID
• A consumer's tokenId, the identifier of a previously provisioned token (vProvisionedTokenID)
• Visa Payment Passkeys set up with device binding for the consumer
• An asymmetric public key onboarded with Visa, used to encrypt the encryptedInstruction payload (JSON Web Encryption (JWE), up to 512,000 bytes)
• Mutual Transport Layer Security (TLS) (two-way SSL) client certificate configuration

Visa maintains a public AI skills repository at https://github.com/visa/ai that provides pre-built context and guidance for AI agents implementing Visa APIs. Installing these skills gives Claude Code-compatible agents awareness of VIC workflows, authentication patterns, and common integration pitfalls, without requiring the agent to be manually prompted each session.

The visa-best-practices skill

The repository includes the visa-best-practices skill, which is the primary integration aid for VIC. The skill automatically activates when an agent is working on:

• Card enrollment, purchase instructions, or payment credentials
• Authentication setup (mutual TLS / two-way SSL)
• Message-Level Encryption (MLE/JWE)
• Credential and environment configuration (Sandbox → Certification → Production)
• Machine Payments Protocol (MPP) / HTTP 402 payment flows

When active, the skill loads concise reference material covering VIC's integrated services (Tokenization, Authentication, Purchase Instructions, Signals), authentication gotchas, and links to official documentation and live code examples via https://sandbox.mcp.visa.com/mcp/doc/llms.txt

Installation

Prerequisites

Claude Code CLI (npm install -g @anthropic-ai/claude-code) or any MCP-compatible agent at runtime.

Project-level install (applies to one integration project):

Or manually:

Global install (applies across all projects on the machine):

How the skill activates

Skills follow a describe-then-load pattern. The skill's SKILL.md contains a natural-language description; the agent runtime reads this at startup and loads the full skill content when the user's task matches the description. For VIC work, any mention of card enrollment, purchase instructions, VTS, or Visa authentication is sufficient to trigger loading.

No additional configuration is required (the skill is self-contained and references live documentation rather than embedding static API specs).

Core VIC workflows covered

Once installed, an agent working on a VIC integration has built-in awareness of these workflows (with code examples fetched dynamically from llms.txt):

Integration approaches

The skill guides agents toward the appropriate integration model based on architecture:

• MCP-Based, streamable HTTP transport for agent systems using the Model Context Protocol (sandbox.mcp.visa.com)
• Direct API, REST calls with MLE encryption for traditional backends
• VDC Hello World, initial connectivity verification before beginning full VIC integration

An Agent Enabler can onboard an Agent Provider into VTS by calling the Onboarding API. To onboard a token requestor, the token service provider must call the Onboarding API and provide the required information to uniquely identify the token requestor.

The token service provider uses the Onboarding API to register a token requestor, configure tokenization settings, and establish relationships with Acquirers and token service providers. This is the foundational step before any PAN enrollment or token provisioning.

Instances in which the client may need to use the Onboarding API include:

• Initial registration as a token requestor
• Setting up tokenization profiles and channel security context
• Establishing relationships with Acquirers and token service providers
• Configuring notification endpoints for token status and payment events

Endpoint

• POST /vts/merchant-api-ic/onboarding (Sandbox)
• POST /vts/merchant-api/onboarding (Live)

Request includes

• Company details (legal name, website, city, country code, contact email)
• Business identification (country-specific VAT/ID)
• Tokenization configuration (profileName, applicationId, postbackURL, device binding enforcement)
• Channel security context (such as SHARED_SECRET, deviceCerts, vtsCerts)
• Relationships (externalClientId, acquirerId, acquirerMerchantId) and token requestor settings

Required fields

• serviceContext, indicates the onboarding purpose (such as TOKENIZATION).
• companyPrimaryLegalName, legal name of the token requestor.
• primaryWebsiteURL, publicly accessible website of the token requestor.
• companyCity, the city of the principal place of business.
• companyCountryCode, ISO-3166-1 alpha-2 country code.
• primaryContactEmail, email address for official communications.
• tokenizationConfiguration, object defining one or more tokenization profiles, including:
  • profileName, unique name for the tokenization profile.
  • applicationId, application identifier that Visa issues.
  • channelSecurityContext, security model used for the channel (such as SHARED_SECRET).

One of these identification methods is required:

• businessIdentificationType and businessIdentificationValue (such as VAT, EIN), or
• acquirerIdentifiers (acquirerId and acquirerMerchantId), identifying the acquiring relationship.
• trSettings, token requestor configuration options such as lifecycle update participation and the required setting of tokenRequestorType to AI_AGENT, and eComClientSetting to Ecom_Enabler.

Optional fields

• companyPrimaryTradeName, DBA or trade name if different from legal name.
• companyAddress details (street, state/province, postal code, phone).
• dunsNumber, Dun & Bradstreet identifier.
• primaryContactFirstName / primaryContactLastName, named business contact.
• tokenRequestorServiceTypes, supported services (such as Purchase).
• relationships, relationship to the token requestor being onboarded (by externalClientId).

Persist from response

• Relationship IDs for future API calls
• Tokenization configuration details (profileName, channelSecurityContext, device binding enforcement)
• Notification endpoint URLs for event handling
• Acquirer identifiers for transaction processing

1. The token service provider collects the required legal, business, and technical information for the token requestor.
2. The token service provider submits an onboarding request to VTS with organization details, identification credentials, tokenization profile, and relationship configuration.
3. VTS validates the request and registers the token requestor, applying the specified tokenization and security settings.
4. VTS returns onboarding and relationship identifiers, which the client must persist.
5. The token requestor uses the onboarding identifiers to perform subsequent VTS operations, including PAN enrollment, token provisioning, and lifecycle management.

Expected outcome

Upon successful completion of the onboarding process:

• The token requestor is registered and authorized within Visa Token Service.
• Tokenization profiles and channel security context are established.
• Acquirer and token service provider relationships are configured for transaction processing.
• Notification endpoints are activated for token and payment event handling.
• The token requestor is now eligible to invoke downstream VTS APIs to enroll PANs, provision tokens, and manage token lifecycle events in a secure and compliant manner.

Visa Intelligent Commerce uses a three-environment progression: Sandbox, then Certification, then Production. Each environment requires Visa approval before you advance to the next.

Example production request:

Two integration models are available based on your business model and who holds the Token Requestor ID (TRID). Choose the one that matches how you operate:

Independent of which integration model you choose, every client advances through the same environment progression (sandbox, then certification, then production) only after Visa approval at each stage.

Before you can call the VIC platform, the consumer's card must be enrolled and provisioned. This enrollment sequence happens once per card, ahead of any purchase-instruction or credential-retrieval call.

Journey steps

1. The consumer adds a Visa card for agentic commerce use through your agent application or partner interface, and provides card details per your implementation.
2. You (the agent or enabler) initiate agentic token provisioning through the Visa Token Service (VTS).
3. Visa returns a provisioned agentic token to you. You do not store the raw Primary Account Number (PAN) for future use (only the provisioned token).
4. You initiate issuer identification and verification (ID&V) or step-up authentication where required, and present the available step-up options to the consumer.
5. The consumer selects a step-up option and completes authentication.
6. If applicable, you initiate Visa Payment Passkey (VPP) setup and complete device binding for the consumer's device.
7. The consumer receives confirmation that the credential is enabled for agentic commerce with your agent.

If Passkey setup (step 6) fails, you cannot proceed to create a purchase instruction for that consumer unless your use case has been specifically approved to operate without it. Do not treat a failed Passkey enrollment as a step to retry silently, but surface the failure and re-route the consumer through step-up authentication.

Exit criteria

A vProvisionedTokenID and a device-bound Visa Payment Passkey for the consumer. Only after this completes can you call POST /vacp/v2/credentials-for-instruction.

1. Run the full sequence once per test consumer/card combination, in sandbox, before attempting any purchase-instruction or credential-retrieval call.
2. Confirm you receive a vProvisionedTokenID from Visa Token Service.
3. Confirm Visa Payment Passkey device binding completes, or that your use case has been approved to skip it.

• vProvisionedTokenID (required as tokenId on every later credential-retrieval call for this card)
• Device-bound Visa Payment Passkey state for the consumer (required for authentication on later calls)

When prompting a consumer to add a Payment Credential to their previously created account, the agent must provide some mechanism to collect Payment Credential details. Clients can use the PAN Enrollment API to register a Primary Account Number (PAN) for token provisioning in Visa Intelligent Commerce (VIC).

The PAN Enrollment API replaces sensitive card details with a secure reference that can be used to provision payment tokens. This process ensures that cardholder data is never exposed during transactions. The client can refer to the Visa Digital Solutions API Reference Guide for more information.

Instances in which the client may use the PAN Enrollment API include during consumer onboarding, after verifying the cardholder's identity, or when adding a new Visa Payment Credential to VIC for tokenized transactions.

Endpoint: POST /vts/panEnrollments

Required fields

• encryptedPaymentInstrument.accountNumber (PAN)
• panSource (capture method)
• Billing address and CVV2 (required in VIC specs, to confirm; for VTS, CVV2 is not required for e-commerce COF tokens, but the agent TR must still capture CVV2 for this flow)

Persist from response

• vPanEnrollmentID, for token provisioning
• Information necessary to present card details to the consumer

The client can then use the VTS Provision Token API to request to provision a token using the PAN and other Payment Credential information stored in the PAN Enrollment API. The client can refer to the Visa Digital Solutions API Reference Guide for more information.

Instances in which the client may need to use the Provision Token API include immediately after enrolling a PAN using the Enroll PAN API, or when adding a new tokenized credential to a consumer's VIC account for future transactions.

Endpoint: POST /vts/panEnrollments/{vPanEnrollmentID}/provisionedTokens

Request includes

• vPanEnrollmentID from the PAN Enrollment API
• Authentication context, if the issuer requires it

Persist from response

• vProvisionedTokenID, for VIC card enrollment and credential retrieval. The client does not need to store the 16-digit token.

VIC uses Visa Payment Passkey APIs to enable AI agents to verify device and cardholder identities and to facilitate consumer consent to a purchase instruction.

The APIs provide endpoints for securely registering consumer devices, validating their authenticity, and performing user authentication during the commerce workflow. These APIs support both attestation (confirming that a device is trusted) and assertion (verifying that the user is authorized to act on a transaction). The client follows the device binding and step-up authentication steps as needed.

Core authentication capability

• Attestation options and results: generate a device registration challenge and submit the attestation response to confirm device trustworthiness.

Key endpoints

• POST /attestation/options, request the parameters needed to perform device attestation.
• POST /attestation/result, submit the device attestation result for verification.
• POST /deviceBinding, perform device binding if Passkey registration is required.

By using these APIs, AI agents ensure that only trusted devices and authenticated consumers can authorize transactions within VIC, supporting secure, passkey-based commerce experiences.

See the VPP Client Implementation Guide (set up passkey-based verification) and the Visa Token Service Implementation Guide (tokenize credential, complete device binding, and manage step-up flows) for more information.

Requirements

• Consumer account and card enrollment are complete, and the token is provisioned (vProvisionedTokenID is the stored provisioned token identifier provided in the response to the Provision Token API).
• The VTS Fast IDentity Online (FIDO) SDK is integrated in your web or mobile application environment.
• Mutual TLS (mTLS) authentication is configured for VIC APIs.
• Initialize the VTS FIDO SDK as early as possible on any page that runs Passkey flows, to reduce UI latency during registration or authentication.
• Prior to presenting Passkey setup to the consumer, the AI agent must determine whether the VTS FIDO SDK can be presented within an iFrame, or whether a popup is required, then use the VTS FIDO SDK to register the Passkey.
• Use correlation and idempotency headers on server calls that follow the SDK flow to de-risk retries.

The client must check for an existing Passkey tied to the consumer's device they are interacting with the agent on, using the Get Device Attestation Options API.

Endpoint: POST /vts/provisionedTokens/{vProvisionedTokenID}/attestation/options

Request includes

• clientReferenceId, a unique identifier for each device
• type = AUTHENTICATE
• reasonCode = PAYMENT

Interpret response

• If action = AUTHENTICATE, a Passkey exists; device binding step-up and Passkey setup can be skipped, and the flow proceeds to authentication when required.
• If action = REGISTER, no Passkey is present, so continue with device binding and registration.

Use the Attestation Options API to request the parameters needed for device attestation in Visa Intelligent Commerce (VIC). The Attestation Options API generates a challenge and supporting parameters required to verify a consumer device's authenticity. This step is typically part of a WebAuthn or FIDO-based flow and ensures that only trusted devices can be registered or used for transactions in VIC.

Purpose

• Provide the cryptographic challenge and relying party details required for device attestation.
• Enable secure device registration during onboarding or when adding a new device.
• Ensure that only verified devices can be linked to a consumer's VIC profile.

When to use

• During consumer onboarding when binding their device to VIC.
• When a consumer adds a new device to their profile.
• When re-testing or re-attesting a device due to a change in security status.

Endpoint: POST /vts/provisionedTokens/{vProvisionedTokenID}/deviceBinding

Request parameter

• intent = FIDO

Interpret response

• status = APPROVED: continue to Passkey registration.
• status = CHALLENGE: handle step-up authentication. The list of step-up methods received in the stepUpRequest object must be presented to the consumer for them to choose their preferred method. The identifier field received in the stepUpRequest object must be tracked and associated with each option, as this value is required in the next step.
• status = DECLINED: inform the consumer that binding cannot proceed.

High-level process

1. The AI agent sends a secure POST request to the /attestation/options endpoint to request attestation parameters.
2. VIC returns a challenge along with parameters such as relying party info, credential creation options, and cryptographic requirements.
3. The AI agent passes these parameters to the consumer's device to perform attestation via WebAuthn/FIDO or a similar protocol.
4. The device produces an attestation response, which is submitted using the /attestation/result API.
5. If no Passkey was found (action = REGISTER), the client must perform device binding using the Request Device Token Binding API. The client can refer to the Visa Digital Solutions API Reference Guide for more information.

If the response from the Request Device Token Binding API is status = CHALLENGE, the client must handle step-up authentication via the Submit ID&V Step-Up Method API. The client can retrieve available ID&V methods from stepUpRequest in the response of the step-up options API and present them to the consumer.

Supported methods of step-up authentication

• OTPSMS
• OTPEMAIL
• OTPONLINEBANKING
• APP-TO-APP
• CUSTOMERSERVICE
• OUTBOUNDCALL

The client can refer to the Visa Digital Solutions API Reference Guide for more information. If the consumer selects one-time passcode (OTP) as the form of authentication, the client can validate the OTP using the Validate OTP Request API.

Endpoints

• Submit ID&V Step-Up Method API: POST /vts/provisionedTokens/{vProvisionedTokenID}/stepUpOptions/method
• Validate OTP Request API: POST /vts/provisionedTokens/{vProvisionedTokenID}/stepUpOptions/validateOTP

For both endpoints, the vProvisionedTokenID provided in the path must be the stored provisioned token identifier provided in the response to the Provision Token API, and the clientReferenceId field must contain the same unique identifier used in the original Get Device Attestation Options API call.

Specific agent action by method

• For out-of-band methods (APP-TO-APP, CUSTOMERSERVICE, OUTBOUNDCALL), wait for MAP notifications (TOKEN_DEVICE_BINDING_APPROVED or CARDHOLDER_STEPUP_APPROVED) before proceeding. The agent must wait for a VTS notification indicating step-up completed successfully, and must present a mechanism indicating to the consumer that they are waiting for the step-up to complete.
• The agent must maintain a record of all out-of-band step-up attempts and be able to link the vProvisionedTokenID received in the request body of the notification to a specific attempt.
• If the method field contains APP-TO-APP, the agent must redirect the consumer to the bank's online banking app using the content of the source field.

The client must register the Passkey after device binding and step-up completion, using the Get Device Attestation Options API.

Endpoint: POST /vts/provisionedTokens/{vProvisionedTokenID}/attestation/options

Request includes

• type = REGISTER
• reasonCode = DEVICE_BINDING

Launch the VTS FIDO SDK (iframe or popup) to complete Passkey registration.

Persist from SDK response

• assuranceData.identifier
• fidoBlob