Visa Intelligent Data Exchange API API Reference
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 required |
string Request content type Example: application/json |
Request Body schema: application/json
| acctNumber required |
string <Format represented ISO 7812.> [ 13 .. 19 ] characters Account number that will be used in the authorisation request for payment transactions. May be represented by PAN, Payment Token. Example: "4111111111111111" |
| acquirerBIN required |
string [ 6 .. 11 ] characters Acquiring institution identification code. Example: "438309" |
| merchantID required |
string [ 1 .. 35 ] characters Merchant identifier. Example: "00002000000" |
| purchaseAmount required |
string <Must be between 1 and 48 numeric numbers> [ 1 .. 48 ] characters Purchase amount in minor units of currency with all punctuation removed. Example: "12550" |
| purchaseCurrency required |
string <ISO 4217 three-digit currency code> 3 characters Currency code of the purchase amount. Example: "840" |
| purchaseDate required |
string Date and time of the transaction converted into UTC. Example: "20240630122155" |
| purchaseExponent required |
string <ISO 4217 currency exponent> 1 characters Minor units of currency as specified in the ISO 4217 currency exponent. Example: "2" |
| transID required |
string Unique transaction Id to track the request. Example: "ee8439b0-67fe-4f22-92ea-575902dd3019" |
| acceptLanguages | Array of strings [ 1 .. 99 ] items Value representing the Browser language preference present in the HTTP header, as defined in IETF BCP 47. The value can be empty. Example: ["en-US","en;q=0.9","fr;q=0.8","de;q=0.7","es;q=0.6"] |
| acctID | string [ 1 .. 64 ] characters Cardholder Account Identifier. Example: "account-1234567890" |
| acctType | string Indicates the type of account. For example, credit or debit. Values: - '01' # Not applicable - '02' # Credit - '03' # Debit - '' # Empty value Enum:"01""02""03""" |
| acquirerCountryCode | string <ISO 3166-1 numeric three-digit country code or empty value> 3 characters The code of the country where the acquiring institution is located. The value can be empty. Example: "840" |
| billAddrCity | string [ 1 .. 25 ] characters The city of the Cardholder billing address associated with the card used for this purchase. Example: "New York" |
| billAddrCountry | string <ISO 3166-1 alpha-3 format three-letter country code or empty value> 3 characters The country of the Cardholder billing address associated with the card used for this purchase. The value can be empty. Example: "USA" |
| billAddrLine1 | string [ 1 .. 99 ] characters First line of the Cardholder billing address associated with the card used for this purchase. Example: "123 Main St" |
| billAddrLine2 | string [ 1 .. 99 ] characters Second line of the Cardholder billing address associated with the card used for this purchase. Example: "Apt 4B" |
| billAddrLine3 | string [ 1 .. 99 ] characters Third line of the Cardholder billing address associated with the card used for this purchase. Example: "Near Central Park" |
| billAddrPostCode | string [ 1 .. 16 ] characters ZIP or other postal code of the Cardholder billing address associated with the card used for this purchase. Example: "10001" |
| billAddrState | string <Country subdivision code defined in ISO 3166-2 or empty value> [ 2 .. 3 ] characters The state of the Cardholder billing address associated with the card used for this purchase. The value can be empty. Example: "NY" |
| browserAcceptHeader | string [ 1 .. 2048 ] characters HTTP accept headers 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 Value representing the bit depth of the colour palette for displaying images, in bits per pixel. The value can be empty. Example: "24" |
| browserIP | string <IPv4 address (refer to RFC 791) or IPv6 address (Refer to RFC 4291) or empty value> [ 7 .. 45 ] characters IP address the browser is connecting from. Either this or deviceIP shall be provided. The value can be empty. Example: "192.168.1.11" |
| browserJavaEnabled | boolean Boolean that represents the ability of the Cardholder Browser to execute Java. Example: true |
| browserJavascriptEnabled | boolean Boolean that represents the ability of the Cardholder Browser to execute JavaScript. Example: true |
| browserLanguage | string [ 1 .. 35 ] characters Value representing the Browser language as defined in IETF BCP47. The value can be empty. Example: "en" |
| browserScreenHeight | string [ 1 .. 6 ] characters Total height of the Cardholder’s screen in pixels. The value can be empty. Example: "1080" |
| browserScreenWidth | string [ 1 .. 6 ] characters Total width of the Cardholder’s screen in pixels. The value can be empty. Example: "1920" |
| browserTZ | string [ 1 .. 5 ] characters Time zone offset in minutes between UTC and the Cardholder Browser local time. The value can be empty. Example: "-240" |
| browserUserAgent | string [ 1 .. 2048 ] characters Exact content of the HTTP user-agent header. 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 Expiry Date of the PAN. The value can be empty. Example: "2806" |
| cardholderName | string [ 1 .. 45 ] characters Name of the Cardholder. Example: "John Doe" |
| cardSecurityCode | string [ 3 .. 4 ] characters Three- or four-digit security code printed on the card. The value can be empty. Example: "123" |
| deviceChannel | string Indicates the type of channel interface being used to initiate the transaction. Values: - '01' # App-based - '02' # Browser - '' # Empty value Enum:"01""02" |
| deviceId | string [ 1 .. 64 ] characters Unique and immutable identifier linked to a device. Example: "Device-1234567890" |
| deviceIP | string <IPv4 address (refer to RFC 791) or IPv6 address (Refer to RFC 4291) or empty value> [ 7 .. 39 ] characters IP address the device is connecting from. Either this or browserIP shall be provided. The value can be empty. Example: "2001:0db8:85a3:0000:0000:8a2e:0370:7334" |
| string <Shall meet requirements of Section 3.4 of IETF RFC 5322 or empty value.> [ 1 .. 99 ] characters The email address associated with the transaction. The value can be empty. Example: "example@example.com" |
|
| geoLocation | object <latitude: string, maximum 10 characters. longitude: string, maximum 10 characters.> The geographic location of the transaction. The object includes the latitude and longitude values. 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.> The home phone number provided. The object includes the country code (cc) and subscriber number (subscriber). Example: {"cc":"1","subscriber":"1234567899"} |
| issuerBIN | string [ 6 .. 8 ] characters 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. Example: "438309" |
| lastFourDigits | string 4 characters The last four digits of the PAN. The value can be empty. Required if acctNumber is not provided. Example: "1111" |
| loginId | string [ 0 .. 32 ] characters The login identifier associated with the cardholder account at the time of the transaction. The value can be empty. Example: "user@example.com" |
| mcc | string 4 characters Code describing the Merchant’s type of business, product or service. The value can be empty. Example: "5411" |
| merchantCountryCode | string <ISO 3166-1 numeric three-digit country code or empty value> 3 characters Country code of the merchant. The value can be empty. Example: "840" |
| merchantName | string <Same name used in the authorisation message as defined in ISO 8583-1> [ 1 .. 40 ] characters Merchant name. Example: "Merchant Name" |
| messageCategory | string Identifies the category of the message (payment or non-payment). Values: - '01' # Payment - '02' # Non-payment - '' # Empty value 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.> The mobile phone number provided. The object includes the country code (cc) and subscriber number (subscriber). Example: {"cc":"1","subscriber":"1234567899"} |
| payTokenInd | boolean A value of True indicates that the transaction was de-tokenized. Example: true |
| productType | string Type of purchased product. Values: - '01' # Digital - '02' # Physical - '' # Empty value Enum:"01""02" |
| purchaseInstalData | string <numeric value shall be greater than 1 or empty value> [ 1 .. 3 ] characters Indicates the maximum number of authorisations permitted for installment payments. The value can be empty. Example: "3" |
| purchaseOrderNumber | string [ 1 .. 26 ] characters Merchant-specific order number for the transaction that is shared with the customer/cardholder. Example: "ORD-12345-ABC" |
| reasonCodes | Array of strings [ 1 .. 10 ] items The reason codes associated with the transaction's risk score. The value can be empty. Example: ["UNKNOWN_SHIP_ADDRESS","LRG_AMNT"] |
| requestDCAPStatus | boolean Indicates whether the sender requests Digital Commerce Authentication Program (DCAP) eligibility information to be returned. Example: false |
| shipAddrCity | string [ 1 .. 25 ] characters City portion of the shipping address requested by the Cardholder. Example: "New York" |
| shipAddrCountry | string <ISO 3166-1 numeric three-digit country code or empty value> 3 characters The country of shipping address requested by the Cardholder. The value can be empty. Example: "840" |
| shipAddrLine1 | string [ 1 .. 99 ] characters First line of the street address or equivalent local portion of the shipping address requested by the Cardholder. The value can be empty. Example: "123 Main St" |
| shipAddrLine2 | string [ 0 .. 99 ] characters Second line of the street address or equivalent local portion of the shipping address requested by the Cardholder. Example: "Apt 4B" |
| shipAddrLine3 | string [ 0 .. 99 ] characters Third line of the street address or equivalent local portion of the shipping address requested by the Cardholder. Example: "Near Central Park" |
| shipAddrPostCode | string [ 1 .. 16 ] characters ZIP or other postal code of the Cardholder shipping address. The value can be empty. Example: "10001" |
| shipAddrState | string <Country subdivision code defined in ISO 3166-2 or empty value> [ 2 .. 3 ] characters The state of the Cardholder shipping address. The value can be empty. Example: "NY" |
| shipIndicator | string 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 Enum:"01""02""03""04""05""06""07""08""09" |
| thirdPartyRiskAssessment | string <numeric value between 1-99999 without leading 0's.> [ 1 .. 5 ] characters The risk assessment associated with the transaction. Example: "50" |
| thirdPartyRiskAssessmentType | string Type of risk assessment provided. Values: - '01' # Score - '02' # Advice Enum:"01""02" |
| transType | string Indicates the type of transaction. Values: - '01' # Regular Transaction - '10' # AFT (Account Funding Transaction) Enum:"01""10" |
| vdiClientRequestId | string A unique 32 or 36 character GUID that uniquely identifies the current request. 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.> The work phone number provided. The object includes the country code (cc) and subscriber number (subscriber). 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 Returns Digital Commerce Authentication Program (DCAP) eligibility status. 1. Not DCAP eligible. 2. DCAP eligible. Enum:12 Example: 1 |
| idxMatchKey | string [ 10 .. 50 ] characters 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. Example: "IQYgAxdYYgAAAGqyhAJocAAAAAA=" |
| transID | string transID in the request echoed back for tracking. Example: "ee8439b0-67fe-4f22-92ea-575902dd3019" |
| warningMessages | string [ 0 .. 599 ] characters Warning messages may appear: - If any fields fail validation due to, for example, format violations. - If a client is not enrolled to share risk assessment data: "Third Party Risk Assessment not processed - Client not enrolled." - If an issuer is not enrolled to receive transaction and/or risk assessment data: "Issuer not enrolled." - If the Acquirer BIN provided is not active: "Acquirer BIN is deactivated." - If the Acquirer BIN provided is invalid or not found: "Acquirer BIN is invalid." - If DCAP eligibility checks fail for the acquirer region: "DCAP Fail for acquirer region {Region Name} ({Region Code}). Field missing: [ {Field Name} ]" - Example: "DCAP Fail for acquirer region U.S.A (01). Field missing: [Billing Address]" - If DCAP eligibility checks fail for the issuer: "Issuer VDCAP eligibility check failed." - If the transaction type is invalid: "Transaction type is invalid." 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...)