# Visa Intelligent Commerce
Enabling safe, secure, and personalized agentic commerce - at scale
## Version: 1
### Servers
| URL | Description |
| --- | ----------- |
| https://sandbox.api.visa.com | Sandbox server |
---
## Visa Intelligent Commerce V2 Bundle APIs
Visa Intelligent Commerce V2 Bundle APIs
### [PUT] /vacp/v2/instructions/{instructionId}/cancel
**Cancel Instruction V2**
The Cancel Instruction API cancels a previously established instruction and all its associated mandates.
The instruction must be in ACTIVE status. If a credential has been retrieved, the Confirm Transaction
Events API must be called before cancellation is permitted. Cancellation is permanent and cannot be
recovered. Already-issued credentials remain valid and may still be used by the merchant.
This API is implemented as a backend service designed for secure server-to-server communication.
#### Request Body
| Required | Schema |
| -------- | ------ |
| Yes | **application/json**: { **"client"**: { **"agent"**: { **"agentId"**: , **"agentSignature"**: { **"signature"**: , **"signatureInput"**: { **"alg"**:
**Available values:** "Ed25519", "RS256", "ES256", **"tag"**:
**Available values:** "credential-request", "confirmation-request", **"keyId"**: , **"nonce"**: , **"created"**: , **"expires"**: } } }, **"authorization"**: , **"externalAppId"**: , **"relationshipId"**: , **"externalClientId"**: }, **"appInstance"**: { **"ipAddress"**: , **"userAgent"**: , **"deviceData"**: { **"type"**: , **"brand"**: , **"model"**: , **"manufacturer"**: }, **"countryCode"**: undefined (ISO 3166-1-alpha2), **"clientDeviceId"**: , **"applicationName"**: }, **"assuranceData"**: , **"clientReferenceId"**: }
|
#### Responses
| Code | Description | Schema |
| ---- | ----------- | ------ |
| 200 | BaseInstructionResponse - Response Body | **application/json**: { **"instructionId"**: , **"clientReferenceId"**: }
|
| 400 | Bad request, see Error object for details, e.g. one or more elements in the request are malformed or invalid request. | **application/json**: { **"reason"**: , **"status"**: , **"message"**: , **"errorDetail"**: }
|
| 401 | Unauthorized, see Error object for details, e.g. invalid MTLS, x-pay-token or apiKey. | **application/json**: { **"reason"**: , **"status"**: , **"message"**: , **"errorDetail"**: }
|
| 403 | Forbidden, see Error object for details, e.g. attempt to access forbidden resource. | **application/json**: { **"reason"**: , **"status"**: , **"message"**: , **"errorDetail"**: }
|
| 404 | Not found, see Error object for details, e.g. the reference to the consumer identity, clientId or transactionId in the request data was not found. | **application/json**: { **"reason"**: , **"status"**: , **"message"**: , **"errorDetail"**: }
|
| 409 | Requested Operation cannot be performed. | **application/json**: { **"reason"**: , **"status"**: , **"message"**: , **"errorDetail"**: }
|
| 500 | Internal server error, see Error object for details. | **application/json**: { **"reason"**: , **"status"**: , **"message"**: , **"errorDetail"**: }
|
| default | Internal server error, see Error object for details. | **application/json**: { **"reason"**: , **"status"**: , **"message"**: , **"errorDetail"**: }
|
---
### Schemas
#### Address Schema
Address data.
| Name | Type | Description | Required |
| ---- | ---- | ----------- | -------- |
| zip | | (Conditional) Address zip/postal code Conditionality: When used with the DPA Registration operation in the Management Service APIs at least one of the following is required: • both city and state • zip Required if this is a shipping address in a valid format for the country and has a postal code or zip code | No |
| city | | (Conditional) Address city Conditionality: When used with the DPA Registration operation in the Management Service APIs at least one of the following is required: • both city and state • zip Required if this is a shipping address in a valid format for the country | No |
| name | | (Optional) Name of the business; Name of the community; c/o Name etc. Notes: Shipping Address - The final recipient's name will be captured in deliveryContacts field. Billing Address - The Card Holder or Consumer Name will be recorded as part of Card or Order Information. | No |
| line1 | | (Conditional) Address line 1 Conditionality: Required when used with the DPA Registration operation in the Management Service APIs Required when address is used as shipping/delivery Address. | No |
| line2 | | (Optional) Address line 2 | No |
| line3 | | (Optional) Address line 3 | No |
| state | | (Conditional) Address state Recommendation to support ISO 3166-2 format i.e. made up of ISO 3166-1 alpha 2 country code, followed by an alphanumeric string of 3 characters representing the state or sub-division Conditionality: When used with the DPA Registration operation in the Management Service APIs at least one of the following is required: • both city and state • zip Required if this is a shipping address in a valid format for the country | No |
| addressId | undefined (uuid) | (Conditional) Reference identifier of the address Conditionality: Required when address is already registered with VACP System. Optional for requests when address fields are provided. | No |
| createTime | | (Optional) Date and time the address was created. UTC time in Unix epoch format | No |
| countryCode | undefined (ISO 3166-1-alpha2) | (Required) Address country code ISO 3166-1 alpha-2 country code | Yes |
| lastUsedTime | | (Optional) Date and time the address was last used. UTC time in Unix epoch format | No |
#### VerificationType Schema
Type of the verification data. Default value is CARDHOLDER
| Name | Type | Description | Required |
| ---- | ---- | ----------- | -------- |
| VerificationType |
**Available values:** "CARDHOLDER", "DEVICE" | Type of the verification data. Default value is CARDHOLDER | |
#### PersonalizationData Schema
| Name | Type | Description | Required |
| ---- | ---- | ----------- | -------- |
| action |
**Available values:** "ACCEPT", "MODIFY", "REVOKE" | (Required) Action to be taken for personalization consent. ACCEPT - Consumer accepts the personalization consent. REVOKE - Consumer revokes the personalization consent that was previously accepted. MODIFY - Consumer modifies the personalization consent that was previously accepted.
*Enum:* `"ACCEPT"`, `"MODIFY"`, `"REVOKE"` | Yes |
| client | { **"agentId"**: , **"authorization"**: , **"externalAppId"**: , **"relationshipId"**: , **"externalClientId"**: } | (Required) Contains Agent(TR) information and, in the case that an Agent Enabler(TR-TSP) is acting on behalf of an Agent(TR), the authorization and relationship information. | Yes |
| consumerId | | (Required) Unique identifier of the consumer previously provided when enrolling a card. | Yes |
| consentData | { **"id"**: , **"type"**:
**Available values:** "PERSONALIZATION", **"source"**: , **"acceptedTime"**: , **"effectiveUntil"**: } | (Conditional) An array of consumer consents for the use of their data for personalization and platform functionality, ensuring compliance with Visa's privacy and regulatory requirements. | No |
| clientReferenceId | | (Required) Transactional identifier provided by the Client. | Yes |
#### PaymentTokenExtended Schema
Extended payment token structure for v1/credentials API. Includes eci field in addition to base PaymentToken fields.
| Name | Type | Description | Required |
| ---- | ---- | ----------- | -------- |
| PaymentTokenExtended | { **"paymentToken"**: , **"tokenExpirationYear"**: , **"tokenExpirationMonth"**: } & { **"eci"**: } | Extended payment token structure for v1/credentials API. Includes eci field in addition to base PaymentToken fields. | |
#### Product Schema
Contains order/product details, including but not limited to productId, productName, totalAmount, quantity,
description, SKU, DeliveryMethod, ShippingAddress, additional-data
| Name | Type | Description | Required |
| ---- | ---- | ----------- | -------- |
| policies | { **"refundPolicy"**: , **"disputePolicy"**: , **"shippingPolicy"**: , **"cancellationPolicy"**: , **"termsAndConditions"**: , **"discountAndPromotions"**: } | terms and conditions, and polices associated to the Product/Sale. | No |
| quantity | | (Conditional) Quantity of the product.
*Example:* `"10"` | No |
| productId | | unique identifier for the product
*Example:* `"1234"` | No |
| unitPrice | { **"amount"**: , **"currencyCode"**: } | The price of a single unit of the product | No |
| productUrl | | URL of the product
*Example:* `"https://www.example.com/product/1234"` | No |
| productName | | Name of the product.
*Example:* `"Balloons"` | No |
| additionalInfo | | Additional information about the product. | No |
| transactionAmount | { **"tax"**: , **"discount"**: , **"subTotal"**: , **"transactionAmount"**: , **"shippingAndHandling"**: , **"transactionCurrencyCode"**: } | The final amount that the customer needs to pay or paid. | No |
#### EffectiveUntil Schema
Date and time until which the personalization consent is effective. UTC time in Unix epoch format.
| Name | Type | Description | Required |
| ---- | ---- | ----------- | -------- |
| EffectiveUntil | | Date and time until which the personalization consent is effective. UTC time in Unix epoch format. | |
#### AuthenticationMethod Schema
Authentication method.
| Name | Type | Description | Required |
| ---- | ---- | ----------- | -------- |
| uriData | { **"uri"**: , **"uriType"**:
**Available values:** "APP_URI", "WEB_URI" } | URI data. | No |
| methodAttributes | { **"threeDsData"**: } | Authentication/Verification Method Attributes | No |
| authenticationSubject |
**Available values:** "CARDHOLDER", "CONSUMER", "CARD" | Authentication subject.
*Enum:* `"CARDHOLDER"`, `"CONSUMER"`, `"CARD"` | No |
| authenticationMethodType |
**Available values:** "SMS_OTP", "EMAIL_OTP", "APP_OTP", "3DS", "CSC_VALIDATION", "APP_AUTHENTICATION", "ADDRESS_VERIFICATION", "FIDO2", "SPC" | Authentication method type.
*Enum:* `"SMS_OTP"`, `"EMAIL_OTP"`, `"APP_OTP"`, `"3DS"`, `"CSC_VALIDATION"`, `"APP_AUTHENTICATION"`, `"ADDRESS_VERIFICATION"`, `"FIDO2"`, `"SPC"` | Yes |
| authenticationCredentialReference | | May be provided by the identity provider once an authentication is initiated to qualify the nature of the authentication method (e.g. for SMS_OTP, this may include the masked mobile number \\"***-***-1234\\", which can be displayed to the Consumer to aid method selection) | No |
#### Instruction Schema
| Name | Type | Description | Required |
| ---- | ---- | ----------- | -------- |
| client | { **"agentId"**: , **"authorization"**: , **"externalAppId"**: , **"relationshipId"**: , **"externalClientId"**: } | (Required) Contains Agent(TR) information and, in the case that an Agent Enabler(TR-TSP) is acting on behalf of an Agent(TR), the authorization and relationship information. | Yes |
| tokenId | | (Required)A Token Reference Identifier for a card that can be used for payments. This identifier is used to reference a specific tokenized card across various operations. | Yes |
| consumer | { **"consumerId"**: , **"countryCode"**: undefined (ISO 3166-1 alpha-2), **"languageCode"**: , **"consumerIdentities"**: } | (Required) A unique identifier for the Consumer within the Client's system. If enrollment is being performed by an agent enabler, this consumerId will be associated with the agent and must be identical for each card being enrolled for the same consumer. | No |
| mandates | | (Conditional) Consumer Set Transaction Mandates Conditionality: Required when a purchase intent is initiated with a mandate by consumer. | Yes |
| ~~frequency~~ |
**Available values:** "WEEKLY", "MONTHLY", "YEARLY" | (Optional) Frequency of the transaction. Required when isRecurring flag is true Note: This field is deprecated. Please use the recurringFrequency field within Mandate instead.
*Enum:* `"WEEKLY"`, `"MONTHLY"`, `"YEARLY"`
**Deprecated** | No |
| consumerId | | (Conditional) Reference identifier of the Consumer. Required if consumer object is not provided. | No |
| appInstance | { **"ipAddress"**: , **"userAgent"**: , **"deviceData"**: { **"type"**: , **"brand"**: , **"model"**: , **"manufacturer"**: }, **"countryCode"**: undefined (ISO 3166-1-alpha2), **"clientDeviceId"**: , **"applicationName"**: } | (Required) Device and Application instance data. | Yes |
| isRecurring | | (Optional) Indicates whether the transaction is recurring. Default value is false. | No |
| assuranceData | | (Required) FIDO Attestation/Assertion Data. | Yes |
| consumerPrompt | | (Optional) Recap - A summary or condensed version of user prompts that leads to the purchase. | No |
| clientReferenceId | | (Required) Transactional identifier provided by the Client. | Yes |
#### ShippingDataV2 Schema
Shipping and tracking data. Present in EncryptedPurchaseData (decoded from
confirmationData.encryptedPurchaseData) for /v2/instructions/{id}/confirmation.
| Name | Type | Description | Required |
| ---- | ---- | ----------- | -------- |
| carrier | | (Optional) Shipping carrier or provider. | No |
| trackingId | | (Optional) Tracking ID for the shipment. | No |
| shippingMethod | | (Optional) Method of shipping (e.g., Standard, Express). | No |
#### InstructionActiveStatus Schema
Purchase Status. ACTIVE - Instruction has been created. Purchase can be initiated. COMPLETED - Purchase has been
completed. SecurePayload is included in the response.
| Name | Type | Description | Required |
| ---- | ---- | ----------- | -------- |
| InstructionActiveStatus |
**Available values:** "ACTIVE", "COMPLETED" | Purchase Status. ACTIVE - Instruction has been created. Purchase can be initiated. COMPLETED - Purchase has been completed. SecurePayload is included in the response. | |
#### Consumer Schema
(Required) Consumer/Card Holder data for Validation/Reporting.
| Name | Type | Description | Required |
| ---- | ---- | ----------- | -------- |
| fullName | | (Optional) Consumer-provided full name | No |
| lastName | | (Optional) Consumer-provided last name | No |
| firstName | | (Optional) Consumer-provided first name | No |
| consumerId | | (Required) A unique identifier for the Consumer within the Client's system. If enrollment is being performed by an agent enabler, this consumerId will be associated with the agent and must be identical for each card being enrolled for the same consumer. | Yes |
| countryCode | undefined (ISO 3166-1 alpha-2) | (Required) Consumer-provided country code. ISO 3166-1 alpha-2 country code | Yes |
| emailAddress | undefined (email) | (Optional) Consumer-provided email address | No |
| languageCode | | (Required) Consumer-provided language choice. ISO 639-1 Code. | Yes |
| mobileNumber | { **"countryCode"**: , **"phoneNumber"**: , **"numberIsVoiceOnly"**: } | (Optional) Primary Phone Number. primary phone won't be considered as identity, unless present in consumerIdentities. | No |
| consumerIdentities | | (Required) Consumer identities data. Conditions: 1. At least one of `consumerIdentity` or `consumerIdentities` is required. 2. Provide all consumer identities that can be used by the consumer to login. | Yes |
| nationalIdentifier | | Conditional: Geographic-specific, nationally-provided identifier for the Consumer. Conditionality: When required as per country specific regulations. | No |
#### Consent Schema
(Conditional) An array of consumer consents for the use of their data for personalization and platform functionality, ensuring compliance with Visa's privacy and regulatory requirements.
| Name | Type | Description | Required |
| ---- | ---- | ----------- | -------- |
| id | | (Required) Unique identifier for the consent.
*Example:* `"550e8400-e29b-41d4-a716-446655440000"` | Yes |
| type |
**Available values:** "PERSONALIZATION" | (Required) Type of the consent.
*Enum:* `"PERSONALIZATION"` | Yes |
| source | | (Required) Source of the consent.
*Example:* `"CLIENT"` | Yes |
| acceptedTime | | (Required) Date and time when the consent was accepted by the consumer. UTC time in Unix epoch format.
*Example:* `"1719169800"` | Yes |
| effectiveUntil | | (Required) Date and time until which the consent remains effective. UTC time in Unix epoch format.
*Example:* `"1750705800"` | Yes |
#### DeviceData Schema
Device data.
| Name | Type | Description | Required |
| ---- | ---- | ----------- | -------- |
| type | | Type of device being used. Example values are: • Mobile Phone • Tablet • Laptop • Personal Assistant • Connected Auto • Home Appliance • Wearable • Stationary Computer • E-Reader • Handheld Gaming Devices • Other | Yes |
| brand | | Brand name of the device | Yes |
| model | | Specific model of the device | No |
| manufacturer | | Manufacturer of the device | No |
#### CancelInstructionDataV2 Schema
Request schema for PUT /vacp/v2/instructions/{id}/cancel.
Removes assuranceData single-object from V1; uses array aligned
with all V2 endpoints. Adds ClientWithAgent for agent identity.
Note: requirements state assuranceData is not required for cancel (poor UX); confirm with PO.
| Name | Type | Description | Required |
| ---- | ---- | ----------- | -------- |
| client | { **"agent"**: { **"agentId"**: , **"agentSignature"**: { **"signature"**: , **"signatureInput"**: { **"alg"**:
**Available values:** "Ed25519", "RS256", "ES256", **"tag"**:
**Available values:** "credential-request", "confirmation-request", **"keyId"**: , **"nonce"**: , **"created"**: , **"expires"**: } } }, **"authorization"**: , **"externalAppId"**: , **"relationshipId"**: , **"externalClientId"**: } | Client with Agent(TR) information and, in the case that an Agent Enabler(TR-TSP) is acting on behalf of an Agent(TR), the authorization and relationship information. | Yes |
| appInstance | { **"ipAddress"**: , **"userAgent"**: , **"deviceData"**: { **"type"**: , **"brand"**: , **"model"**: , **"manufacturer"**: }, **"countryCode"**: undefined (ISO 3166-1-alpha2), **"clientDeviceId"**: , **"applicationName"**: } | (Required) Device and Application instance data. | Yes |
| assuranceData | | (Required) FIDO Attestation/Assertion Data. | Yes |
| clientReferenceId | | (Required) Transactional identifier provided by the Client. | Yes |
#### DeliveryContactDetails Schema
Delivery Contact Details associated with a shipping address.
| Name | Type | Description | Required |
| ---- | ---- | ----------- | -------- |
| instructions | | (Optional) Consumer-provided delivery instructions | No |
| contactFullName | | (Optional) Consumer-provided name of the contact person | No |
| contactPhoneNumber | { **"countryCode"**: , **"phoneNumber"**: , **"numberIsVoiceOnly"**: } | (Optional) Primary Phone Number. primary phone won't be considered as identity, unless present in consumerIdentities. | No |
| contactEmailAddress | undefined (email) | (Optional) Consumer-provided email address | No |
#### PartnerReferenceId Schema
(Optional) Supplemental Transactional identifier provided by the Partner of the client.
| Name | Type | Description | Required |
| ---- | ---- | ----------- | -------- |
| PartnerReferenceId | | (Optional) Supplemental Transactional identifier provided by the Partner of the client. | |
#### TransactionDetailExtended Schema
Transaction detail for /v2/credentials-for-instruction API.
| Name | Type | Description | Required |
| ---- | ---- | ----------- | -------- |
| TransactionDetailExtended | { **"merchantUrl"**: , **"merchantName"**: , **"transactionAmount"**: { **"tax"**: , **"discount"**: , **"subTotal"**: , **"transactionAmount"**: , **"shippingAndHandling"**: , **"transactionCurrencyCode"**: }, **"transactionReferenceId"**: } & { **"merchantId"**: , **"billingAddress"**: { **"zip"**: , **"city"**: , **"name"**: , **"line1"**: , **"line2"**: , **"line3"**: , **"state"**: , **"addressId"**: undefined (uuid), **"createTime"**: , **"countryCode"**: undefined (ISO 3166-1-alpha2), **"lastUsedTime"**: }, **"deliveryMethod"**:
**Available values:** "NO_DELIVERY", "ADDRESS_BILLING", "ADDRESS_ON_FILE", "ADDRESS_OTHER", "PICKUP", "ELECTRONIC", **"merchantDomain"**: , **"paymentOptions"**: { **"dynamicDataType"**:
**Available values:** "CARD_APPLICATION_CRYPTOGRAM_SHORT_FORM", "DYNAMIC_CARD_SECURITY_CODE", "NONE",
**Default:** CARD_APPLICATION_CRYPTOGRAM_SHORT_FORM, **"encryptionOverride"**: }, **"shippingAddress"**: { **"zip"**: , **"city"**: , **"name"**: , **"line1"**: , **"line2"**: , **"line3"**: , **"state"**: , **"addressId"**: undefined (uuid), **"createTime"**: , **"countryCode"**: undefined (ISO 3166-1-alpha2), **"lastUsedTime"**: } & { **"deliveryContactDetails"**: { **"instructions"**: , **"contactFullName"**: , **"contactPhoneNumber"**: { **"countryCode"**: , **"phoneNumber"**: , **"numberIsVoiceOnly"**: }, **"contactEmailAddress"**: undefined (email) } } } | Transaction detail for /v2/credentials-for-instruction API. | |
#### TransactionDataExtended Schema
Transaction data object for /v2/credentials-for-instruction API with billing address support.
Includes: transactionAmount, merchantName, merchantUrl, billingAddress, shippingAddress, paymentOptions, encryptedInstruction, policies, etc.
| Name | Type | Description | Required |
| ---- | ---- | ----------- | -------- |
| TransactionDataExtended | { **"merchantUrl"**: , **"merchantName"**: , **"transactionAmount"**: { **"tax"**: , **"discount"**: , **"subTotal"**: , **"transactionAmount"**: , **"shippingAndHandling"**: , **"transactionCurrencyCode"**: }, **"transactionReferenceId"**: } & { **"merchantId"**: , **"billingAddress"**: { **"zip"**: , **"city"**: , **"name"**: , **"line1"**: , **"line2"**: , **"line3"**: , **"state"**: , **"addressId"**: undefined (uuid), **"createTime"**: , **"countryCode"**: undefined (ISO 3166-1-alpha2), **"lastUsedTime"**: }, **"deliveryMethod"**:
**Available values:** "NO_DELIVERY", "ADDRESS_BILLING", "ADDRESS_ON_FILE", "ADDRESS_OTHER", "PICKUP", "ELECTRONIC", **"merchantDomain"**: , **"paymentOptions"**: { **"dynamicDataType"**:
**Available values:** "CARD_APPLICATION_CRYPTOGRAM_SHORT_FORM", "DYNAMIC_CARD_SECURITY_CODE", "NONE",
**Default:** CARD_APPLICATION_CRYPTOGRAM_SHORT_FORM, **"encryptionOverride"**: }, **"shippingAddress"**: { **"zip"**: , **"city"**: , **"name"**: , **"line1"**: , **"line2"**: , **"line3"**: , **"state"**: , **"addressId"**: undefined (uuid), **"createTime"**: , **"countryCode"**: undefined (ISO 3166-1-alpha2), **"lastUsedTime"**: } & { **"deliveryContactDetails"**: { **"instructions"**: , **"contactFullName"**: , **"contactPhoneNumber"**: { **"countryCode"**: , **"phoneNumber"**: , **"numberIsVoiceOnly"**: }, **"contactEmailAddress"**: undefined (email) } } } & { **"policies"**: { **"refundPolicy"**: , **"disputePolicy"**: , **"shippingPolicy"**: , **"cancellationPolicy"**: , **"termsAndConditions"**: , **"discountAndPromotions"**: }, **"encryptedInstruction"**: , **"mandateReferenceData"**: , **"transactionReferenceIdType"**:
**Available values:** "ENCRYPTED" } | Transaction data object for /v2/credentials-for-instruction API with billing address support. Includes: transactionAmount, merchantName, merchantUrl, billingAddress, shippingAddress, paymentOptions, encryptedInstruction, policies, etc. | |
#### TransactionItem Schema
| Name | Type | Description | Required |
| ---- | ---- | ----------- | -------- |
| TransactionItem | { **"merchantUrl"**: , **"merchantName"**: , **"transactionAmount"**: { **"tax"**: , **"discount"**: , **"subTotal"**: , **"transactionAmount"**: , **"shippingAndHandling"**: , **"transactionCurrencyCode"**: }, **"transactionReferenceId"**: } & { **"products"**: , **"merchantId"**: , **"attachments"**: , **"deliveryMethod"**:
**Available values:** "NO_DELIVERY", "ADDRESS_BILLING", "ADDRESS_ON_FILE", "ADDRESS_OTHER", "PICKUP", "ELECTRONIC", **"merchantDomain"**: , **"merchantLocale"**: , **"paymentOptions"**: { **"dynamicDataType"**:
**Available values:** "TAVV", "DAVV", "NONE", **"dpaDynamicDataTtlMinutes"**: }, **"merchantOrderId"**: , **"shippingAddress"**: { **"zip"**: , **"city"**: , **"name"**: , **"line1"**: , **"line2"**: , **"line3"**: , **"state"**: , **"addressId"**: undefined (uuid), **"createTime"**: , **"countryCode"**: undefined (ISO 3166-1-alpha2), **"lastUsedTime"**: } & { **"deliveryContactDetails"**: { **"instructions"**: , **"contactFullName"**: , **"contactPhoneNumber"**: { **"countryCode"**: , **"phoneNumber"**: , **"numberIsVoiceOnly"**: }, **"contactEmailAddress"**: undefined (email) } }, **"transactionType"**:
**Available values:** "PURCHASE", "BILL_PAYMENT", "MONEY_TRANSFER", "DISBURSEMENT", "P2P", **"merchantCountryCode"**: undefined (ISO 3166-1-alpha2), **"merchantCategoryCode"**: , **"paymentServiceProviderUrl"**: , **"paymentServiceProviderName"**: } & { **"mandateReferenceData"**: } | | |
#### InstructionId Schema
(Required) Unique instruction identifier.
| Name | Type | Description | Required |
| ---- | ---- | ----------- | -------- |
| InstructionId | | (Required) Unique instruction identifier. | |
#### InstructionTerminalStatus Schema
Purchase Status. EXPIRED - Purchase Instruction has expired. CANCELLED - Purchase Instruction has been cancelled.
| Name | Type | Description | Required |
| ---- | ---- | ----------- | -------- |
| InstructionTerminalStatus |
**Available values:** "EXPIRED", "CANCELLED" | Purchase Status. EXPIRED - Purchase Instruction has expired. CANCELLED - Purchase Instruction has been cancelled. | |
#### PaymentOptionsEmv Schema
payment options for /v2/credentials-for-instruction API with encryption override and EMV dynamic data types
| Name | Type | Description | Required |
| ---- | ---- | ----------- | -------- |
| dynamicDataType |
**Available values:** "CARD_APPLICATION_CRYPTOGRAM_SHORT_FORM", "DYNAMIC_CARD_SECURITY_CODE", "NONE",
**Default:** CARD_APPLICATION_CRYPTOGRAM_SHORT_FORM | Type of Dynamic Data required in the payload. Default value is CARD_APPLICATION_CRYPTOGRAM_SHORT_FORM.
*Enum:* `"CARD_APPLICATION_CRYPTOGRAM_SHORT_FORM"`, `"DYNAMIC_CARD_SECURITY_CODE"`, `"NONE"` | No |
| encryptionOverride | | (Optional) Indicates whether the encryption configuration during merchant onboarding should be ignored. Values: true or false. Default: false. | No |
#### JSONObject Schema
Represents a free-form JSON Object data structure.
| Name | Type | Description | Required |
| ---- | ---- | ----------- | -------- |
| JSONObject | | Represents a free-form JSON Object data structure. | |
#### UpdateInstructionData Schema
| Name | Type | Description | Required |
| ---- | ---- | ----------- | -------- |
| client | { **"agentId"**: , **"authorization"**: , **"externalAppId"**: , **"relationshipId"**: , **"externalClientId"**: } | (Required) Contains Agent(TR) information and, in the case that an Agent Enabler(TR-TSP) is acting on behalf of an Agent(TR), the authorization and relationship information. | Yes |
| tokenId | | (Required)A Token Reference Identifier for a card that can be used for payments. This identifier is used to reference a specific tokenized card across various operations. | Yes |
| mandates | | (Required) Consumer Set Transaction Mandates Required when a purchase intent is initiated with a mandate by consumer. | Yes |
| consumerId | | (Optional) Reference identifier of the Consumer. | No |
| appInstance | { **"ipAddress"**: , **"userAgent"**: , **"deviceData"**: { **"type"**: , **"brand"**: , **"model"**: , **"manufacturer"**: }, **"countryCode"**: undefined (ISO 3166-1-alpha2), **"clientDeviceId"**: , **"applicationName"**: } | (Required) Device and Application instance data. | Yes |
| assuranceData | | (Required) FIDO Attestation/Assertion Data. | Yes |
| consumerPrompt | | (Optional) Recap - A summary or condensed version of user prompts that leads to the purchase. | No |
| clientReferenceId | | (Required) Transactional identifier provided by the Client. | Yes |
#### ConsumerId Schema
(Required) Reference identifier of the Consumer.
| Name | Type | Description | Required |
| ---- | ---- | ----------- | -------- |
| ConsumerId | | (Required) Reference identifier of the Consumer. | |
#### PaymentToken Schema
| Name | Type | Description | Required |
| ---- | ---- | ----------- | -------- |
| paymentToken | | ISO/IEC 7812 format. Payment Token | Yes |
| tokenExpirationYear | | Expiration year expressed as a four-digit calendar year (YYYY) Conditionality: Required when specified for the Payment Token | No |
| tokenExpirationMonth | | Expiration month expressed as a two-digit month (MM) Conditionality: Required when specified for the Payment Token | No |
#### InstructionStatus Schema
Purchase Status. ACTIVE - Instruction has been created. Purchase can be initiated. COMPLETED - Purchase has been
completed. SecurePayload is included in the response. PENDING - Purchase is pending further checks or authentication.
INPROGRESS - Instruction is in progress. Can't be updated/cancelled at this moment. EXPIRED - Purchase Instruction has
expired. CANCELLED - Purchase Instruction has been cancelled.
| Name | Type | Description | Required |
| ---- | ---- | ----------- | -------- |
| InstructionStatus |
**Available values:** "ACTIVE", "COMPLETED", "PENDING", "INPROGRESS", "EXPIRED", "CANCELLED" | Purchase Status. ACTIVE - Instruction has been created. Purchase can be initiated. COMPLETED - Purchase has been completed. SecurePayload is included in the response. PENDING - Purchase is pending further checks or authentication. INPROGRESS - Instruction is in progress. Can't be updated/cancelled at this moment. EXPIRED - Purchase Instruction has expired. CANCELLED - Purchase Instruction has been cancelled. | |
#### ProductSimplified Schema
Contains order/product details, including productId, productName, quantity, unitPrice,
transactionAmount, productUrl, and additionalInfo.
| Name | Type | Description | Required |
| ---- | ---- | ----------- | -------- |
| quantity | | (Conditional) Quantity of the product.
*Example:* `"10"` | No |
| productId | | unique identifier for the product
*Example:* `"1234"` | No |
| unitPrice | { **"amount"**: , **"currencyCode"**: } | The price of a single unit of the product | No |
| productUrl | | URL of the product
*Example:* `"https://www.example.com/product/1234"` | No |
| productName | | Name of the product.
*Example:* `"Balloons"` | No |
| additionalInfo | | Additional information about the product. | No |
| transactionAmount | { **"tax"**: , **"discount"**: , **"subTotal"**: , **"transactionAmount"**: , **"shippingAndHandling"**: , **"transactionCurrencyCode"**: } | The final amount that the customer needs to pay or paid. | No |
#### CredentialsPayload Schema
Payment credentials with card metadata.
Contains EITHER signedPayload (JWS) OR encryptedSignedPayload (JWE), but not both.
Selection depends on paymentOptions.encryptionOverride and merchant encryption key availability.
| Name | Type | Description | Required |
| ---- | ---- | ----------- | -------- |
| network |
**Available values:** "visa", "mastercard", "amex", "discover" | (Optional) Card network
*Enum:* `"visa"`, `"mastercard"`, `"amex"`, `"discover"` | No |
| panLastFour | | (Optional) Last 4 digits of PAN | No |
| signedPayload | undefined (application/jwt) | (Conditional) JWS-formatted signed payload (NOT encrypted). Condition: When encryptionOverride=TRUE OR merchant encryption key not available. Mutually exclusive with encryptedSignedPayload: exactly one of the two is always present. Decoded payload structure: [CredentialsSecuredPayload](#/components/schemas/CredentialsSecuredPayload). Decoded JSON fields: `token`, `dynamicData`, `clientReferenceID`, `authorization`. | No |
| panExpirationYear | | (Optional) PAN expiration year (YYYY) | No |
| panExpirationMonth | | (Optional) PAN expiration month (MM) | No |
| encryptedSignedPayload | | (Conditional) JWE-formatted encrypted+signed payload. Condition: When encryptionOverride=FALSE (or not present) AND merchant encryption key is available. Mutually exclusive with signedPayload: exactly one of the two is always present. After decryption and signature verification, the plaintext is [CredentialsSecuredPayload](#/components/schemas/CredentialsSecuredPayload). Decoded JSON fields: `token`, `dynamicData`, `clientReferenceID`, `authorization`. | No |
| paymentAccountReference | | (Required) Payment Account Reference (PAR), also known as PAR. Condition: Return if found. | No |
#### Authorization Schema
(Conditional) First Party Authorization Token/code: An opaque first party token issued and recognised by the System it issued. The content and structure of these tokens/codes are out of scope of the specification. Refer to client Integration Guide for usage details including but not limited. Conditionality: When additional consumer authentication/action is required.
| Name | Type | Description | Required |
| ---- | ---- | ----------- | -------- |
| Authorization | | (Conditional) First Party Authorization Token/code: An opaque first party token issued and recognised by the System it issued. The content and structure of these tokens/codes are out of scope of the specification. Refer to client Integration Guide for usage details including but not limited. Conditionality: When additional consumer authentication/action is required. | |
#### ThresholdAmount Schema
(Required) Transaction Decline Threshold amount
| Name | Type | Description | Required |
| ---- | ---- | ----------- | -------- |
| amount | | (Required) Transaction Decline Threshold amount | Yes |
| currencyCode | | (Required) ISO 4217 currency code. Currency in which the Transaction Decline Threshold amount is expressed. | Yes |
#### TransactionItemExtended Schema
Transaction item for /v2/credentials-for-instruction API.
| Name | Type | Description | Required |
| ---- | ---- | ----------- | -------- |
| TransactionItemExtended | { **"merchantUrl"**: , **"merchantName"**: , **"transactionAmount"**: { **"tax"**: , **"discount"**: , **"subTotal"**: , **"transactionAmount"**: , **"shippingAndHandling"**: , **"transactionCurrencyCode"**: }, **"transactionReferenceId"**: } & { **"merchantId"**: , **"billingAddress"**: { **"zip"**: , **"city"**: , **"name"**: , **"line1"**: , **"line2"**: , **"line3"**: , **"state"**: , **"addressId"**: undefined (uuid), **"createTime"**: , **"countryCode"**: undefined (ISO 3166-1-alpha2), **"lastUsedTime"**: }, **"deliveryMethod"**:
**Available values:** "NO_DELIVERY", "ADDRESS_BILLING", "ADDRESS_ON_FILE", "ADDRESS_OTHER", "PICKUP", "ELECTRONIC", **"merchantDomain"**: , **"paymentOptions"**: { **"dynamicDataType"**:
**Available values:** "CARD_APPLICATION_CRYPTOGRAM_SHORT_FORM", "DYNAMIC_CARD_SECURITY_CODE", "NONE",
**Default:** CARD_APPLICATION_CRYPTOGRAM_SHORT_FORM, **"encryptionOverride"**: }, **"shippingAddress"**: { **"zip"**: , **"city"**: , **"name"**: , **"line1"**: , **"line2"**: , **"line3"**: , **"state"**: , **"addressId"**: undefined (uuid), **"createTime"**: , **"countryCode"**: undefined (ISO 3166-1-alpha2), **"lastUsedTime"**: } & { **"deliveryContactDetails"**: { **"instructions"**: , **"contactFullName"**: , **"contactPhoneNumber"**: { **"countryCode"**: , **"phoneNumber"**: , **"numberIsVoiceOnly"**: }, **"contactEmailAddress"**: undefined (email) } } } & { **"policies"**: { **"refundPolicy"**: , **"disputePolicy"**: , **"shippingPolicy"**: , **"cancellationPolicy"**: , **"termsAndConditions"**: , **"discountAndPromotions"**: }, **"encryptedInstruction"**: , **"mandateReferenceData"**: , **"transactionReferenceIdType"**:
**Available values:** "ENCRYPTED" } | Transaction item for /v2/credentials-for-instruction API. | |
#### ConfirmationRequestData Schema
| Name | Type | Description | Required |
| ---- | ---- | ----------- | -------- |
| confirmationData | | (Required) Contains Transaction, Order and Payment Confirmation Events. | Yes |
| clientReferenceId | | (Required) Transactional identifier provided by the Client. | Yes |
| mandatesCompleted | | (Optional) Indicates the aggregated status of mandates linked to the instruction. If mandatesCompleted is true, the system updates Visa's ledgers to reflect a "completed" status, with the Agent serving as the authoritative source, required for reconciliation. | No |
#### ConfirmationData Schema
| Name | Type | Description | Required |
| ---- | ---- | ----------- | -------- |
| orderData | { **"orderId"**: , **"products"**: , **"orderDate"**: , **"orderStatus"**: , **"transactionAmount"**: { **"tax"**: , **"discount"**: , **"subTotal"**: , **"transactionAmount"**: , **"shippingAndHandling"**: , **"transactionCurrencyCode"**: }, **"expectedDeliveryDate"**: } | Order data. | No |
| merchantData | { **"merchantId"**: , **"merchantName"**: , **"merchantCategoryCode"**: } | Merchant data. | No |
| shippingData | { **"carrier"**: , **"trackingId"**: , **"shippingMethod"**: , **"shippingAddress"**: { **"zip"**: , **"city"**: , **"name"**: , **"line1"**: , **"line2"**: , **"line3"**: , **"state"**: , **"addressId"**: undefined (uuid), **"createTime"**: , **"countryCode"**: undefined (ISO 3166-1-alpha2), **"lastUsedTime"**: } & { **"deliveryContactDetails"**: { **"instructions"**: , **"contactFullName"**: , **"contactPhoneNumber"**: { **"countryCode"**: , **"phoneNumber"**: , **"numberIsVoiceOnly"**: }, **"contactEmailAddress"**: undefined (email) } } } | Shipping & Tracking Information. | No |
| mandateReferenceData | | (Optional) Contains the list of user mandates associated with the specified transaction or item. The Agent acts as the authoritative source for mandate status and provides this list when one or more mandates are partially fulfilled but not all are complete. This ensures accurate tracking of mandate progress and supports reconciliation processes | No |
| transactionReferenceId | | (Required) Unique identifier for the transaction | Yes |
| paymentConfirmationData | { **"responseCode"**: , **"cardEntryMode"**:
**Available values:** "EMV", "CONTACTLESS", "MANUAL", "ECOMMERCE", "WALLET", **"dynamicDataId"**: , **"transactionType"**:
**Available values:** "PURCHASE", "AUTHORIZATION", "CAPTURE", "REFUND", "REVERSAL", "VERIFICATION", "CHARGEBACK", "FRAUD", **"authorizationCode"**: , **"transactionAmount"**: { **"tax"**: , **"discount"**: , **"subTotal"**: , **"transactionAmount"**: , **"shippingAndHandling"**: , **"transactionCurrencyCode"**: }, **"transactionStatus"**:
**Available values:** "APPROVED", "DECLINED", "PENDING", "ERROR", "CANCELLED", **"transactionTimestamp"**: , **"cardVerificationResult"**: , **"systemTraceAuditNumber"**: , **"acquirerReferenceNumber"**: , **"retrievalReferenceNumber"**: , **"addressVerificationResult"**: } | (Required) Payment/Transaction Confirmation Data. This is typically provided by the payment processor/acquirer. | Yes |
#### TransactionData Schema
(Conditional) Transaction details associated with the instruction. Conditionality: Transaction details are necessary for risk evaluation, fraud prevention, and payment authentication. To maximize transaction approval rates, it is highly recommended to provide all available data points, whether a field is marked as required, conditional, or optional.
| Name | Type | Description | Required |
| ---- | ---- | ----------- | -------- |
| TransactionData | | (Conditional) Transaction details associated with the instruction. Conditionality: Transaction details are necessary for risk evaluation, fraud prevention, and payment authentication. To maximize transaction approval rates, it is highly recommended to provide all available data points, whether a field is marked as required, conditional, or optional. | |
#### ClientReferenceId Schema
(Required) Transactional identifier provided by the Client.
| Name | Type | Description | Required |
| ---- | ---- | ----------- | -------- |
| ClientReferenceId | | (Required) Transactional identifier provided by the Client. | |
#### OrderDataV2 Schema
Order data. Present in EncryptedPurchaseData (decoded from
confirmationData.encryptedPurchaseData) for /v2/instructions/{id}/confirmation.
| Name | Type | Description | Required |
| ---- | ---- | ----------- | -------- |
| orderId | | (Optional) Unique identifier for the order. | No |
| policies | { **"refundPolicy"**: , **"disputePolicy"**: , **"shippingPolicy"**: , **"cancellationPolicy"**: , **"termsAndConditions"**: , **"discountAndPromotions"**: } | (Optional) Terms and conditions, and policies associated with the order. | No |
| products | | (Optional) Array of products in the order. | No |
| orderDate | | (Optional) Order date (UTC time in Epoch format). | No |
| orderStatus | | (Optional) Status of the order. | No |
| transactionAmount | { **"tax"**: , **"discount"**: , **"subTotal"**: , **"transactionAmount"**: , **"shippingAndHandling"**: , **"transactionCurrencyCode"**: } | The final amount that the customer needs to pay or paid. | No |
| expectedDeliveryDate | | (Optional) Expected delivery date for the order (UTC time in Epoch format). | No |
#### TokenReferenceData Schema
(Conditional) Token References representing a source token with-in a Token for Token usecase.
| Name | Type | Description | Required |
| ---- | ---- | ----------- | -------- |
| tokenId | | (Required)A Token Reference Identifier for a card that can be used for payments. This identifier is used to reference a specific tokenized card across various operations. | No |
| clientDeviceId | | (Conditional) Stable and unique device identification set by the wallet provider. By default, this field should be considered required. It is optional for the following presentation types: ECOM, MERCHANT_PRESENTED_QR, QR_CONSUMER_CLOUD, and RECEIVE_ONLY. An Enroll PAN request for a card on file will not have a device ID Format: Alphabetic, numeric, hyphens ( - ), and underscores ( _ ), e.g. spaces are not allowed; 24 characters Conditionality: Required for Token for Token use-case or deferred authentication flows. | No |
| tokenRequestorId | | (Conditional) Token Requestor Id, which identifies the owner of the token. Format: Number Conditionality: Required for Token for Token use-case or deferred authentication flows. | No |
| clientWalletAccountId | | (Conditional) Client-provided consumer ID that identifies the wallet account holder entity. Format: Alphabetic, numeric, hyphens ( - ), and underscores ( _ ), e.g. spaces are not allowed; maximum 24 characters. Conditionality: Required for Token for Token use-case or deferred authentication flows. | No |
| paymentAccountReference | | (Conditional) Payment Account Reference(a.k.a PAR). Conditionality: Required for Token for Token use-case or deferred authentication flows. | No |
#### DynamicDataType Schema
Type of Dynamic Data required in the payload
| Name | Type | Description | Required |
| ---- | ---- | ----------- | -------- |
| DynamicDataType |
**Available values:** "TAVV", "DAVV", "NONE" | Type of Dynamic Data required in the payload | |
#### TransactionAmount Schema
The final amount that the customer needs to pay or paid.
| Name | Type | Description | Required |
| ---- | ---- | ----------- | -------- |
| ~~tax~~ | | The total tax amount applied to the transaction.
**Deprecated** | No |
| discount | | The total discount amount applied to the transaction. | No |
| subTotal | | The total transaction amount before any taxes or discounts are applied. | No |
| transactionAmount | | The final amount that the customer needs to pay or paid. | Yes |
| shippingAndHandling | | The total shipping and handling cost(amount) applied to the transaction. | No |
| transactionCurrencyCode | | (Conditional) ISO 4217 currency code. Currency in which the transactionAmount, subTotal, tax, Shipping& handling or discount amount is expressed. Conditionality: Required when either transactionAmount, subTotal, tax, Shipping& handling or discount amount is present. | Yes |
#### MerchantData Schema
Merchant data.
| Name | Type | Description | Required |
| ---- | ---- | ----------- | -------- |
| merchantId | | Reference identifier of the Merchant | No |
| merchantName | | Name of the merchant | No |
| merchantCategoryCode | | Merchant Category Code (MCC) of the merchant | No |
#### ConfirmationDataV2 Schema
Confirmation data item for /v2/instructions/{id}/confirmation.
| Name | Type | Description | Required |
| ---- | ---- | ----------- | -------- |
| merchantData | { **"merchantId"**: , **"merchantUrl"**: , **"merchantName"**: } | Merchant data for confirmationData in /v2/instructions/{id}/confirmation. | No |
| shippingAddress | { **"zip"**: , **"city"**: , **"name"**: , **"line1"**: , **"line2"**: , **"line3"**: , **"state"**: , **"addressId"**: undefined (uuid), **"createTime"**: , **"countryCode"**: undefined (ISO 3166-1-alpha2), **"lastUsedTime"**: } & { **"deliveryContactDetails"**: { **"instructions"**: , **"contactFullName"**: , **"contactPhoneNumber"**: { **"countryCode"**: , **"phoneNumber"**: , **"numberIsVoiceOnly"**: }, **"contactEmailAddress"**: undefined (email) } } | Delivery Address & Contact details | No |
| transactionAmount | { **"tax"**: , **"discount"**: , **"subTotal"**: , **"transactionAmount"**: , **"shippingAndHandling"**: , **"transactionCurrencyCode"**: } | The final amount that the customer needs to pay or paid. | Yes |
| transactionStatus |
**Available values:** "APPROVED", "DECLINED", "CANCELLED" | (Required) Status of the attempted payment transaction. APPROVED - transaction succeeded; mandate should be set to COMPLETED. DECLINED - transaction failed; mandate stays ACTIVE, cryptogram can be re-requested. CANCELLED - if transactionStatus changes to CANCELLED, the agent will not be able to use that tokenized credential for transactions; instruction status remains ACTIVE and mandate stays ACTIVE. Agent must retrieve a new credential to continue.
*Enum:* `"APPROVED"`, `"DECLINED"`, `"CANCELLED"` | Yes |
| mandateReferenceData | | (Required) The single mandate this transaction confirmation applies to. Agent is the authoritative source for mandate status. Mandate must be in ACTIVE status in the system to be updated; otherwise the request is rejected. | Yes |
| transactionTimestamp | | (Required) Date and time of the transaction (UTC time in Epoch format). | Yes |
| encryptedPurchaseData | | (Optional) Contains the orderData and shippingData objects in an encrypted format, only to be decrypted at time of dispute. The rest of the fields within confirmationData are provided in the clear. URL-encoded JSON Web Encryption (JWE) compact serialization string, encrypted using the asymmetric public key provided during onboarding. Decrypted payload structure: [EncryptedPurchaseData](#/components/schemas/EncryptedPurchaseData). Decrypted JSON fields: `orderData`, `shippingData`. For encryption guidelines, refer to the Visa Developer Platform JWE/JWS Encryption Guide. | No |
| transactionReferenceId | | (Required) Unique identifier for the transaction. Links this confirmation to a credential retrieval. A given transactionReferenceId can only be confirmed once. | Yes |
#### UnitPrice Schema
The price of a single unit of the product
| Name | Type | Description | Required |
| ---- | ---- | ----------- | -------- |
| amount | | The price of a single unit. | No |
| currencyCode | | ISO 4217 currency code. Currency in which the unit price is expressed. | No |
#### TransactionRequestData Schema
| Name | Type | Description | Required |
| ---- | ---- | ----------- | -------- |
| client | { **"agentId"**: , **"authorization"**: , **"externalAppId"**: , **"relationshipId"**: , **"externalClientId"**: } | (Required) Contains Agent(TR) information and, in the case that an Agent Enabler(TR-TSP) is acting on behalf of an Agent(TR), the authorization and relationship information. | Yes |
| tokenId | | (Required)A Token Reference Identifier for a card that can be used for payments. This identifier is used to reference a specific tokenized card across various operations. | No |
| transactionData | | (Conditional) Transaction details associated with the instruction. Conditionality: Transaction details are necessary for risk evaluation, fraud prevention, and payment authentication. To maximize transaction approval rates, it is highly recommended to provide all available data points, whether a field is marked as required, conditional, or optional. | Yes |
| clientReferenceId | | (Required) Transactional identifier provided by the Client. | Yes |
#### PhoneNumber Schema
(Optional) Primary Phone Number. primary phone won't be considered as identity, unless present in consumerIdentities.
| Name | Type | Description | Required |
| ---- | ---- | ----------- | -------- |
| countryCode | | (Required) Phone number country code as defined by the International Telecommunication Union | Yes |
| phoneNumber | | (Required) Phone number without country code | Yes |
| numberIsVoiceOnly | | (Optional) Indicates that the phone number provided is not capable of receiving text messages. | No |
#### Email Schema
(Optional) Consumer-provided email address
| Name | Type | Description | Required |
| ---- | ---- | ----------- | -------- |
| Email | undefined (email) | (Optional) Consumer-provided email address | |
#### EncryptedInstruction Schema
Object containing the list of fields present in the encrypted instruction.
This represents the decrypted structure of the encryptedInstruction field in transactionData.
Present in: transactionData.encryptedInstruction of [TransactionItemExtended](#/components/schemas/TransactionItemExtended).
Note: this object is never transmitted as JSON on the wire. It is the plaintext obtained after
URL-decoding and JWE-decrypting that string.
| Name | Type | Description | Required |
| ---- | ---- | ----------- | -------- |
| mandates | | (Required) Array of mandates. | Yes |
| products | | (Optional) A list of products being purchased from the merchant. Each product can have its own productId, product information, cost, quantity, description, SKU, DeliveryMethod, ShippingAddress etc. | No |
| attachments | | (Optional) List of images of the cart, payment confirmation, proof of disclosure and acceptance for audit and dispute management. | No |
| merchantUrl | | (Required) Full URL of the merchant. | Yes |
| merchantName | | (Required) Merchant name. | Yes |
| billingAddress | { **"zip"**: , **"city"**: , **"name"**: , **"line1"**: , **"line2"**: , **"line3"**: , **"state"**: , **"addressId"**: undefined (uuid), **"createTime"**: , **"countryCode"**: undefined (ISO 3166-1-alpha2), **"lastUsedTime"**: } | Address data. | No |
| consumerPrompt | | (Optional) A summary or condensed version of user prompts that leads to the purchase. | No |
| merchantDomain | | (Optional) Merchant's top-level domain. | No |
| merchantOrderId | | (Optional) Digital Payment Application generated order/invoice number corresponding to a Consumer purchase. | No |
| shippingAddress | { **"zip"**: , **"city"**: , **"name"**: , **"line1"**: , **"line2"**: , **"line3"**: , **"state"**: , **"addressId"**: undefined (uuid), **"createTime"**: , **"countryCode"**: undefined (ISO 3166-1-alpha2), **"lastUsedTime"**: } & { **"deliveryContactDetails"**: { **"instructions"**: , **"contactFullName"**: , **"contactPhoneNumber"**: { **"countryCode"**: , **"phoneNumber"**: , **"numberIsVoiceOnly"**: }, **"contactEmailAddress"**: undefined (email) } } | Delivery Address & Contact details | No |
| transactionAmount | { **"tax"**: , **"discount"**: , **"subTotal"**: , **"transactionAmount"**: , **"shippingAndHandling"**: , **"transactionCurrencyCode"**: } | The final amount that the customer needs to pay or paid. | Yes |
#### AutofillTransactionData Schema
| Name | Type | Description | Required |
| ---- | ---- | ----------- | -------- |
| client | { **"agentId"**: , **"authorization"**: , **"externalAppId"**: , **"relationshipId"**: , **"externalClientId"**: } | (Required) Contains Agent(TR) information and, in the case that an Agent Enabler(TR-TSP) is acting on behalf of an Agent(TR), the authorization and relationship information. | Yes |
| tokenId | | (Required)A Token Reference Identifier for a card that can be used for payments. This identifier is used to reference a specific tokenized card across various operations. | Yes |
| consumer | { **"consumerId"**: , **"countryCode"**: undefined (ISO 3166-1 alpha-2), **"languageCode"**: , **"consumerIdentities"**: } | (Required) A unique identifier for the Consumer within the Client's system. If enrollment is being performed by an agent enabler, this consumerId will be associated with the agent and must be identical for each card being enrolled for the same consumer. | No |
| consumerId | | (Required) Reference identifier of the Consumer. | No |
| appInstance | { **"ipAddress"**: , **"userAgent"**: , **"deviceData"**: { **"type"**: , **"brand"**: , **"model"**: , **"manufacturer"**: }, **"countryCode"**: undefined (ISO 3166-1-alpha2), **"clientDeviceId"**: , **"applicationName"**: } | (Required) Device and Application instance data. | Yes |
| assuranceData | | (Required) FIDO Attestation/Assertion Data. | Yes |
| transactionData | { **"merchantUrl"**: , **"merchantName"**: , **"transactionAmount"**: { **"tax"**: , **"discount"**: , **"subTotal"**: , **"transactionAmount"**: , **"shippingAndHandling"**: , **"transactionCurrencyCode"**: }, **"transactionReferenceId"**: } | Transaction Details | Yes |
| clientReferenceId | | (Required) Transactional identifier provided by the Client. | Yes |
#### ConfirmationRequestDataV2 Schema
Request schema for /v2/instructions/{id}/confirmation.
| Name | Type | Description | Required |
| ---- | ---- | ----------- | -------- |
| client | { **"agent"**: { **"agentId"**: , **"agentSignature"**: { **"signature"**: , **"signatureInput"**: { **"alg"**:
**Available values:** "Ed25519", "RS256", "ES256", **"tag"**:
**Available values:** "credential-request", "confirmation-request", **"keyId"**: , **"nonce"**: , **"created"**: , **"expires"**: } } }, **"authorization"**: , **"externalAppId"**: , **"relationshipId"**: , **"externalClientId"**: } | Client with Agent(TR) information and, in the case that an Agent Enabler(TR-TSP) is acting on behalf of an Agent(TR), the authorization and relationship information. | Yes |
| confirmationData | | (Required) Array of transaction confirmation entries. Minimum 1 entry. | Yes |
| clientReferenceId | | (Required) Transactional identifier provided by the Client. | Yes |
| instructionCompleted | | (Optional) Default state of instruction is ACTIVE. If instructionCompleted is set to TRUE, then instruction is marked COMPLETED. If set to true, this overrides the related mandateReferenceData status fields, preventing further credential retrievals. | No |
#### Attachment Schema
(Optional) List of images of the cart, products, payment confirmation, user overrides etc for audit & dispute
management.
| Name | Type | Description | Required |
| ---- | ---- | ----------- | -------- |
| name | | (Required) Type/Name of the image. For example: product, payment confirmation, cart etc. | No |
| content | | (Required) Image(Binary) in Base64 encoded with no padding | No |
| contentType | | (Required) Content Type of the image. For example: image/jpeg, image/png, application/pdf etc. | No |
#### ConsentData Schema
(Conditional) An array of consumer consents for the use of their data for personalization and platform functionality, ensuring compliance with Visa's privacy and regulatory requirements. Conditionality: This field is required when the consumer has not previously provided consent within VIC or when updated consent is needed due to changes in privacy requirements. Note: If this object is omitted, it will be assumed that the user has accepted \"all\" Visa Terms & Conditions as part of a partner‑orchestrated flow.
| Name | Type | Description | Required |
| ---- | ---- | ----------- | -------- |
| ConsentData | | (Conditional) An array of consumer consents for the use of their data for personalization and platform functionality, ensuring compliance with Visa's privacy and regulatory requirements. Conditionality: This field is required when the consumer has not previously provided consent within VIC or when updated consent is needed due to changes in privacy requirements. Note: If this object is omitted, it will be assumed that the user has accepted \"all\" Visa Terms & Conditions as part of a partner‑orchestrated flow. | |
#### DynamicDataTypeEmv Schema
Type of Dynamic Data required in the payload. Default value is CARD_APPLICATION_CRYPTOGRAM_SHORT_FORM.
| Name | Type | Description | Required |
| ---- | ---- | ----------- | -------- |
| DynamicDataTypeEmv |
**Available values:** "CARD_APPLICATION_CRYPTOGRAM_SHORT_FORM", "DYNAMIC_CARD_SECURITY_CODE", "NONE",
**Default:** CARD_APPLICATION_CRYPTOGRAM_SHORT_FORM | Type of Dynamic Data required in the payload. Default value is CARD_APPLICATION_CRYPTOGRAM_SHORT_FORM. | |
#### PaymentConfirmationData Schema
(Required) Payment/Transaction Confirmation Data. This is typically provided by the payment processor/acquirer.
| Name | Type | Description | Required |
| ---- | ---- | ----------- | -------- |
| responseCode | | 2 Digit Response code from the payment processor. | No |
| cardEntryMode |
**Available values:** "EMV", "CONTACTLESS", "MANUAL", "ECOMMERCE", "WALLET" | Method used to enter card details.
*Enum:* `"EMV"`, `"CONTACTLESS"`, `"MANUAL"`, `"ECOMMERCE"`, `"WALLET"` | No |
| dynamicDataId | | A unique reference ID that represents the dynamic data associated with a transaction. | No |
| transactionType |
**Available values:** "PURCHASE", "AUTHORIZATION", "CAPTURE", "REFUND", "REVERSAL", "VERIFICATION", "CHARGEBACK", "FRAUD" | Type of payment transaction.
*Enum:* `"PURCHASE"`, `"AUTHORIZATION"`, `"CAPTURE"`, `"REFUND"`, `"REVERSAL"`, `"VERIFICATION"`, `"CHARGEBACK"`, `"FRAUD"` | Yes |
| authorizationCode | | Authorization code for approved transactions. | No |
| transactionAmount | { **"tax"**: , **"discount"**: , **"subTotal"**: , **"transactionAmount"**: , **"shippingAndHandling"**: , **"transactionCurrencyCode"**: } | The final amount that the customer needs to pay or paid. | No |
| transactionStatus |
**Available values:** "APPROVED", "DECLINED", "PENDING", "ERROR", "CANCELLED" | Status of the payment transaction.
*Enum:* `"APPROVED"`, `"DECLINED"`, `"PENDING"`, `"ERROR"`, `"CANCELLED"` | Yes |
| transactionTimestamp | | Date and time of the transaction (UTC time in Epoch format). | Yes |
| cardVerificationResult | | 2 Digit Card Verification Value result. | No |
| systemTraceAuditNumber | | Audit number assigned by the payment network. | No |
| acquirerReferenceNumber | | Reference number assigned by the acquirer. | No |
| retrievalReferenceNumber | | Unique reference number for the transaction. | No |
| addressVerificationResult | | 2 Digit Address Verification Service result. | No |
#### MethodResults Schema
Authentication/Verification Method Attributes associated with Visa Passkey(FIDO2) Authentication. Clients should silently disregard any unrecognized fields in the JSON object.
| Name | Type | Description | Required |
| ---- | ---- | ----------- | -------- |
| error | { **"reason"**: , **"status"**: , **"message"**: , **"errorDetail"**: } | | No |
| identifier | | (Required) This is a distinctive and non-transparent identifier provided by VISA for correlation purposes in the previous, related API. Field Mapping: - When authenticationMethodType is 'FIDO2'. - On Success: FidoResponse.identifier - On Error: AuthContext.identifier | Yes |
| dfpSessionId | | (Required) Device Fingerprinting Session identifier. | Yes |
| fidoAssertionData | { **"code"**: } | (Conditional) Visa Passkey Authentication Result Data Conditionality: Required when the authenticationMethodType is FIDO2 and the performed getDeviceAttestationOptions[action] is 'AUTHENTICATION' | No |
| fidoAttestationData | { **"code"**: } | (Conditional) Visa Passkey Attestation Result Data Conditionality: Required when the authenticationMethodType is FIDO2 and the performed getDeviceAttestationOptions[action] is 'REGISTER' | No |
#### VerificationData Schema
| Name | Type | Description | Required |
| ---- | ---- | ----------- | -------- |
| methodResults | { **"error"**: { **"reason"**: , **"status"**: , **"message"**: , **"errorDetail"**: }, **"identifier"**: , **"dfpSessionId"**: , **"fidoAssertionData"**: { **"code"**: }, **"fidoAttestationData"**: { **"code"**: } } | Authentication/Verification Method Attributes associated with Visa Passkey(FIDO2) Authentication. Clients should silently disregard any unrecognized fields in the JSON object. | No |
| additionalData | | (Optional) Data collected during the verification process | No |
| verificationType |
**Available values:** "CARDHOLDER", "DEVICE" | Type of the verification data. Default value is CARDHOLDER
*Enum:* `"CARDHOLDER"`, `"DEVICE"` | No |
| verificationEntity |
**Available values:** "10" | (Required) Entity performing the verification 10 - VISA (Default) 20 - WALLET_PROVIDER 30 - AGENT 40 - AGENT_ENABLER
*Enum:* `"10"` | No |
| verificationEvents | | (Optional) Event where the verification occurred 01 - Payment transaction 02 - Add card/Card enrollment 03 - Profile access 04 - Account verification | No |
| verificationMethod |
**Available values:** "02", "04", "21", "22", "23" | (Required) Method of the verification 02 - App-based authentication 04 - One-time passcode 21 - Visa Token Service step-up: Device binding 22 - Visa Token Service step-up: Cardholder verification 23 - FIDO2
*Enum:* `"02"`, `"04"`, `"21"`, `"22"`, `"23"` | Yes |
| verificationResults |
**Available values:** "01", "02", "03", "04", "21" | (Required) Result of the verification 01 - Verified 02 - Not Verified 03 - Not performed 04 - Not required 21 - Not allowed
*Enum:* `"01"`, `"02"`, `"03"`, `"04"`, `"21"` | Yes |
| verificationTimestamp | | (Required) Date and time the verification occurred. UTC time in Unix epoch format | Yes |
#### BusinessErrorDetail Schema
| Name | Type | Description | Required |
| ---- | ---- | ----------- | -------- |
| code |
**Available values:** "CURRENCY_MISMATCH", "THRESHOLD_EXCEEDED", "AUTHORIZATION_EXPIRED", "PROCESSING_ERROR" | Specific error code for the detail.
*Enum:* `"CURRENCY_MISMATCH"`, `"THRESHOLD_EXCEEDED"`, `"AUTHORIZATION_EXPIRED"`, `"PROCESSING_ERROR"` | Yes |
| field | | Field or parameter related to the error as json-path(e.g., currency, amount) | No |
| source | | Service where the error originated(VTS, VIC etc). | No |
| message | | Detailed message for this error. | Yes |
#### PersonalizationSignalsData Schema
| Name | Type | Description | Required |
| ---- | ---- | ----------- | -------- |
| client | { **"agentId"**: , **"authorization"**: , **"externalAppId"**: , **"relationshipId"**: , **"externalClientId"**: } | (Required) Contains Agent(TR) information and, in the case that an Agent Enabler(TR-TSP) is acting on behalf of an Agent(TR), the authorization and relationship information. | Yes |
| filters | { **"signals"**: } | (Optional) Filters to apply to the signals request. | No |
| consumerId | | (Required) Unique identifier for the consumer. | Yes |
| clientReferenceId | | (Required) Transactional identifier provided by the Client. | Yes |
#### ErrorDetail Schema
| Name | Type | Description | Required |
| ---- | ---- | ----------- | -------- |
| reason | | Error reason | No |
| message | | Error message. | No |
#### VisaPasskeyAuthResult Schema
Authentication/Verification Method Attributes associated with Visa Passkey(FIDO2) Authentication. Clients should silently disregard any unrecognized fields in the JSON object.
| Name | Type | Description | Required |
| ---- | ---- | ----------- | -------- |
| error | { **"reason"**: , **"status"**: , **"message"**: , **"errorDetail"**: } | | No |
| identifier | | (Required) This is a distinctive and non-transparent identifier provided by VISA for correlation purposes in the previous, related API. Field Mapping: - When authenticationMethodType is 'FIDO2'. - On Success: FidoResponse.identifier - On Error: AuthContext.identifier | Yes |
| dfpSessionId | | (Required) Device Fingerprinting Session identifier. | Yes |
| fidoAssertionData | { **"code"**: } | (Conditional) Visa Passkey Authentication Result Data Conditionality: Required when the authenticationMethodType is FIDO2 and the performed getDeviceAttestationOptions[action] is 'AUTHENTICATION' | No |
| fidoAttestationData | { **"code"**: } | (Conditional) Visa Passkey Attestation Result Data Conditionality: Required when the authenticationMethodType is FIDO2 and the performed getDeviceAttestationOptions[action] is 'REGISTER' | No |
#### BaseTransactionDetail Schema
Transaction Details
| Name | Type | Description | Required |
| ---- | ---- | ----------- | -------- |
| merchantUrl | | (Required) Merchant URL. | Yes |
| merchantName | | (Required) Merchant name. Required for the VISA system to facilitate authentication. | Yes |
| transactionAmount | { **"tax"**: , **"discount"**: , **"subTotal"**: , **"transactionAmount"**: , **"shippingAndHandling"**: , **"transactionCurrencyCode"**: } | The final amount that the customer needs to pay or paid. | Yes |
| transactionReferenceId | | (Required) A distinct identifier for this order/line item. This ID will act as a reference to connect this line item with payment details, payment transactions, and confirmation events. | Yes |
#### Client Schema
(Required) Contains Agent(TR) information and, in the case that an Agent Enabler(TR-TSP) is acting on behalf of an Agent(TR), the authorization and relationship information.
| Name | Type | Description | Required |
| ---- | ---- | ----------- | -------- |
| agentId | | (Optional) Token Requestor Identifier (TRID) that uniquely identifies the client/agent. This is an 11-digit numeric identifier assigned by Visa. | No |
| authorization | | (Conditional) The API Key of the requesting entity, which—when used together with the relationship—confirms that the entity is authorized to act on behalf of the Agent(TR). Conditionality: Required when the Client is a Agent Enabler(TR-TSP) acting on behalf-of an Agent(TR). | No |
| externalAppId | | (Required) External Application Profile Identifier assigned to an Agent(TR) by Visa Token Service/Card-Network | Yes |
| relationshipId | | (Conditional) The ID that specifies the relationship between a token requestor and the caller of this API—namely, an Agent Enabler(TR-TSP) with whom the token requestor is associated. This relationship is established during onboarding; for further details, please contact your Visa representative. Conditionality: Required when the Client is a Agent Enabler(TR-TSP) acting on behalf-of an Agent(TR). | No |
| externalClientId | | (Required) An external client Id assigned to an Agent(TR) or to an Agent Enabler(TR-TSP) acting on behalf-of an Agent(TR) by Visa Token Service/Card-Network. | Yes |
#### ShippingData Schema
Shipping & Tracking Information.
| Name | Type | Description | Required |
| ---- | ---- | ----------- | -------- |
| carrier | | Shipping carrier or provider | No |
| trackingId | | Tracking ID for the shipment | No |
| shippingMethod | | Method of shipping (e.g., Standard, Express) | No |
| shippingAddress | { **"zip"**: , **"city"**: , **"name"**: , **"line1"**: , **"line2"**: , **"line3"**: , **"state"**: , **"addressId"**: undefined (uuid), **"createTime"**: , **"countryCode"**: undefined (ISO 3166-1-alpha2), **"lastUsedTime"**: } & { **"deliveryContactDetails"**: { **"instructions"**: , **"contactFullName"**: , **"contactPhoneNumber"**: { **"countryCode"**: , **"phoneNumber"**: , **"numberIsVoiceOnly"**: }, **"contactEmailAddress"**: undefined (email) } } | Delivery Address & Contact details | No |
#### DynamicData Schema
Dynamic data, generated using the dynamicDataType preference indicated in paymentOptions
| Name | Type | Description | Required |
| ---- | ---- | ----------- | -------- |
| dynamicDataType |
**Available values:** "TAVV", "DAVV", "NONE" | Type of Dynamic Data required in the payload
*Enum:* `"TAVV"`, `"DAVV"`, `"NONE"` | No |
| dynamicDataValue | | Value of the dynamic data Conditionality: Required when the value of dynamicDataType is not set to NONE | No |
| dynamicDataExpiration | | UTC time in Unix epoch format. Date and time at which the Dynamic Data expires | No |
#### AppInstance Schema
(Required) Device and Application instance data.
| Name | Type | Description | Required |
| ---- | ---- | ----------- | -------- |
| ipAddress | | IP address of the consumer's device. Supports both IPv4 (e.g. 192.168.1.100) and IPv6 (e.g. 2001:db8::1) formats. | Yes |
| userAgent | | (Conditional) Base64 Encoded userAgent string of the connecting client application, with no padding. User agent string of the connecting client application Conditionality: • Required for browsers • Optional for non-browsers | No |
| deviceData | { **"type"**: , **"brand"**: , **"model"**: , **"manufacturer"**: } | Device data. | Yes |
| countryCode | undefined (ISO 3166-1-alpha2) | ISO 3166-1 alpha-2 country code. The country where the Consumer is accessing the service from | No |
| clientDeviceId | | (Conditional) Unique device identifier of the consumer's device. Conditionality: Required when the token is bound to the device. Example Autofill, CTF etc. | No |
| applicationName | | Name of the connecting client application | Yes |
#### EncryptedPurchaseData Schema
Decoded contents of confirmationData.encryptedPurchaseData for
/v2/instructions/{id}/confirmation, intended to be opened only at the time of a dispute.
Present in: confirmationData.encryptedPurchaseData of [ConfirmationDataV2](#/components/schemas/ConfirmationDataV2).
Note: this object is never transmitted as JSON on the wire. It is the decoded plaintext
obtained after JWE decryption.
| Name | Type | Description | Required |
| ---- | ---- | ----------- | -------- |
| orderData | { **"orderId"**: , **"policies"**: { **"refundPolicy"**: , **"disputePolicy"**: , **"shippingPolicy"**: , **"cancellationPolicy"**: , **"termsAndConditions"**: , **"discountAndPromotions"**: }, **"products"**: , **"orderDate"**: , **"orderStatus"**: , **"transactionAmount"**: { **"tax"**: , **"discount"**: , **"subTotal"**: , **"transactionAmount"**: , **"shippingAndHandling"**: , **"transactionCurrencyCode"**: }, **"expectedDeliveryDate"**: } | Order data. Present in EncryptedPurchaseData (decoded from confirmationData.encryptedPurchaseData) for /v2/instructions/{id}/confirmation. | No |
| shippingData | { **"carrier"**: , **"trackingId"**: , **"shippingMethod"**: } | Shipping and tracking data. Present in EncryptedPurchaseData (decoded from confirmationData.encryptedPurchaseData) for /v2/instructions/{id}/confirmation. | No |
#### CredentialsSecuredPayload Schema
Decoded secured payload for /v2/credentials-for-instruction API.
This structure represents the decrypted content from either signedPayload or encryptedSignedPayload.
Present in: payload.signedPayload (JWS) and payload.encryptedSignedPayload (JWE) of [CredentialsPayload](#/components/schemas/CredentialsPayload).
Note: this object is never transmitted as JSON on the wire. It is the decoded plaintext obtained after
verifying the JWS signature, or after JWE decryption followed by JWS signature verification.
| Name | Type | Description | Required |
| ---- | ---- | ----------- | -------- |
| token | { **"paymentToken"**: , **"tokenExpirationYear"**: , **"tokenExpirationMonth"**: } & { **"eci"**: } | Extended payment token structure for v1/credentials API. Includes eci field in addition to base PaymentToken fields. | Yes |
| dynamicData | { **"dynamicDataType"**:
**Available values:** "CARD_APPLICATION_CRYPTOGRAM_SHORT_FORM", "DYNAMIC_CARD_SECURITY_CODE", "NONE",
**Default:** CARD_APPLICATION_CRYPTOGRAM_SHORT_FORM, **"dynamicDataValue"**: , **"dynamicDataExpiration"**: , **"transactionReferenceId"**: } | Dynamic data, generated using the dynamicDataType preference indicated in paymentOptions | Yes |
| authorization | | (Conditional) First-party authorization token/code: an opaque first-party token issued and recognized by the system that issued it. The content and structure of these tokens/codes are out of scope of the specification. Refer to client integration guide for usage details. Condition: When additional consumer authentication or action is required. | Yes |
| clientReferenceID | | (Conditional) Transaction ID for the checkout session. This value is present if created by the Agent and shared with all parties. | Yes |
#### CompositeTransactionDataExtendedV2 Schema
Request schema for /v2/credentials-for-instruction API with agent
| Name | Type | Description | Required |
| ---- | ---- | ----------- | -------- |
| client | { **"agent"**: { **"agentId"**: , **"agentSignature"**: { **"signature"**: , **"signatureInput"**: { **"alg"**:
**Available values:** "Ed25519", "RS256", "ES256", **"tag"**:
**Available values:** "credential-request", "confirmation-request", **"keyId"**: , **"nonce"**: , **"created"**: , **"expires"**: } } }, **"authorization"**: , **"externalAppId"**: , **"relationshipId"**: , **"externalClientId"**: } | Client with Agent(TR) information and, in the case that an Agent Enabler(TR-TSP) is acting on behalf of an Agent(TR), the authorization and relationship information. | Yes |
| tokenId | | (Required)A Token Reference Identifier for a card that can be used for payments. This identifier is used to reference a specific tokenized card across various operations. | Yes |
| consumer | { **"consumerId"**: , **"countryCode"**: undefined (ISO 3166-1 alpha-2), **"languageCode"**: , **"consumerIdentities"**: } | (Required) A unique identifier for the Consumer within the Client's system. If enrollment is being performed by an agent enabler, this consumerId will be associated with the agent and must be identical for each card being enrolled for the same consumer. | Yes |
| mandates | | (Required) Consumer Set Transaction Mandates. Condition: Required when a purchase intent is initiated with a mandate by consumer. | Yes |
| appInstance | { **"ipAddress"**: , **"userAgent"**: , **"deviceData"**: { **"type"**: , **"brand"**: , **"model"**: , **"manufacturer"**: }, **"countryCode"**: undefined (ISO 3166-1-alpha2), **"clientDeviceId"**: , **"applicationName"**: } | (Required) Device and Application instance data. | Yes |
| purchaseType |
**Available values:** "PURCHASE_HITL", "PURCHASE_AUTONOMOUS", "PURCHASE_RECURRING" | (Required) Transaction type.
*Enum:* `"PURCHASE_HITL"`, `"PURCHASE_AUTONOMOUS"`, `"PURCHASE_RECURRING"` | Yes |
| assuranceData | | (Required) FIDO Attestation/Assertion Data. | Yes |
| transactionData | { **"merchantUrl"**: , **"merchantName"**: , **"transactionAmount"**: { **"tax"**: , **"discount"**: , **"subTotal"**: , **"transactionAmount"**: , **"shippingAndHandling"**: , **"transactionCurrencyCode"**: }, **"transactionReferenceId"**: } & { **"merchantId"**: , **"billingAddress"**: { **"zip"**: , **"city"**: , **"name"**: , **"line1"**: , **"line2"**: , **"line3"**: , **"state"**: , **"addressId"**: undefined (uuid), **"createTime"**: , **"countryCode"**: undefined (ISO 3166-1-alpha2), **"lastUsedTime"**: }, **"deliveryMethod"**:
**Available values:** "NO_DELIVERY", "ADDRESS_BILLING", "ADDRESS_ON_FILE", "ADDRESS_OTHER", "PICKUP", "ELECTRONIC", **"merchantDomain"**: , **"paymentOptions"**: { **"dynamicDataType"**:
**Available values:** "CARD_APPLICATION_CRYPTOGRAM_SHORT_FORM", "DYNAMIC_CARD_SECURITY_CODE", "NONE",
**Default:** CARD_APPLICATION_CRYPTOGRAM_SHORT_FORM, **"encryptionOverride"**: }, **"shippingAddress"**: { **"zip"**: , **"city"**: , **"name"**: , **"line1"**: , **"line2"**: , **"line3"**: , **"state"**: , **"addressId"**: undefined (uuid), **"createTime"**: , **"countryCode"**: undefined (ISO 3166-1-alpha2), **"lastUsedTime"**: } & { **"deliveryContactDetails"**: { **"instructions"**: , **"contactFullName"**: , **"contactPhoneNumber"**: { **"countryCode"**: , **"phoneNumber"**: , **"numberIsVoiceOnly"**: }, **"contactEmailAddress"**: undefined (email) } } } & { **"policies"**: { **"refundPolicy"**: , **"disputePolicy"**: , **"shippingPolicy"**: , **"cancellationPolicy"**: , **"termsAndConditions"**: , **"discountAndPromotions"**: }, **"encryptedInstruction"**: , **"mandateReferenceData"**: , **"transactionReferenceIdType"**:
**Available values:** "ENCRYPTED" } & { **"mandateReferenceData"**: } | (Required) Transaction data of the purchases being made. | Yes |
| clientReferenceId | | (Required) Transactional identifier provided by the Client. | Yes |
#### ConsumerIdOptional Schema
(Optional) Reference identifier of the Consumer.
| Name | Type | Description | Required |
| ---- | ---- | ----------- | -------- |
| ConsumerIdOptional | | (Optional) Reference identifier of the Consumer. | |
#### MerchantDataV2 Schema
Merchant data for confirmationData in /v2/instructions/{id}/confirmation.
| Name | Type | Description | Required |
| ---- | ---- | ----------- | -------- |
| merchantId | | (Optional) Reference identifier of the merchant. | No |
| merchantUrl | | (Optional) Full URL of the merchant. | No |
| merchantName | | (Optional) Name of the merchant. | No |
#### PaymentOptions Schema
(Optional) Payment data type and expiry preferences requested by the DPA.
| Name | Type | Description | Required |
| ---- | ---- | ----------- | -------- |
| dynamicDataType |
**Available values:** "TAVV", "DAVV", "NONE" | Type of Dynamic Data required in the payload
*Enum:* `"TAVV"`, `"DAVV"`, `"NONE"` | No |
| dpaDynamicDataTtlMinutes | | (Optional) Requested "Time to Live" (expiry period) of the Dynamic Data, specified in minutes. | No |
#### BaseEnrollmentResponse Schema
| Name | Type | Description | Required |
| ---- | ---- | ----------- | -------- |
| clientReferenceId | | (Required) Transactional identifier provided by the Client. | Yes |
#### BaseInstructionResponse Schema
| Name | Type | Description | Required |
| ---- | ---- | ----------- | -------- |
| instructionId | | (Required) Unique instruction identifier. | Yes |
| clientReferenceId | | (Required) Transactional identifier provided by the Client. | Yes |
#### BusinessError Schema
| Name | Type | Description | Required |
| ---- | ---- | ----------- | -------- |
| code |
**Available values:** "DECLINED", "EXPIRED" | Unique error code (e.g., DECLINED, AUTHORIZATION_EXPIRED).
*Enum:* `"DECLINED"`, `"EXPIRED"` | Yes |
| details | | | No |
| message | | Human-readable description of the error/reason. | Yes |
| category |
**Available values:** "VALIDATION_ERROR", "AUTHORIZATION_ERROR", "PROCESSING_ERROR", "LIMIT_ERROR" | High-level classification of the error/reason.
*Enum:* `"VALIDATION_ERROR"`, `"AUTHORIZATION_ERROR"`, `"PROCESSING_ERROR"`, `"LIMIT_ERROR"` | Yes |
| correlationId | | ID for tracing the request across systems. | No |
#### MandateExtended Schema
Extended mandate for /v2/credentials-for-instruction API with additional repository fields
| Name | Type | Description | Required |
| ---- | ---- | ----------- | -------- |
| quantity | | (Conditional) Quantity of the product.
*Example:* `"10"` | No |
| mandateId | | (Required) Mandate reference, that is, a unique identifier of the mandate assigned by the client. This must be provided in any future purchase request(s) linked to this mandate. | Yes |
| declineThreshold | { **"amount"**: , **"currencyCode"**: } | (Required) Transaction Decline Threshold amount | Yes |
| merchantCategory | | (Optional) Comma-separated string containing one or more merchant categories at which purchases associated with the mandate will occur. | No |
| effectiveUntilTime | | (Required) Timestamp indicating until when purchases associated with the mandate can occur. UTC time in Unix epoch format. | Yes |
| recurringFrequency |
**Available values:** "WEEKLY", "MONTHLY", "YEARLY" | (Conditional) Frequency of the transaction, specifying how often the transaction occurs. Condition: If the mandate contains a recurring instruction, a recurring frequency must be provided, and purchaseType = PURCHASE_RECURRING
*Enum:* `"WEEKLY"`, `"MONTHLY"`, `"YEARLY"` | No |
| preferredMerchantName | | (Optional) Comma-separated string containing one or more preferred merchants at which purchases associated with the mandate will occur. For example, the allowed_payees as per VI. | No |
#### FidoAttestationData Schema
(Conditional) Visa Passkey Attestation Result Data Conditionality: Required when the authenticationMethodType is FIDO2
and the performed getDeviceAttestationOptions[action] is 'REGISTER'
| Name | Type | Description | Required |
| ---- | ---- | ----------- | -------- |
| code | | (Required) An auth_code returned by Visa as part of the Visa Passkey Attestation Flow. Field Mapping: - FidoResponse.fidoBlob | Yes |
#### ClientWithAgent Schema
Client with Agent(TR) information and, in the case that an Agent Enabler(TR-TSP) is acting on behalf of an Agent(TR), the authorization and relationship information.
| Name | Type | Description | Required |
| ---- | ---- | ----------- | -------- |
| agent | { **"agentId"**: , **"agentSignature"**: { **"signature"**: , **"signatureInput"**: { **"alg"**:
**Available values:** "Ed25519", "RS256", "ES256", **"tag"**:
**Available values:** "credential-request", "confirmation-request", **"keyId"**: , **"nonce"**: , **"created"**: , **"expires"**: } } } | Identifies the Agent Provider. | Yes |
| authorization | | (Conditional) The API Key of the requesting entity, which when used together with the relationship identifier, confirms that the entity is authorized to act on behalf of the Agent or Wallet Provider (TR). Conditionality: Required when the external client is a TR-TSP acting on behalf of a TR. | No |
| externalAppId | | (Required) External application profile identifier assigned by Visa Token Service/Card-Network | Yes |
| relationshipId | | (Conditional) The identifier that specifies the relationship between a token requestor and the caller of this API—namely, a TR-TSP with whom the token requestor is associated. This relationship is established during onboarding. Conditionality: Required when the external client is a TR-TSP acting on behalf of a TR. | No |
| externalClientId | | (Required) External client identifier assigned by Visa Token Service/Card-Network | Yes |
#### MethodAttributes Schema
Authentication/Verification Method Attributes
| Name | Type | Description | Required |
| ---- | ---- | ----------- | -------- |
| threeDsData | | Represents a free-form JSON Object data structure. | No |
#### ConfirmationResponseV2 Schema
Response for /v2/instructions/{id}/confirmation.
| Name | Type | Description | Required |
| ---- | ---- | ----------- | -------- |
| status |
**Available values:** "ACTIVE", "COMPLETED" | (Required) Current instruction status after confirmation. ACTIVE - Instruction remains active; further credential retrievals are permitted. COMPLETED - Instruction marked complete (instructionCompleted=true); no further retrievals permitted. Note: CANCELLED and EXPIRED are not returned here — the Confirmation API can only be called when the instruction is ACTIVE in the system; a CANCELLED or EXPIRED instruction returns an error instead.
*Enum:* `"ACTIVE"`, `"COMPLETED"` | Yes |
| clientReferenceId | | (Required) Transactional identifier provided by the Client. | Yes |
#### InstructionPendingStatus Schema
Purchase Status. PENDING - Purchase is pending further checks or authentication. EXPIRED - Purchase Instruction has
expired. CANCELLED - Purchase Instruction has been cancelled. ACTIVE - Instruction has been created. Purchase can be
initiated. INPROGRESS - Instruction is in progress. Can't be updated/cancelled at this moment. COMPLETED - Purchase has
been completed. SecurePayload is included in the response.
| Name | Type | Description | Required |
| ---- | ---- | ----------- | -------- |
| InstructionPendingStatus |
**Available values:** "PENDING", "INPROGRESS" | Purchase Status. PENDING - Purchase is pending further checks or authentication. EXPIRED - Purchase Instruction has expired. CANCELLED - Purchase Instruction has been cancelled. ACTIVE - Instruction has been created. Purchase can be initiated. INPROGRESS - Instruction is in progress. Can't be updated/cancelled at this moment. COMPLETED - Purchase has been completed. SecurePayload is included in the response. | |
#### FidoAssertionData Schema
(Conditional) Visa Passkey Authentication Result Data Conditionality: Required when the authenticationMethodType is
FIDO2 and the performed getDeviceAttestationOptions[action] is 'AUTHENTICATION'
| Name | Type | Description | Required |
| ---- | ---- | ----------- | -------- |
| code | | (Required) An auth_code returned by Visa as part of the Visa Passkey Flow. Field Mapping: - FidoResponse.fidoBlob | Yes |
#### CardPendingEvent Schema
Card pending event.
| Name | Type | Description | Required |
| ---- | ---- | ----------- | -------- |
| CardPendingEvent |
**Available values:** "PENDING_CARDHOLDER_AUTHENTICATION" | Card pending event. | |
#### ConsumerIdentity Schema
(Conditional) Primary verifiable Consumer Identity within a Profile (e.g. an email address or a mobile phone number)
Conditionality: Required during new enrollment
| Name | Type | Description | Required |
| ---- | ---- | ----------- | -------- |
| identityType |
**Available values:** "EMAIL_ADDRESS", "MOBILE_PHONE_NUMBER", "USER_NAME" | (Required) Type of Consumer Identity transmitted or collected
*Enum:* `"EMAIL_ADDRESS"`, `"MOBILE_PHONE_NUMBER"`, `"USER_NAME"` | Yes |
| identityValue | | (Required) Consumer Identity value that corresponds to the Consumer Identity Type | Yes |
| identityProvider |
**Available values:** "VISA", "PARTNER" | (Optional) Identity provider of the Consumer Identity. The default value is Partner
*Enum:* `"VISA"`, `"PARTNER"` | No |
| identityProviderUrl | | (Optional) Domain Name/URL(iss) of the Identity provider of the Consumer Identity. | No |
#### EnrollmentData Schema
| Name | Type | Description | Required |
| ---- | ---- | ----------- | -------- |
| client | { **"agentId"**: , **"authorization"**: , **"externalAppId"**: , **"relationshipId"**: , **"externalClientId"**: } | (Required) Contains Agent(TR) information and, in the case that an Agent Enabler(TR-TSP) is acting on behalf of an Agent(TR), the authorization and relationship information. | Yes |
| consumer | { **"fullName"**: , **"lastName"**: , **"firstName"**: , **"consumerId"**: , **"countryCode"**: undefined (ISO 3166-1 alpha-2), **"emailAddress"**: undefined (email), **"languageCode"**: , **"mobileNumber"**: { **"countryCode"**: , **"phoneNumber"**: , **"numberIsVoiceOnly"**: }, **"consumerIdentities"**: , **"nationalIdentifier"**: } | (Required) Consumer/Card Holder data for Validation/Reporting. | Yes |
| appInstance | { **"ipAddress"**: , **"userAgent"**: , **"deviceData"**: { **"type"**: , **"brand"**: , **"model"**: , **"manufacturer"**: }, **"countryCode"**: undefined (ISO 3166-1-alpha2), **"clientDeviceId"**: , **"applicationName"**: } | (Required) Device and Application instance data. | Yes |
| consentData | | (Conditional) An array of consumer consents for the use of their data for personalization and platform functionality, ensuring compliance with Visa's privacy and regulatory requirements. Conditionality: This field is required when the consumer has not previously provided consent within VIC or when updated consent is needed due to changes in privacy requirements. Note: If this object is omitted, it will be assumed that the user has accepted \\"all\\" Visa Terms & Conditions as part of a partner‑orchestrated flow. | No |
| assuranceData | | (Required) FIDO Attestation/Assertion Data. | No |
| clientReferenceId | | (Required) Transactional identifier provided by the Client. | Yes |
| enrollmentReferenceData | { **"enrollmentReferenceId"**: , **"enrollmentReferenceType"**:
**Available values:** "TOKEN_REFERENCE_ID", **"enrollmentReferenceProvider"**: } | (Required) Token Reference Data to be enrolled in the VACP Platform. | Yes |
#### Mandates Schema
(Conditional) Consumer Set Transaction Mandates Conditionality: Required when a purchase intent is initiated with a
mandate by consumer.
| Name | Type | Description | Required |
| ---- | ---- | ----------- | -------- |
| Mandates | | (Conditional) Consumer Set Transaction Mandates Conditionality: Required when a purchase intent is initiated with a mandate by consumer. | |
#### DynamicDataEmv Schema
Dynamic data, generated using the dynamicDataType preference indicated in paymentOptions
| Name | Type | Description | Required |
| ---- | ---- | ----------- | -------- |
| dynamicDataType |
**Available values:** "CARD_APPLICATION_CRYPTOGRAM_SHORT_FORM", "DYNAMIC_CARD_SECURITY_CODE", "NONE",
**Default:** CARD_APPLICATION_CRYPTOGRAM_SHORT_FORM | Type of Dynamic Data required in the payload. Default value is CARD_APPLICATION_CRYPTOGRAM_SHORT_FORM.
*Enum:* `"CARD_APPLICATION_CRYPTOGRAM_SHORT_FORM"`, `"DYNAMIC_CARD_SECURITY_CODE"`, `"NONE"` | Yes |
| dynamicDataValue | | (Required) Value of the dynamic data. Conditionality: Required when the value of dynamicDataType is not set to NONE | No |
| dynamicDataExpiration | | (Required) UTC time in Unix epoch format. Date and time at which the Dynamic Data expires | Yes |
| transactionReferenceId | | (Optional) Transaction Reference Identifier | No |
#### VerificationDataEnhanced Schema
verification data for /v2/credentials-for-instruction API
| Name | Type | Description | Required |
| ---- | ---- | ----------- | -------- |
| methodResults | { **"error"**: { **"reason"**: , **"status"**: , **"message"**: , **"errorDetail"**: }, **"identifier"**: , **"dfpSessionId"**: , **"fidoAssertionData"**: { **"code"**: }, **"fidoAttestationData"**: { **"code"**: } } | Authentication/Verification Method Attributes associated with Visa Passkey(FIDO2) Authentication. Clients should silently disregard any unrecognized fields in the JSON object. | No |
| additionalData | | (Optional) Data collected during the verification process | No |
| verificationType |
**Available values:** "CARDHOLDER", "DEVICE" | Type of the verification data. Default value is CARDHOLDER
*Enum:* `"CARDHOLDER"`, `"DEVICE"` | No |
| verificationEntity |
**Available values:** "10", "20", "30", "40" | (Required) Entity performing the verification 10 - VISA (Default) 20 - WALLET_PROVIDER 30 - AGENT 40 - AGENT_ENABLER
*Enum:* `"10"`, `"20"`, `"30"`, `"40"` | Yes |
| verificationEvents | | (Optional) Event where the verification occurred 01 - Payment transaction 02 - Add card / Card enrollment 03 - Profile access 04 - Account verification | No |
| verificationMethod |
**Available values:** "02", "04", "21", "22", "23" | (Required) Method of the verification 02 - App-based authentication 04 - One-time passcode 21 - Visa Token Service step-up: Device binding 22 - Visa Token Service step-up: Cardholder verification 23 - FIDO2
*Enum:* `"02"`, `"04"`, `"21"`, `"22"`, `"23"` | Yes |
| verificationResults |
**Available values:** "01", "02", "03", "04", "21" | (Required) Result of the verification 01 - Verified 02 - Not verified 03 - Not performed 04 - Not required 21 - Not allowed
*Enum:* `"01"`, `"02"`, `"03"`, `"04"`, `"21"` | Yes |
| verificationTimestamp | | (Required) Date and time the verification occurred. UTC time in Unix epoch format | Yes |
#### TransactionDetail Schema
| Name | Type | Description | Required |
| ---- | ---- | ----------- | -------- |
| TransactionDetail | { **"merchantUrl"**: , **"merchantName"**: , **"transactionAmount"**: { **"tax"**: , **"discount"**: , **"subTotal"**: , **"transactionAmount"**: , **"shippingAndHandling"**: , **"transactionCurrencyCode"**: }, **"transactionReferenceId"**: } & { **"products"**: , **"merchantId"**: , **"attachments"**: , **"deliveryMethod"**:
**Available values:** "NO_DELIVERY", "ADDRESS_BILLING", "ADDRESS_ON_FILE", "ADDRESS_OTHER", "PICKUP", "ELECTRONIC", **"merchantDomain"**: , **"merchantLocale"**: , **"paymentOptions"**: { **"dynamicDataType"**:
**Available values:** "TAVV", "DAVV", "NONE", **"dpaDynamicDataTtlMinutes"**: }, **"merchantOrderId"**: , **"shippingAddress"**: { **"zip"**: , **"city"**: , **"name"**: , **"line1"**: , **"line2"**: , **"line3"**: , **"state"**: , **"addressId"**: undefined (uuid), **"createTime"**: , **"countryCode"**: undefined (ISO 3166-1-alpha2), **"lastUsedTime"**: } & { **"deliveryContactDetails"**: { **"instructions"**: , **"contactFullName"**: , **"contactPhoneNumber"**: { **"countryCode"**: , **"phoneNumber"**: , **"numberIsVoiceOnly"**: }, **"contactEmailAddress"**: undefined (email) } }, **"transactionType"**:
**Available values:** "PURCHASE", "BILL_PAYMENT", "MONEY_TRANSFER", "DISBURSEMENT", "P2P", **"merchantCountryCode"**: undefined (ISO 3166-1-alpha2), **"merchantCategoryCode"**: , **"paymentServiceProviderUrl"**: , **"paymentServiceProviderName"**: } | | |
#### TokenId Schema
(Required)A Token Reference Identifier for a card that can be used for payments. This identifier is used to reference a
specific tokenized card across various operations.
| Name | Type | Description | Required |
| ---- | ---- | ----------- | -------- |
| TokenId | | (Required)A Token Reference Identifier for a card that can be used for payments. This identifier is used to reference a specific tokenized card across various operations. | |
#### AssuranceData Schema
(Required) FIDO Attestation/Assertion Data.
| Name | Type | Description | Required |
| ---- | ---- | ----------- | -------- |
| AssuranceData | | (Required) FIDO Attestation/Assertion Data. | |
#### PersonalizationReferenceData Schema
Personalization Reference Data
| Name | Type | Description | Required |
| ---- | ---- | ----------- | -------- |
| dataTokenId | | A reference identifier that serves as a key to retrieve stored preference data, customization settings, or behavioral information. | No |
#### EnrollmentReferenceData Schema
(Required) Token Reference Data to be enrolled in the VACP Platform.
| Name | Type | Description | Required |
| ---- | ---- | ----------- | -------- |
| enrollmentReferenceId | | Identifier of the enrolment reference | Yes |
| enrollmentReferenceType |
**Available values:** "TOKEN_REFERENCE_ID" | Type of the enrolment reference. For Visa tokens, the enrollmentReferenceId field should contain a valid vProvisionedTokenID
*Enum:* `"TOKEN_REFERENCE_ID"` | Yes |
| enrollmentReferenceProvider | | Provider of the enrolment reference. Valid Values are: VTS | No |
#### ConsumerPrompt Schema
(Optional) Recap - A summary or condensed version of user prompts that leads to the purchase.
| Name | Type | Description | Required |
| ---- | ---- | ----------- | -------- |
| ConsumerPrompt | | (Optional) Recap - A summary or condensed version of user prompts that leads to the purchase. | |
#### CredentialsResponseComplete Schema
Response for /v2/credentials-for-instruction API with enhanced payload structure
| Name | Type | Description | Required |
| ---- | ---- | ----------- | -------- |
| payload | { **"network"**:
**Available values:** "visa", "mastercard", "amex", "discover", **"panLastFour"**: , **"signedPayload"**: undefined (application/jwt), **"panExpirationYear"**: , **"panExpirationMonth"**: , **"encryptedSignedPayload"**: , **"paymentAccountReference"**: } | Payment credentials with card metadata. Contains EITHER signedPayload (JWS) OR encryptedSignedPayload (JWE), but not both. Selection depends on paymentOptions.encryptionOverride and merchant encryption key availability. | Yes |
| instructionId | | (Required) Unique instruction identifier. | Yes |
| clientReferenceId | | (Required) Transactional identifier provided by the Client. | Yes |
#### TokenRequestData Schema
Network Specific Token Request Data
| Name | Type | Description | Required |
| ---- | ---- | ----------- | -------- |
| tokenReferenceData | { **"tokenId"**: , **"clientDeviceId"**: , **"tokenRequestorId"**: , **"clientWalletAccountId"**: , **"paymentAccountReference"**: } | (Conditional) Token References representing a source token with-in a Token for Token usecase. | No |
#### ConsumerSimplified Schema
(Required) A unique identifier for the Consumer within the Client's system. If enrollment is being performed by an agent enabler, this consumerId will be associated with the agent and must be identical for each card being enrolled for the same consumer.
| Name | Type | Description | Required |
| ---- | ---- | ----------- | -------- |
| consumerId | | (Required) Unique identifier for the Consumer | Yes |
| countryCode | undefined (ISO 3166-1 alpha-2) | (Conditional) Consumer-provided country code. Must be provided if consumerId doesn't already exist in VICP | No |
| languageCode | | (Conditional) Consumer-provided language choice. Must be provided if consumerId doesn't already exist in VICP | No |
| consumerIdentities | | (Conditional) Consumer identities data. Conditions: - Provide all consumerIdentities that can be used by the consumer to login. - username (USER_NAME) must be present AND at least one of emailAddress (EMAIL_ADDRESS) or mobileNumber (MOBILE_PHONE_NUMBER) must be present. - Required if consumerId doesn't already exist in VICP. | No |
#### BusinessIdentification Schema
Business identification.
| Name | Type | Description | Required |
| ---- | ---- | ----------- | -------- |
| acquirerMerchantId | | Acquirer-assigned merchant identifier. | No |
| businessIdentificationType | | Conditionality: Required when acquirerMerchantId is not present or when business Identification Value is present. | No |
| businessIdentificationValue | | Conditionality: Required when acquirerMerchantId is not present or when businessIdentificationType is present. | No |
#### CompositeTransactionData Schema
| Name | Type | Description | Required |
| ---- | ---- | ----------- | -------- |
| client | { **"agentId"**: , **"authorization"**: , **"externalAppId"**: , **"relationshipId"**: , **"externalClientId"**: } | (Required) Contains Agent(TR) information and, in the case that an Agent Enabler(TR-TSP) is acting on behalf of an Agent(TR), the authorization and relationship information. | Yes |
| tokenId | | (Required)A Token Reference Identifier for a card that can be used for payments. This identifier is used to reference a specific tokenized card across various operations. | Yes |
| consumer | { **"fullName"**: , **"lastName"**: , **"firstName"**: , **"consumerId"**: , **"countryCode"**: undefined (ISO 3166-1 alpha-2), **"emailAddress"**: undefined (email), **"languageCode"**: , **"mobileNumber"**: { **"countryCode"**: , **"phoneNumber"**: , **"numberIsVoiceOnly"**: }, **"consumerIdentities"**: , **"nationalIdentifier"**: } | (Required) Consumer/Card Holder data for Validation/Reporting. | Yes |
| mandates | | (Conditional) Consumer Set Transaction Mandates Conditionality: Required when a purchase intent is initiated with a mandate by consumer. | Yes |
| appInstance | { **"ipAddress"**: , **"userAgent"**: , **"deviceData"**: { **"type"**: , **"brand"**: , **"model"**: , **"manufacturer"**: }, **"countryCode"**: undefined (ISO 3166-1-alpha2), **"clientDeviceId"**: , **"applicationName"**: } | (Required) Device and Application instance data. | Yes |
| consentData | | (Conditional) An array of consumer consents for the use of their data for personalization and platform functionality, ensuring compliance with Visa's privacy and regulatory requirements. Conditionality: This field is required when the consumer has not previously provided consent within VIC or when updated consent is needed due to changes in privacy requirements. Note: If this object is omitted, it will be assumed that the user has accepted \\"all\\" Visa Terms & Conditions as part of a partner‑orchestrated flow. | No |
| isRecurring | | (Optional) Indicates whether the transaction is recurring. Default value is false. | No |
| assuranceData | | (Required) FIDO Attestation/Assertion Data. | Yes |
| consumerPrompt | | (Optional) Recap - A summary or condensed version of user prompts that leads to the purchase. | No |
| transactionData | | (Conditional) Transaction details associated with the instruction. Conditionality: Transaction details are necessary for risk evaluation, fraud prevention, and payment authentication. To maximize transaction approval rates, it is highly recommended to provide all available data points, whether a field is marked as required, conditional, or optional. | No |
| clientReferenceId | | (Required) Transactional identifier provided by the Client. | Yes |
| partnerReferenceId | | (Optional) Supplemental Transactional identifier provided by the Partner of the client. | No |
#### TransactionResponseComplete Schema
| Name | Type | Description | Required |
| ---- | ---- | ----------- | -------- |
| TransactionResponseComplete | { **"instructionId"**: , **"clientReferenceId"**: } & { **"status"**:
**Available values:** "COMPLETED", **"authorization"**: , **"signedPayload"**: undefined (application/jwt) } | | |
#### Error Schema
| Name | Type | Description | Required |
| ---- | ---- | ----------- | -------- |
| reason | | Error reason as associated with the HTTP status code. | Yes |
| status | | HTTP status code to categorize the errors. | Yes |
| message | | Error message as associated with the HTTP status code. | Yes |
| errorDetail | | | No |
#### Quantity Schema
(Conditional) Quantity of the product.
| Name | Type | Description | Required |
| ---- | ---- | ----------- | -------- |
| Quantity | | (Conditional) Quantity of the product. | |
**Example**
10
#### Mandate Schema
User mandates.
| Name | Type | Description | Required |
| ---- | ---- | ----------- | -------- |
| quantity | | (Conditional) Quantity of the product.
*Example:* `"10"` | No |
| mandateId | | (Required) Unique identifier with in the context of a purchase-intent for the mandate. Assigned by Partner. Id shall not be reused when a mandate is updated/deleted. | Yes |
| description | | (Required) Description of the product
*Example:* `"50 Blue Balloons"` | Yes |
| declineThreshold | { **"amount"**: , **"currencyCode"**: } | (Required) Transaction Decline Threshold amount | Yes |
| merchantCategory | | (Optional) Merchant category Description | No |
| effectiveUntilTime | | (Required) UTC time in Unix epoch format. | Yes |
| recurringFrequency |
**Available values:** "WEEKLY", "MONTHLY", "YEARLY" | (Conditional) Frequency of the transaction. Specifies how often the transaction occurs. If the mandate contains a recurring instruction, a recurring frequency must be provided and the request isRecurring flag should be set to true.
*Enum:* `"WEEKLY"`, `"MONTHLY"`, `"YEARLY"` | No |
| merchantCategoryCode | | (Optional) Merchant category Code | No |
| preferredMerchantName | | (Optional) User merchant preference.
*Example:* `"Best Buy"` | No |
#### OrderData Schema
Order data.
| Name | Type | Description | Required |
| ---- | ---- | ----------- | -------- |
| orderId | | (Optional) Unique identifier for the order | No |
| products | | (Optional) Array of products in the order | No |
| orderDate | | (Optional) Order date (UTC time in Epoch format) | No |
| orderStatus | | (Optional) Status of the order | No |
| transactionAmount | { **"tax"**: , **"discount"**: , **"subTotal"**: , **"transactionAmount"**: , **"shippingAndHandling"**: , **"transactionCurrencyCode"**: } | The final amount that the customer needs to pay or paid. | No |
| expectedDeliveryDate | | (Optional) Expected delivery date for the order (UTC time in Epoch format) | No |
#### CancelInstructionData Schema
| Name | Type | Description | Required |
| ---- | ---- | ----------- | -------- |
| appInstance | { **"ipAddress"**: , **"userAgent"**: , **"deviceData"**: { **"type"**: , **"brand"**: , **"model"**: , **"manufacturer"**: }, **"countryCode"**: undefined (ISO 3166-1-alpha2), **"clientDeviceId"**: , **"applicationName"**: } | (Required) Device and Application instance data. | Yes |
| assuranceData | | (Required) FIDO Attestation/Assertion Data. | Yes |
| clientReferenceId | | (Required) Transactional identifier provided by the Client. | Yes |
#### TransactionResponseWithPendingEvents Schema
| Name | Type | Description | Required |
| ---- | ---- | ----------- | -------- |
| TransactionResponseWithPendingEvents | { **"instructionId"**: , **"clientReferenceId"**: } & { **"reason"**: { **"code"**:
**Available values:** "DECLINED", "EXPIRED", **"details"**: , **"message"**: , **"category"**:
**Available values:** "VALIDATION_ERROR", "AUTHORIZATION_ERROR", "PROCESSING_ERROR", "LIMIT_ERROR", **"correlationId"**: }, **"status"**:
**Available values:** "PENDING", "EXPIRED", "CANCELLED", "DECLINED", **"pendingEvents"**: } | | |
#### SecuredPayload Schema
Decoded secured payload signed by Visa.
Present in: signedPayload (JWS) of [TransactionResponseComplete](#/components/schemas/TransactionResponseComplete).
Note: this object is never transmitted as JSON on the wire. It is the decoded plaintext obtained after
verifying the JWS signature.
| Name | Type | Description | Required |
| ---- | ---- | ----------- | -------- |
| dynamicData | | Dynamic Payment Data/Cryptogram associated with the PAN/Token used for the purchase. | No |
#### MandateReferenceData Schema
List of User Mandates applied/associated with this transaction/item.
| Name | Type | Description | Required |
| ---- | ---- | ----------- | -------- |
| MandateReferenceData | | List of User Mandates applied/associated with this transaction/item. | |
#### UriData Schema
URI data.
| Name | Type | Description | Required |
| ---- | ---- | ----------- | -------- |
| uri | | URI | No |
| uriType |
**Available values:** "APP_URI", "WEB_URI" | Type of the URI. Valid Values are APP_URI, and WEB_URI
*Enum:* `"APP_URI"`, `"WEB_URI"` | No |
#### ShippingAddress Schema
Delivery Address & Contact details
| Name | Type | Description | Required |
| ---- | ---- | ----------- | -------- |
| ShippingAddress | { **"zip"**: , **"city"**: , **"name"**: , **"line1"**: , **"line2"**: , **"line3"**: , **"state"**: , **"addressId"**: undefined (uuid), **"createTime"**: , **"countryCode"**: undefined (ISO 3166-1-alpha2), **"lastUsedTime"**: } & { **"deliveryContactDetails"**: { **"instructions"**: , **"contactFullName"**: , **"contactPhoneNumber"**: { **"countryCode"**: , **"phoneNumber"**: , **"numberIsVoiceOnly"**: }, **"contactEmailAddress"**: undefined (email) } } | Delivery Address & Contact details | |
#### CredentialTransactionDataRequestV2 Schema
Request schema for /v2/instructions/{id}/credentials (Retrieve Payment Credential API).
| Name | Type | Description | Required |
| ---- | ---- | ----------- | -------- |
| client | { **"agent"**: { **"agentId"**: , **"agentSignature"**: { **"signature"**: , **"signatureInput"**: { **"alg"**:
**Available values:** "Ed25519", "RS256", "ES256", **"tag"**:
**Available values:** "credential-request", "confirmation-request", **"keyId"**: , **"nonce"**: , **"created"**: , **"expires"**: } } }, **"authorization"**: , **"externalAppId"**: , **"relationshipId"**: , **"externalClientId"**: } | Client with Agent(TR) information and, in the case that an Agent Enabler(TR-TSP) is acting on behalf of an Agent(TR), the authorization and relationship information. | Yes |
| tokenId | | (Required)A Token Reference Identifier for a card that can be used for payments. This identifier is used to reference a specific tokenized card across various operations. | Yes |
| appInstance | { **"ipAddress"**: , **"userAgent"**: , **"deviceData"**: { **"type"**: , **"brand"**: , **"model"**: , **"manufacturer"**: }, **"countryCode"**: undefined (ISO 3166-1-alpha2), **"clientDeviceId"**: , **"applicationName"**: } | (Required) Device and Application instance data. | No |
| transactionData | { **"merchantUrl"**: , **"merchantName"**: , **"transactionAmount"**: { **"tax"**: , **"discount"**: , **"subTotal"**: , **"transactionAmount"**: , **"shippingAndHandling"**: , **"transactionCurrencyCode"**: }, **"transactionReferenceId"**: } & { **"merchantId"**: , **"billingAddress"**: { **"zip"**: , **"city"**: , **"name"**: , **"line1"**: , **"line2"**: , **"line3"**: , **"state"**: , **"addressId"**: undefined (uuid), **"createTime"**: , **"countryCode"**: undefined (ISO 3166-1-alpha2), **"lastUsedTime"**: }, **"deliveryMethod"**:
**Available values:** "NO_DELIVERY", "ADDRESS_BILLING", "ADDRESS_ON_FILE", "ADDRESS_OTHER", "PICKUP", "ELECTRONIC", **"merchantDomain"**: , **"paymentOptions"**: { **"dynamicDataType"**:
**Available values:** "CARD_APPLICATION_CRYPTOGRAM_SHORT_FORM", "DYNAMIC_CARD_SECURITY_CODE", "NONE",
**Default:** CARD_APPLICATION_CRYPTOGRAM_SHORT_FORM, **"encryptionOverride"**: }, **"shippingAddress"**: { **"zip"**: , **"city"**: , **"name"**: , **"line1"**: , **"line2"**: , **"line3"**: , **"state"**: , **"addressId"**: undefined (uuid), **"createTime"**: , **"countryCode"**: undefined (ISO 3166-1-alpha2), **"lastUsedTime"**: } & { **"deliveryContactDetails"**: { **"instructions"**: , **"contactFullName"**: , **"contactPhoneNumber"**: { **"countryCode"**: , **"phoneNumber"**: , **"numberIsVoiceOnly"**: }, **"contactEmailAddress"**: undefined (email) } } } & { **"policies"**: { **"refundPolicy"**: , **"disputePolicy"**: , **"shippingPolicy"**: , **"cancellationPolicy"**: , **"termsAndConditions"**: , **"discountAndPromotions"**: }, **"encryptedInstruction"**: , **"mandateReferenceData"**: , **"transactionReferenceIdType"**:
**Available values:** "ENCRYPTED" } & { **"mandateReferenceData"**: } | (Required) Transaction data for this credential retrieval. One mandate reference required. | Yes |
| clientReferenceId | | (Required) Transactional identifier provided by the Client. | Yes |