Concepts
Understanding the object lifecycle, authentication model, and business rules of VIC helps you avoid the integration failures most clients encounter, especially around authentication sequencing and mandate validation.
Purchase types
| Dimension | Agentic (Human-in-the-Loop) | Agentic (Autonomous) | Agentic (Autonomous Recurring) |
|---|---|---|---|
| Purchase decisioning / initiation | Cardholder authorizes transaction through the agent | Agent, within approved bounds | Agent, within standing instruction bounds |
| Checkout execution | Agent via browser automation | Agent via API or browser automation | Agent via API or browser automation |
| Cardholder authorization scope | Cardholder authorizes a specific transaction | Bounded one-time purchase instruction | Bounded standing purchase instruction |
| Tokenization | Required | Required | Required |
| ID&V for all tokens used in VIC | Required | Required | Required |
| Agent-side verification | Required via Visa Payment Passkeys or another approved method | Required via Visa Payment Passkeys or another approved method | Required via Visa Payment Passkeys or another approved method |
| Purchase Instructions | Required to evidence the specific authorized transaction for disputes | Required to evidence the specific authorized instruction for disputes | Required to evidence the specific authorized recurring instruction for disputes |
| Payment Data | Required | Required | Required |
| Signals (Agent order data) | Required to evidence agent execution context | Required to evidence agent execution context | Required to evidence agent execution context |
Authentication and encryption methods
Visa Intelligent Commerce uses mutual TLS (two-way SSL) as its transport-layer authentication, plus a request-level agent signature and multi-factor consumer authentication layered on top.
VIC and Visa Token Service (VTS) are authenticated separately; do not treat them as one scheme: VIC calls use mutual TLS.
Get your authentication credentials
Obtain your mutual TLS client certificate through standard Visa Developer onboarding. If your integration requires an agent signature (see Set Up Agent Signature), also provision a signing key pair (Ed25519, RS256, or ES256) during onboarding. Visa validates your public key via the Visa Agent Registry Service (VARS) at the time of credential retrieval.
Set up agent signature
- Generate a signatureInput object containing created and expires (Unix epoch timestamps), your keyId, the signing alg (Ed25519, RS256, or ES256), a unique nonce, and tag: credential-request.
- Sign the signatureInput with your private key and base64-encode the result as signature.
- Include both as client.agent.agentSignature in every request (CompositeTransactionDataExtendedV2, CredentialTransactionDataRequestV2, ConfirmationRequestDataV2, CancelInstructionDataV2).
agentSignature is a required field within the JSON request body (client.agent.agentSignature), not an HTTP header. This differs from typical token-in-header authentication schemes. It is required when the agent is a Trusted Agent Provider or the TR is a Wallet Provider, and is not provided for an Open Source Agent (whose agentId is fixed at 11111111111).
Consumer authentication
Consumer authentication supports multiple methods, recorded as assuranceData, an array of verification records: FIDO2 biometric/device-based (verificationMethod: 23), app-based authentication (02), one-time passcode (04), and Visa Token Service step-up for device binding (21) or cardholder verification (22). Handle whichever method is presented to the consumer. VIC validates that authentication is valid before credentials are returned.
Field-level vs. message-level encryption
Your client codebase must reconcile two distinct protection models: Visa Token Service applies Field-Level Encryption to sensitive fields (such as PAN data) during enrollment, provisioning, and device binding, while VIC applies Message-Level Encryption to credential-retrieval responses (the signedPayload/encryptedSignedPayload JWS/JWE fields) that must be decrypted and handled only in memory. Store and rotate keys and secrets for each independently.
Test connectivity
Stand up your full authentication stack (mutual TLS, FIDO2/device-based consumer authentication, and device fingerprinting) before attempting any transaction flow. Clients most commonly underestimate the coordination this requires; treat it as a prerequisite, not something built alongside the integration.
Environment notes
See Environment Hosts and URL Structure for environment URLs, data availability, and setup timing.
Core operations
Lifecycles
Instruction / mandate status
| State / Status | Meaning | Transitions to |
|---|---|---|
| ACTIVE | Instruction created; further credential retrievals permitted. Recurring instructions remain valid until the mandate's effectiveUntilTime or until cancelled. | COMPLETED, CANCELLED, EXPIRED |
| COMPLETED | Instruction completed (instructionCompleted=true); no further retrievals permitted | (terminal) |
| CANCELLED | Instruction has been cancelled | (terminal) |
| EXPIRED | Instruction has expired | (terminal) |
An issuer or the Visa Token Service can revoke a consumer's provisioned token independently of instruction or mandate state. Revocation is not reflected as an instruction status change and carries no callback or notification (the first sign is typically a failed credential retrieval against a tokenId that previously worked). Treat an unexpected UNAUTHENTICATED or NOT_FOUND on a previously valid tokenId as a possible revocation, not only as a transient failure.
Instructions default to a 90-day (US) intent expiration. Assurance data remains valid for that same window (or for whatever validity period Visa Payment Passkeys assigns to FIDO-based assertions), and if assurance data has expired, no further credential will be returned. For recurring instructions, the mandate's effectiveUntilTime specified the expiration window.
Controls and rules
- Mandate-scoped credential retrieval: Each credential retrieval is scoped to exactly one instructionId; within it, a request references exactly one mandateId (transactionData.mandateReferenceData.mandateId) and is validated against that mandate's declineThreshold. Visa aggregates this check across the entire instruction: it sums all transactions and mandates on the instructionId (including prior transactions) and confirms the total does not exceed the decline threshold.
- Transactions: When a transaction references a specific mandateId, Visa also checks that the transaction's merchant name matches any preferred merchant name set on that mandate, and that the transactionAmount alone does not exceed the mandate's declineThreshold.
- Recurring frequency behavior: For a recurring mandate, Visa checks that each credential retrieval fulfills the stated recurringFrequency and effectiveUntilTime dates. If the recurring frequency is set to YEARLY, the maximum that can be set is 5 years.
- Unique transaction references: Every transactionReferenceId submitted against an instruction must be unique.
- Consistent consumerId across enrollments: When an Agent Enabler performs enrollment, consumerId must be identical for every card enrolled for the same consumer. Assigning a new consumerId per card prevents Visa from correlating multiple payment credentials to one consumer.
- Maximum 50 tokens per consumerId: Agent/Agent Enablers are expected to monitor this 50 token limit per consumerId, and perform token LCM to deactivate/delete not needed tokens if necessary.
- Maximum 10 mandates per instruction: If more than 10 mandates are required, multiple instruction id can be created.
- Cryptogram retrieval rate limit: A maximum of 15 cryptograms may be retrieved under one token within a rolling 24-hour window; the limit resets after 24 hours.
- Fresh agent signature per call: Each POST /vacp/v2/instructions/{instructionId}/credentials call requires a fresh agentSignature, for non-repudiation and audit purposes; neither may be reused across calls. When agentSignature is required (the agent is a Trusted Agent Provider or the TR is a Wallet Provider, see Set Up Agent Signature), Visa validates it against the Visa Agent Registry Service (VARS) at credential retrieval to confirm the agent is a registered, trusted provider.
- Expiration for authentication and instructions: Consumer authentication sessions and purchase instructions expire per the default intent-expiration window (see Lifecycle). If the instruction is expired, the agent must cancel and recall the Credentials for Instruction API with fresh and valid authentication data.
- Update via Cancellation: There is no endpoint to modify an existing instruction or mandate. To change a purchase instruction (a different product, a different budget, an added mandate), the agent cancels the existing instruction and creates a new one via the Credentials For Instruction API.
- Restricted Merchant Categories: Clients must not submit transactions containing products associated with restricted Merchant Category Codes (MCCs); these are automatically declined. The current list of restricted MCCs is maintained in the VIC and TAP Client Implementation Guide.
- 3DS and SCA Behavior: US merchants that support 3-D Secure (3DS) receive a "Program Not Supported" response for agentic transactions in US only; other regions have 3DS enabled with region-specific treatment. Strong Customer Authentication (SCA) in Europe is supported via Visa Payment Passkeys.
Agents must also comply with the acceptable use policy requirements described under Agent Provider program obligations (see Production readiness).