Ch 23 (08/30/2019 Update): Added "NOTE: If value passed > than field definition, it will be truncated to the maximum allowable value" to Lookup R&R fields including BillingFullName, BillingAddress1,2,3, ShippingAddress1,2,3, BillingCity, ShippingCity
***Changes made on 08/30/2019 are delineated below in Red.***
Added "NOTE: If the value passed is greater than the field definition, it will be truncated to the maximum allowable value" to nine Lookup Request Response fields including BillingFullName, BillingAddress1,2,3, ShippingAddress1,2,3, BillingCity, and ShippingCity
cmpi_lookup Request Message
TIP:
- All fields use ASCII character set (0-9, A-Z, a-z, special characters $%&@!_etc.)
- The required field contains one of the following values
- Y = Yes (Required field)
- C = Conditional (Conditions of transaction to determine if it's required)
- O = Optional (Not required but recommended pass)
- Boolean = True or False
Required Fields
These fields are required to initiate a Cardinal Consumer Authentication transaction.
Field Name | Description | Required | Field Definition |
|---|---|---|---|
| Amount | Unformatted total transaction amount without any decimalization. Example: $100.00 = 10000, $123.67 = 12367, $.99 = 99 | Y | N(48) |
| BillingAddress1 | Consumer's billing address information. NOTE: If the value passed is greater than the field definition, it will be truncated to the maximum allowable value. | Y | AN(50) |
| BillingCity | Consumer's city on their billing address. NOTE: If the value passed is greater than the field definition, it will be truncated to the maximum allowable value. | Y | AN(50) |
| BillingCountryCode | Consumer's numeric 3-digit ISO 3166-1 country code. Example: United States = 840 | Y | N(3) |
| BillingFirstName | Consumer's first name. | Y | AN(22) |
| BillingLastName | Consumer's last name. | Y | AN(22) |
| BillingPostalCode | Consumer's postal code of their billing address. | Y | AN(16) |
| BillingState | Consumer's state or province of their billing address. NOTE: Should be the country subdivision code defined in ISO 3166-2. | Y | AN(2) |
| CardExpMonth | Card number expiration month. Formatted MM Example: January = 01 | Y | N(2) |
| CardExpYear | Card number expiration year. Formatted YYYY Example: YYYY = 2016 | Y | N(4) |
| CardNumber | Consumer's credit card number. | Y | N(19) |
| CurrencyCode | 3 digit numeric ISO 4217 currency code for the sale amount. | Y | N(3) |
| DFReferenceId | Reference Id that relates to the device data that was previously collected. NOTE: In the Cruise Hybrid Integration, this field will need to match the ReferenceId claim in the JWT or the sessionId from the payments.setupComplete event handler. | Y | AN(50) |
| Consumer's email address. | Y | AN(254) | |
| MobilePhone | Cardholder's mobile phone number. NOTE: This field is required for VISA Brazil extensions. | Y | N(25) |
| ProcessorId | Merchant Processor identification code. This value is assigned to the Merchant by CardinalCommerce. | Y | AN(20) |
| MerchantId | Merchant identification code. This value is assigned to the Merchant by CardinalCommerce. | Y | AN(50) |
| TransactionPwd | A password to secure and verify the transaction originated from Merchant represented by the transaction details. The password value is configured through the Merchant profile. | Y | AN(50) |
| Version | Application message identifier. Current Version - 1.7 | Y | AN(3) |
| TransactionMode | Transaction mode identifier. Identifies the channel the transaction originates from. Available Options: M - Moto (Mail Order Telephone Order) P - Mobile Device R - Retail (Physical Store) S - Computer Device T - Tablet Device | O | A(1) |
| MsgType | cmpi_lookup | Y | AN(50) |
| TransactionType | Identifies the transaction type used for processing. Possible Values: C - Credit Card/Debit Card Authentication | Y | AN(3) |
| OrderNumber | Order Number or transaction identifier from the Merchant commerce website. | Y | AN(50) |
Conditionally Required Fields
The requirements for these fields are driven by the conditions of the transaction.
Field Name | Description | Required | Condition | Field Definition |
|---|---|---|---|---|
| ShippingAddress1 | Consumer's shipping address information. NOTE: If the value passed is greater than the field definition, it will be truncated to the maximum allowable value. | C | Required if information is available. | AN(50) |
| ShippingState | Consumer's state or province of their shipping address. NOTE: Should be the country subdivision code defined in ISO 3166-2. | C | Required if information is available. | AN(3) |
| ShippingCity | Consumer's city of their shipping address. NOTE: If the value passed is greater than the field definition, it will be truncated to the maximum allowable value. | C | Required if information is available. | AN(50) |
| ShippingCountryCode | Consumer's 3-digit ISO 3166-1 country code. | C | Required if information is available. | AN(3) |
| ShippingAddress2 | Consumer's shipping address information. NOTE: If the value passed is greater than the field definition, it will be truncated to the maximum allowable value. | C | Required if information is available. | AN(50) |
| ShippingAddress3 | Consumer's shipping address information. NOTE: If the value passed is greater than the field definition, it will be truncated to the maximum allowable value. | C | Required if information is available. | AN(50) |
| ShippingPostalCode | Consumer's postal code of their shipping address. | C | Required if information is available. | AN(16) |
| BillingPhone | Consumer's phone number for billing address. This should be unformatted without hyphens. Example: 222-234-5678 = 2222345678 | C | Required if information is available. | N(20) |
| WorkPhone | Consumer's work phone number. | C | Required if information is available. | N(25) |
| BillingAddress2 | Consumer's billing address information. NOTE: If the value passed is greater than the field definition, it will be truncated to the maximum allowable value. | C | Required if information is available. | AN(50) |
| BillingAddress3 | Consumer's billing address information. NOTE: If the value passed is greater than the field definition, it will be truncated to the maximum allowable value. | C | Required if information is available. | AN(50) |
| AuthenticationIndicator | Indicates the type of Authentication request. 01 - Payment transaction 02 - Recurring transaction 03 - Installment transaction 04 - Add card 05 - Maintain card 06 - Cardholder verification as part of EMV token ID&V | C | Required if not a Payment transaction. | N(2) |
| ProductCode | Merchant product code. Possible Values: PHY - Goods/Service Purchase CHA - Check Acceptance ACF - Account Funding QCT - Quasi-Cash Transaction PAL - Prepaid Activation and Load NOTE: This value defaults to PHY. This field can be used to override that value if applicable. | C | Required is the value if anything other than PHY | AN(3) |
| ThreeDSVersion | This field contains the 3DS version that can be leveraged to force a transaction down the 1.0 rails. Possible Values: 1.0.2 | C | AN(10) | |
OrderId | Centinel generated order identifier. Used to link multiple actions on a single order to a single identifier. Mod-10 compliant and unique BIN range to CardinalCommerce services. | Y | N(16) |
Device Data Information - OPTIONAL
These fields can be passed to Centinel as redundant device data values if Cardinal Cruise JavaScript is unable to collect this device data in real-time.
Field Name | Description | Required | Field Definition | |
|---|---|---|---|---|
| BrowserJavaEnabled | A Boolean value that represents the ability of the cardholder browser to execute Java. Value is returned from the navigator.javaEnabled property. Possible Values: True False | O | Boolean | |
| BrowserHeader | The exact content of the HTTP accept headers sent from the cardholder's browser. Example: text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8 | O | AN(2048) | |
| BrowserLanguage | Value represents the browser language as defined in IETF BCP47 . Example: en-US | O | AN(8) | |
| BrowserColorDepth | Value represents the bit depth of the color palette for displaying images, in bits per pixel Example: 24 | O | AN(2) | |
| BrowserScreenHeight | Total height of the Cardholder's scree in pixels Example: 864 | O | AN(6) | |
| BrowserScreenWidth | Total width of the cardholder's screen in pixels. Example: 1536 | O | AN(6) | |
| BrowserTimeZone | Time difference between UTC time and the cardholder browser local time, in minutes Example: 300 | O | AN(5) | |
| UserAgent | The 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/71.0.3578.98 Safari/537.36 | O | AN(2048) | |
| IPAddress | The IP address of the Consumer. Example: IPv4 address: <IPAddress>1.12.123.255</IPAddress> Pv6 address: <IPAddress>2011:0db8:85 a3:0101:0101:8a2e:03 70:7334</IPAddress> | O | AN(45) | |
| DeviceChannel | Determines the channel that the transaction came through. Possible Values: SDK Browser 3RI NOTE: Cardinal will dynamically set SDK when using the Cardinal Mobile SDK or Browser when customer is using our Cardinal Cruise JavaScript. Client will need to set 3RI for Merchant Initiated or 3RI transactions. When using this field in addition to Cardinal Cruise JavaScript, the value should be set to Browser. | O | AN(10) | |
| BrowserJavascriptEnabled | A Boolean value that represents represents the ability of the cardholder browser to execute JavaScript. Possible Values: True False | Y | Boolean |
Risk Information - OPTIONAL
These fields can be passed to the issuer to use in risk-based authentication.
| Field Name | Description | Required | Field Definition |
|---|---|---|---|
| ShippingMethodIndicator | Indicates shipping method chosen for the transaction. Possible Values: 01 - Ship to cardholder billing address 02 - Ship to another verified address on file with merchant 03 - Ship to address that is different than billing address 04 - Ship to store (store address should be populated on request) 05 - Digital goods 06 - Travel and event tickets, not shipped 07 - Other | O | N(2) |
| DeliveryTimeframe | Indicates the delivery timeframe. Possible Values: 01 - Electronic delivery 02 - Same day shipping 03 - Overnight shipping 04 - Two or more day shipping | O | N(2) |
| DeliveryEmail | For electronic delivery, email address to which the merchandise was delivered. | O | AN(254) |
| ReorderIndicator | Indicates whether the cardholder is reordering previously purchased merchandise. Possible Values: 01 - First time ordered 02 - Reordered | O | N(2) |
| PreOrderIndicator | Indicates whether cardholder is placing an order with a future availability or release date. Possible Values: 01 - Merchandise available 02 - Future availability | O | N(2) |
| PreOrderDate | Expected date that a pre-ordered purchase will be available. Format: YYYYMMDD | O | N(8) |
| GiftCardAmount | The purchase amount total for prepaid gift cards in major units. Example: $123.45 USD = 12345 | O | N(15) |
| GiftCardCurrencyCode | ISO 4217 currency code for the gift card purchased. | O | N(3) |
| GiftCardCount | Total count of individual prepaid gift cards purchased. NOTE: The value passed in should be exactly 2-digit numeric. | O | N(2) |
| Cardholder Information | |||
| AccountAgeIndicator | Length of time cardholder has had account. Possible Values: 01 - No Account 02 - Created during transaction 03 - Less than 30 days 04 - 30-60 days 05 - More than 60 days | O | N(2) |
| AccountCreateDate | Date the cardholder opened the account. Format: YYYYMMDD | O | N(8) |
| AccountChangeIndicator | Length of time since the last change to the cardholder account. This includes shipping address, new payment account or new user added. Possible Values: 01 - Changed during transaction 02 - Less than 30 days 03 - 30-60 days 04 - More than 60 days | O | N(2) |
| AccountChangeDate | Date the cardholder's account was last changed. This includes changes to the billing or shipping address, new payment accounts or new users added. Format: YYYYMMDD | O | N(8) |
| AccountPwdChangeIndicator | Length of time since the cardholder changed or reset the password on the account. Possible Values: 01 - No change 02 - Changed during transaction 03 - Less than 30 days 04 - 30-60 days 05 - More than 60 days | O | N(2) |
| AccountPwdChangeDate | Date the cardholder last changed or reset password on account. Format: YYYYMMDD | O | N(8) |
| ShippingAddressUsageIndicator | Indicates when the shipping address used for transaction was first used. Possible Values: 01 - This transaction 02 - Less than 30 days 03 - 30-60 days 04 - More than 60 days | O | N(2) |
| ShippingAddressUsageDate | Date when the shipping address used for this transaction was first used. Format: YYYYMMDD | O | N(8) |
| TransactionCountDay | Number of transactions (successful or abandoned) for this cardholder account within the last 24 hours. | O | N(3) |
| TransactionCountYear | Number of transactions (successful or abandoned) for this cardholder account within the last year. | O | N(3) |
| AddCardAttempts | Number of add card attempts in the last 24 hours. | O | N(3) |
| AccountPurchases | Number of purchases with this cardholder account during the previous six months. | O | N(4) |
| FraudActivity | Indicates whether the merchant experienced suspicious activity (including previous fraud) on the account. Possible Values: 01 - No suspicious activity 02 - Suspicious activity observed | O | N(2) |
| ShippingNameIndicator | Indicates if the cardholder name on the account is identical to the shipping name used for the transaction. Possible Values: 01 - Account name identical to shipping name 02 - Account name different than shipping name | O | N(2) |
| PaymentAccountIndicator | Indicates the length of time that the payment account was enrolled in the merchant account. Possible Values: 01 - No account (guest checkout) 02 - During the transaction 03 - Less than 30 days 04 - 30-60 days 05 - More than 60 days | O | N(2) |
| PaymentAccountAge | Date the payment account was added to the cardholder account. Format: YYYYMMDD | O | N(8) |
| Requester Authentication | |||
| AlternateAuthenticationMethod | Mechanism used by the cardholder to authenticate to the 3DS requester. Possible Values: 01 - No authentication occurred (e.g. Guest Checkout) 02 - Login to the cardholder account at the Merchant system using Merchant system credentials 03 - Login to the cardholder account at the Merchant system using a Federated ID 04 - Login to the cardholder account at the Merchant system using Issuer credentials 05 - Login to the cardholder account at the Merchant system using third-party authentication 06 - Login to the cardholder account at the Merchant system using FIDO Authenticator | O | N(2) |
| AlternateAuthenticationDate | Date and time in UTC of the cardholder authentication. Format: YYYYMMDDHHMM | O | N(12) |
| AlternateAuthenticationData | Data that documents and supports a specific authentication process that was sent in the AlternateAuthenticationMethod field. | O | AN(2048) |
| Requester Prior Authentication | |||
| PriorAuthenticationData | This field carry data that the ACS can use to verify the authentication process. | O | AN(2048) |
| PriorAuthenticationMethod | Mechanism used by the Cardholder to previously authenticate to the 3DS Requestor. 01 - Frictionless authentication occurred by ACS 02 - Cardholder challenge occurred by ACS 03 - AVS verified 04 - Other issuer methods 05-79 - Reserved for EMVCo future use (values invalid until defined by EMVCo) 80-99 - Reserved for DS use | O | N(2) |
| PriorAuthenticationTime | Date and time in UTC of the prior cardholder authentication. Format YYYYMMDDHHMM | O | N(12) |
| PriorAuthenticationRef | This data element contains a ACS Transaction ID for a prior authenticated transaction For example, the first recurring transaction that was authenticated with the cardholder | O | AN(36) |
Additional and Override Fields
Additional data that can be sent into our Centinel platform to override fields or convey to the issuer the alternative authentication methods that the consumer used.
| Field Name | Description | Required | Field Definition |
|---|---|---|---|
| Override Fields | |||
| ChallengeIndicator | Indicates whether a challenge is requested for this transaction. Possible Values: 01 - No preference 02 - No challenge requested 03 - Challenge requested (3DS Requestor Preference) 04 - Challenge requested (Mandate) 05 - No challenge requested (transactional risk analysis is already performed) 06 - No challenge requested (Data share only) 07 - No challenge requested (strong consumer authentication is already performed) 08 - No challenge requested (utilise whitelist exemption if no challenge required) 09 - Challenge requested (whitelist prompt requested if challenge required) NOTE: Cardinal will default to 01 on Merchant Configuration - can be overridden by the merchant. EMV® 3-D Secure version 2.1.0 supports values 01-04. Version 2.2.0 supports values 01-09. | O | N(2) |
| ACSWindowSize | An override field that a merchant can pass in to set the challenge window size to display to the end cardholder. The ACS will reply with content that is formatted appropriately to this window size to allow for the best user experience. The sizes are width x height in pixels of the window displayed in the cardholder browser window. 01 - 250x400 02 - 390x400 03 - 500x600 04 - 600x400 05 - Full page NOTE: This is a 2.0 browser required field, Cardinal will choose the best possible option based on the device data collected or set a default value in the merchant's configuration. This value will override both of those. | O | N(2) |
| MerchantName | Override the Merchant name configured in the Centinel Merchant profile. | O | AN(25) |
| AcquirerId | Override the acquiring institution identification code (the Acquirer BIN) that is currently configured in the Centinel profile. TIP: This field is numeric only. | O | N(6) |
| AcquirerMerchantId | Override the Acquirer Merchant identifier configured in the Merchant's profile. | O | AN(25) |
| AcquirerPassword | The value in this field is used to facilitate Merchant Authentication File (MAF) authentication processing. NOTE: This is required only when processing within certain VISA regions. If this value is passed it will override the password value configured on the Merchant's configuration profile. | O | AN(50) |
| RequestorId | This value is a Directory Server assigned 3DS Requestor ID value, each DS may provide a unique ID. NOTE: This is a 2.0 value only and if passed will override the Requestor Id value that is configured on the Merchant's profile. | O | AN(35) |
| RequestorName | This value is a Directory Server assigned 3DS Requestor Name value, each DS may provide a unique ID. NOTE: This is a 2.0 value only and if passed will override the Requestor Name value that is configured on the Merchant's profile. | O | AN(40) |
| CategoryCode | Merchant category code (MCC) NOTE: This field is required by Mastercard and Visa Brazil extensions. | O | N(4) |
| CountryCodeOverride | Override the country code configured in the Centinel Merchant profile. | O | N(3) |
| MessageCategory | Category of the message for a specific use case. Possible Values: 01 - PA 02 - NPA 03-79 - Reserved for EMVCo future use (values invalid until defined by EMVCo) 80-99 - Reserved for DS use NOTE: Default is payment (01). Configured on Merchant account, or can be overridden on transaction. | O | N(2) |
| ProductCode | Merchant product code. Possible Values: AIR - Airline GEN - General Retail DIG - Digital Goods SVC - Services RES - Restaurant TRA - Travel DSP - Cash Dispensing REN - Car Rental GAS - Fueld LUX - Luxury Retail ACC - Accommodation Retail TBD - Other | O | AN(3) |
| MerchantUrl | Override the Merchant URL configured in the Centinel Merchant profile. | O | AN(2048) |
| Tokenization | |||
| Alias | An alias that uniquely identifies the account. NOTE: This field is required if Tokenization is enabled in the Merchant profile settings. | O | AN(128) |
| Token | The third party token that will be used to process the transaction in place of the actual card number. NOTE: This field is required if Tokenization is enabled in the Merchant profile setting AND the Merchant is using a third party token in place of the Cardinal token. | O | AN(100) |
| SDK | |||
| SdkMaxTimeout | This field indicates the maximum amount of time for all 3DS 2.0 messages to be communicated between all components (in minutes). Possible Values: Greater than or equal to 05 (05 is the minimum timeout to set) Cardinal Default is set to 15 NOTE: This field is a required 3DS 2.0 field and Cardinal sends in a default of 15 if nothing is passed | O | N(2) |
| General | |||
| BillingFullName | Consumer's billing name. This field can be used by systems that do not support separate field names and is used in place of the BillingFirstName, BillingMiddleName and BillingLastName fields. NOTE: If the value passed is greater than the field definition, it will be truncated to the maximum allowable value. | O | AN(45) |
| AddressMatch | Indicates whether cardholder billing and shipping addresses match. Possible Values: Y - Shipping address matches billing address N - Shipping address does not match billing address | O | AN(1) |
| AccountId | Additional cardholder account information. | O | AN(64) |
| BrowserHeader | The exact content of the HTTP accept headers as sent to the 3DS Requestor from the Cardholder’s browser. | O | AN(2048) |
| CardType | Type of cards used for purchase. Possible Values: VSA - Visa MSC - Mastercard VSD - Visa Delta/Debit (UK) VSE - Visa Electron MAE - Maestro (UK, Spain & Austria) AMX - American Express DSC - Discover DIN - Diners CBLA - Carte Blanche JCB - JCB ENR - EnRoute JAL - JAL CTB - Carte Bleue DNK - Dankort CSI - CartaSi EAN - Encoded Account Number UATP - UATP MAEI - Maestro (International) CB - Cartes Bancaires | O | AN(20) |
| Custom_X | A custom field used to accept merchant data to be used within our rules engine. Limit of 5 Custom fields per request. Example: Custom_1, Custom_2, etc. for multiple custom fields | O | AN(175) |
| IPAddress | The IP address of the Consumer. Example: IPv4 address: <IPAddress>1.12.123.255</IPAddress> Pv6 address: <IPAddress>2011:0db8:85 a3:0101:0101:8a2e:03 70:7334</IPAddress> | O | AN(45) |
| Item_Desc_X | Brief description of item. | O | AN(256) |
| Item_Name_X | Name of item purchased. | O | AN(128) |
| Item_Price_X | Unformatted price of item X transaction amount without any decimalization. | O | N(20) |
| Item_Quantity_X | Number of items purchased. | O | N(20) |
| Item_ShippingAddress1_X | Address where item will be shipped. | O | AN(50) |
| Item_ShippingAddress2_X | Address where item will be shipped. | O | AN(128) |
| Item_ShippingCity_X | City where item will be shipped. | O | AN(50) |
| Item_ShippingCountryCode_X | Country where item will be shipped. | O | AN(2) |
| Item_ShippingDestination_X | Shipping destination of item. Example: Commercial, Residential, Store | O | AN(50) |
| Item_ShippingFirstName_X | Consumer's first name. | O | AN(128) |
| Item_ShippingLastName_X | Consumer's last name. | O | AN(128) |
| Item_ShippingMiddleName_X | Consumer's middle name. | O | AN(128) |
| Item_ShippingPhone_X | Phone number where item will be shipped. | O | N(20) |
| Item_ShippingPostalCode_X | Postal code where item will be shipped. | O | AN(16) |
| Item_ShippingState_X | State where item will be shipped. | O | AN(3) |
| Item_SKU_X | Item SKU number. | O | AN(20) |
| MerchantReferenceNumber | Merchant specified data. | O | AN(20) |
| OrderDescription | Brief Description of items purchased. | O | AN(256) |
| ShippingDestination_X | Destination to where the item will be shipped. Example: Commercial, Residential, Store | O | AN(25) |
| ShippingFirstName | Consumer's first name. | O | AN(50) |
| ShippingLastName | Consumer's last name. | O | AN(50) |
| ShippingMiddleName | Consumer's middle name. | O | AN(50) |
| ShippingPhone | Consumer's phone number for shipping address. This should be unformatted without hyphens. Example: 222-234-5678 = 2222345678 | O | N(20) |
| TaxAmount | Unformatted tax amount without any decimalization. Example: $100.00 = 10000, $123.67 = 12367, $.99 = 99 | O | N(20) |
| OverridePaymentMethod | Override the payment method. Possible Values: NA - Not Applicable CR - Credit DB - Debit VSAVR - Visa Vale Refeicao VSAVA - Visa Vale Alimentacao | O | AN(10) |
| UserAgent | The exact content of the HTTP user agent header. | O | AN(500) |
| ShippingFullName | Consumer's shipping name. This field can be used by systems that do not support separate field names and is used in place of the ShippingFirstName, ShippingMiddleName and ShippingLastName fields. | O | AN(150) |
| DecoupledMaxTime | Indicates the maximum amount of time that the 3DS Requestor will wait for an ACS to provide the results of a Decoupled Authentication transaction (in minutes). Possible Values: Numeric values between 1 and 10080 accepted. NOTE: Decoupled authentication is not supported at this time. | O | N(5) |
| DecoupledIndicator | Indicates whether the 3DS Requestor requests the ACS to utilise Decoupled Authentication and agrees to utilise Decoupled Authentication if the ACS confirms its use. Possible Values: Y - Decoupled Authentication is supported and preferred if challenge is necessary N - Do not use Decoupled Authentication Default Value: N NOTE: If the element is not provided, the expected action is for the ACS to interpret as N, DO NOT use Decoupled Authentication. Decoupled authentication is not supported at this time. | O | AN(1) |