# Visa Intelligent Data Exchange API

The Visa Intelligent Data Exchange (Visa IDX) API enables third-party providers, on behalf of their merchant clients, to provide Visa with enhanced data for card-not-present (CNP) transactions prior to authorization using a channel outside of EMV 3-D Secure (3DS). Visa will share select enhanced data with issuers in the authorization request message via the Visa IDX mechanism for issuers to use in their authorization decisioning, helping improve CNP transaction approval rates and increase fraud detection. Visa IDX is a supplemental data delivery mechanism designed to help enrich Visa issuers’ risk management for CNP transactions by sending insights from outside of the authorization flow to issuers and endpoints within the Visa network.

## Visa IDX API Request  v1 - Latest

Initiate a Visa IDX API request to send supplemental data that will be used during authorization.

### Request

##### header Parameters

|     |     |
| --- | --- |
| Content-Type<br>required | string<br>Request content type<br>Example: application/json |

##### Request Body schema: application/json

|     |     |
| --- | --- |
| acctNumber<br>required | string <Format represented ISO 7812.>  \[ 13 .. 19 \] characters <br>Account number that will be used in the authorisation request for payment transactions. May be represented by PAN, Payment Token.<br>Example: "4111111111111111" |
| acquirerBIN<br>required | string \[ 6 .. 11 \] characters <br>Acquiring institution identification code.<br>Example: "438309" |
| merchantID<br>required | string \[ 1 .. 35 \] characters <br>Merchant identifier.<br>Example: "00002000000" |
| purchaseAmount<br>required | string <Must be between 1 and 48 numeric numbers>  \[ 1 .. 48 \] characters <br>Purchase amount in minor units of currency with all punctuation removed.<br>Example: "12550" |
| purchaseCurrency<br>required | string <ISO 4217 three-digit currency code>  3 characters <br>Currency code of the purchase amount.<br>Example: "840" |
| purchaseDate<br>required | string <YYYYMMDDHHMMSS>  14 characters <br>Date and time of the transaction converted into UTC.<br>Example: "20240630122155" |
| purchaseExponent<br>required | string <ISO 4217 currency exponent>  1 characters <br>Minor units of currency as specified in the ISO 4217 currency exponent.<br>Example: "2" |
| transID<br>required | string <uuid> <br>Unique transaction Id to track the request.<br>Example: "ee8439b0-67fe-4f22-92ea-575902dd3019" |
| acceptLanguages | Array of strings \[ 1 .. 99 \] items <br>Value representing the Browser language preference present in the HTTP header, as defined in IETF BCP 47. The value can be empty.<br>Example: \["en-US","en;q=0.9","fr;q=0.8","de;q=0.7","es;q=0.6"\] |
| acctID | string \[ 1 .. 64 \] characters <br>Cardholder Account Identifier.<br>Example: "account-1234567890" |
| acctType | string<br>Indicates the type of account. For example, credit or debit. Values: - '01' # Not applicable - '02' # Credit - '03' # Debit - '' # Empty value <br>Enum:"01""02""03""" |
| acquirerCountryCode | string <ISO 3166-1 numeric three-digit country code or empty value>  3 characters <br>The code of the country where the acquiring institution is located. The value can be empty.<br>Example: "840" |
| billAddrCity | string \[ 1 .. 25 \] characters <br>The city of the Cardholder billing address associated with the card used for this purchase.<br>Example: "New York" |
| billAddrCountry | string <ISO 3166-1 alpha-3 format three-letter country code or empty value>  3 characters <br>The country of the Cardholder billing address associated with the card used for this purchase. The value can be empty.<br>Example: "USA" |
| billAddrLine1 | string \[ 1 .. 99 \] characters <br>First line of the Cardholder billing address associated with the card used for this purchase.<br>Example: "123 Main St" |
| billAddrLine2 | string \[ 1 .. 99 \] characters <br>Second line of the Cardholder billing address associated with the card used for this purchase.<br>Example: "Apt 4B" |
| billAddrLine3 | string \[ 1 .. 99 \] characters <br>Third line of the Cardholder billing address associated with the card used for this purchase.<br>Example: "Near Central Park" |
| billAddrPostCode | string \[ 1 .. 16 \] characters <br>ZIP or other postal code of the Cardholder billing address associated with the card used for this purchase.<br>Example: "10001" |
| billAddrState | string <Country subdivision code defined in ISO 3166-2 or empty value>  \[ 2 .. 3 \] characters <br>The state of the Cardholder billing address associated with the card used for this purchase. The value can be empty.<br>Example: "NY" |
| browserAcceptHeader | string \[ 1 .. 2048 \] characters <br>HTTP accept headers<br>Example: "text/html,application/xhtml+xml,application/xml; q=0.9,*/*;q=0.8" |
| browserColorDepth | string <numeric value between 1-99 or empty value.>  \[ 1 .. 2 \] characters <br>Value representing the bit depth of the colour palette for displaying images, in bits per pixel. The value can be empty.<br>Example: "24" |
| browserIP | string <IPv4 address (refer to RFC 791) or IPv6 address (Refer to RFC 4291) or empty value>  \[ 7 .. 45 \] characters <br>IP address the browser is connecting from. Either this or deviceIP shall be provided. The value can be empty.<br>Example: "192.168.1.11" |
| browserJavaEnabled | boolean <true or false> <br>Boolean that represents the ability of the Cardholder Browser to execute Java.<br>Example: true |
| browserJavascriptEnabled | boolean <true or false> <br>Boolean that represents the ability of the Cardholder Browser to execute JavaScript.<br>Example: true |
| browserLanguage | string \[ 1 .. 35 \] characters <br>Value representing the Browser language as defined in IETF BCP47. The value can be empty.<br>Example: "en" |
| browserScreenHeight | string \[ 1 .. 6 \] characters <br>Total height of the Cardholder’s screen in pixels. The value can be empty.<br>Example: "1080" |
| browserScreenWidth | string \[ 1 .. 6 \] characters <br>Total width of the Cardholder’s screen in pixels. The value can be empty.<br>Example: "1920" |
| browserTZ | string \[ 1 .. 5 \] characters <br>Time zone offset in minutes between UTC and the Cardholder Browser local time. The value can be empty.<br>Example: "-240" |
| browserUserAgent | string \[ 1 .. 2048 \] characters <br>Exact content of the HTTP user-agent header.<br>Example: "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/58.0.3029.110 Safari/537.36" |
| cardExpiryDate | string <YYMM or empty value>  4 characters <br>Expiry Date of the PAN. The value can be empty.<br>Example: "2806" |
| cardholderName | string \[ 1 .. 45 \] characters <br>Name of the Cardholder.<br>Example: "John Doe" |
| cardSecurityCode | string \[ 3 .. 4 \] characters <br>Three- or four-digit security code printed on the card. The value can be empty.<br>Example: "123" |
| deviceChannel | string<br>Indicates the type of channel interface being used to initiate the transaction. Values: - '01' # App-based - '02' # Browser - '' # Empty value <br>Enum:"01""02" |
| deviceId | string \[ 1 .. 64 \] characters <br>Unique and immutable identifier linked to a device.<br>Example: "Device-1234567890" |
| deviceIP | string <IPv4 address (refer to RFC 791) or IPv6 address (Refer to RFC 4291) or empty value>  \[ 7 .. 39 \] characters <br>IP address the device is connecting from. Either this or browserIP shall be provided. The value can be empty.<br>Example: "2001:0db8:85a3:0000:0000:8a2e:0370:7334" |
| email | string <Shall meet requirements of Section 3.4 of IETF RFC 5322 or empty value.>  \[ 1 .. 99 \] characters <br>The email address associated with the transaction. The value can be empty.<br>Example: "example@example.com" |
| geoLocation | object <latitude: string, maximum 10 characters. longitude: string, maximum 10 characters.> <br>The geographic location of the transaction. The object includes the latitude and longitude values.<br>Example: {"latitude":"37.4","longitude":"-122.1"} |
| homePhone | object <cc: 1–3 characters. subscriber: variable, maximum 15 characters. Refer to ITU-E.164 for additional information on format and length.> <br>The home phone number provided. The object includes the country code (cc) and subscriber number (subscriber).<br>Example: {"cc":"1","subscriber":"1234567899"} |
| issuerBIN | string \[ 6 .. 8 \] characters <br>The issuer bank identification number. equivalent to the first 6 or 8 digits of the PAN. The value can be empty. Required if acctNumber is not provided.<br>Example: "438309" |
| lastFourDigits | string 4 characters <br>The last four digits of the PAN. The value can be empty. Required if acctNumber is not provided.<br>Example: "1111" |
| loginId | string \[ 0 .. 32 \] characters <br>The login identifier associated with the cardholder account at the time of the transaction. The value can be empty.<br>Example: "user@example.com" |
| mcc | string 4 characters <br>Code describing the Merchant’s type of business, product or service. The value can be empty.<br>Example: "5411" |
| merchantCountryCode | string <ISO 3166-1 numeric three-digit country code or empty value>  3 characters <br>Country code of the merchant. The value can be empty.<br>Example: "840" |
| merchantName | string <Same name used in the authorisation message as defined in ISO 8583-1>  \[ 1 .. 40 \] characters <br>Merchant name.<br>Example: "Merchant Name" |
| messageCategory | string<br>Identifies the category of the message (payment or non-payment). Values: - '01' # Payment - '02' # Non-payment - '' # Empty value <br>Enum:"01""02" |
| mobilePhone | object <cc: 1–3 characters. subscriber: variable, maximum 15 characters. Refer to ITU-E.164 for additional information on format and length.> <br>The mobile phone number provided. The object includes the country code (cc) and subscriber number (subscriber).<br>Example: {"cc":"1","subscriber":"1234567899"} |
| payTokenInd | boolean <true or false> <br>A value of True indicates that the transaction was de-tokenized.<br>Example: true |
| productType | string<br>Type of purchased product. Values: - '01' # Digital - '02' # Physical - '' # Empty value <br>Enum:"01""02" |
| purchaseInstalData | string <numeric value shall be greater than 1 or empty value>  \[ 1 .. 3 \] characters <br>Indicates the maximum number of authorisations permitted for installment payments. The value can be empty.<br>Example: "3" |
| purchaseOrderNumber | string \[ 1 .. 26 \] characters <br>Merchant-specific order number for the transaction that is shared with the customer/cardholder.<br>Example: "ORD-12345-ABC" |
| reasonCodes | Array of strings \[ 1 .. 10 \] items <br>The reason codes associated with the transaction's risk score. The value can be empty.<br>Example: \["UNKNOWN_SHIP_ADDRESS","LRG_AMNT"\] |
| requestDCAPStatus | boolean<br>Indicates whether the sender requests Digital Commerce Authentication Program (DCAP) eligibility information to be returned.<br>Example: false |
| shipAddrCity | string \[ 1 .. 25 \] characters <br>City portion of the shipping address requested by the Cardholder.<br>Example: "New York" |
| shipAddrCountry | string <ISO 3166-1 numeric three-digit country code or empty value>  3 characters <br>The country of shipping address requested by the Cardholder. The value can be empty.<br>Example: "840" |
| shipAddrLine1 | string \[ 1 .. 99 \] characters <br>First line of the street address or equivalent local portion of the shipping address requested by the Cardholder. The value can be empty.<br>Example: "123 Main St" |
| shipAddrLine2 | string \[ 0 .. 99 \] characters <br>Second line of the street address or equivalent local portion of the shipping address requested by the Cardholder.<br>Example: "Apt 4B" |
| shipAddrLine3 | string \[ 0 .. 99 \] characters <br>Third line of the street address or equivalent local portion of the shipping address requested by the Cardholder.<br>Example: "Near Central Park" |
| shipAddrPostCode | string \[ 1 .. 16 \] characters <br>ZIP or other postal code of the Cardholder shipping address. The value can be empty.<br>Example: "10001" |
| shipAddrState | string <Country subdivision code defined in ISO 3166-2 or empty value>  \[ 2 .. 3 \] characters <br>The state of the Cardholder shipping address. The value can be empty.<br>Example: "NY" |
| shipIndicator | string<br>Indicates shipping method chosen for the transaction. Values: - '01' # Ship to the Cardholder’s billing address - '02' # Ship to another verified address on file with the Merchant - '03' # Ship to an address that is different than the Cardholder’s billing address - '04' # “Ship to Store” / Pick-up at a local store (Store address shall be populated in shipping address fields) - '05' # Digital goods (includes online services, electronic gift cards and redemption codes) - '06' # Travel and event tickets, not shipped - '07' # Other (for example, gaming, digital services not shipped, emedia subscriptions, etc.) - '08' # Pick-up and go delivery - '09' # Locker delivery (or other automated pick-up) - '' # Empty value <br>Enum:"01""02""03""04""05""06""07""08""09" |
| thirdPartyRiskAssessment | string <numeric value between 1-99999 without leading 0's.>  \[ 1 .. 5 \] characters <br>The risk assessment associated with the transaction.<br>Example: "50" |
| thirdPartyRiskAssessmentType | string<br>Type of risk assessment provided. Values: - '01' # Score - '02' # Advice <br>Enum:"01""02" |
| transType | string<br>Indicates the type of transaction. Values: - '01' # Regular Transaction - '10' # AFT (Account Funding Transaction) <br>Enum:"01""10" |
| vdiClientRequestId | string<br>A unique 32 or 36 character GUID that uniquely identifies the current request.<br>Example: "354d1481a5dc4a9fa8e87ec73049f511" |
| workPhone | object <cc: 1–3 characters. subscriber: variable, maximum 15 characters. Refer to ITU-E.164 for additional information on format and length.> <br>The work phone number provided. The object includes the country code (cc) and subscriber number (subscriber).<br>Example: {"cc":"1","subscriber":"1234567899"} |

### Responses

200
Successful Visa IDX API response.

Warning messages may be included when certain validity, data quality, and other error or warning conditions are met and allow clients to self-correct.

##### Response Schema: application/json

|     |     |
| --- | --- |
| dcapIndicator | integer<br>Returns Digital Commerce Authentication Program (DCAP) eligibility status.<br>1. Not DCAP eligible.<br>2. DCAP eligible.<br>Enum:12<br>Example: 1 |
| idxMatchKey | string \[ 10 .. 50 \] characters <br>The key is used to match transaction data sent via Visa IDX API with the corresponding authorization request. The value of this attribute should be populated in field 126.9 of the authorization message. <br>Example: "IQYgAxdYYgAAAGqyhAJocAAAAAA=" |
| transID | string <uuid> <br>transID in the request echoed back for tracking.<br>Example: "ee8439b0-67fe-4f22-92ea-575902dd3019" |
| warningMessages | string \[ 0 .. 599 \] characters <br>Warning messages may appear:<br>- If any fields fail validation due to, for example, format violations.<br>- If a client is not enrolled to share risk assessment data: "Third Party Risk Assessment not processed - Client not enrolled."<br>- If an issuer is not enrolled to receive transaction and/or risk assessment data: "Issuer not enrolled."<br>- If the Acquirer BIN provided is not active: "Acquirer BIN is deactivated."<br>- If the Acquirer BIN provided is invalid or not found: "Acquirer BIN is invalid."<br>- If DCAP eligibility checks fail for the acquirer region: "DCAP Fail for acquirer region {Region Name} ({Region Code}). Field missing: \[ {Field Name} \]"<br> - Example: "DCAP Fail for acquirer region U.S.A (01). Field missing: \[Billing Address\]"<br>- If DCAP eligibility checks fail for the issuer: "Issuer VDCAP eligibility check failed."<br>- If the transaction type is invalid: "Transaction type is invalid."<br>Example: "\[\"DCAP Fail for acquirer region U.S.A (01). Field missing: \[Billing Address\]\"\]" |

400
The API server could not understand the request;

... (additional error responses omitted for brevity...)

----