Development Notice

The Cardinal Virtual SDK is currently in Beta and is subject to changes within the codebase and documentation. Please reach out to your AE if there are any questions.

Overview

Universal Reference Guide

The documentation below covers many communication methods when it comes to talking with the Cardinal systems. There may be fields that include notes for "Cruise Standard" and "Cruise Hybrid" that may not be applicable to this integration.

This is the first transaction of the Lookup/Authenticate pair that is used to process the Consumer Authentication transaction request. The TransactionType value represented on the transaction request will dictate how the transaction will be processed.

The CardNumber value dictates the program that will be used in processing the transaction. Currently, Verified by Visa, Mastercard SecureCode/Identity Check, American Express SafeKey, Discover ProtectBuy, JCB J/Secure and Diners Club ProtectBuy are supported by Centinel.

Merchants must ensure that Cardinal has the proper Acquiring Merchant Identification Number and corresponding Acquiring Bank Identification Numbers (BINs) configured in your account. The identifiers may vary based on card acceptance with your acquirer and processor. Please contact us to verify your credentials.

TLS Global Mandate

It is important to note that the Cardinal Cruise integration of Javascript, specifically Songbird.js, uses TLS 1.2 cipher suites and protocols and above. If you are currently using a deprecated TLS cipher suite and protocol (Ie: TLS 1.0 or 1.1) you will be required to upgrade to the latest and approved TLS 1.2 cipher suites and protocols. You can find the approved cipher suite list here.

Virtual SDK Lookup Request Example

Lookup Request Example

<CardinalMPI>
	<ProcessorId>PID</ProcessorId>
	<MerchantId>MID</MerchantId>
	<TransactionPwd>TransactionPwd</TransactionPwd>
	<Version>1.7</Version>
	<MsgType>cmpi_lookup</MsgType>
	<TransactionType>C</TransactionType>
	<OrderNumber>abc123doerayme</OrderNumber>
	<AcctNumber>4012##88</AcctNumber>
	<PurchaseAmount>1400</PurchaseAmount>
	<PurchaseCurrency>840</PurchaseCurrency>
	<CardNumber>4012##88</CardNumber>
	<CardExpMonth>09</CardExpMonth>
	<CardExpYear>2020</CardExpYear>
	<BillingCity>Mentor</BillingCity>
	<BillingAddress1>8100 Tyler Blvd</BillingAddress1>
	<BillingAddress2></BillingAddress2>
	<BillAddrPostCode>44060</BillAddrPostCode>
	<BillingCountryCode>840</BillingCountryCode>
	<BillAddrState>OH</BillAddrState>
	<CardholderName>
		<BillingFirstName>John Doe</BillingFirstName>
		<BillingLastName>John Doe</BillingLastName>
		<BillingFullName>John Doe</BillingFullName>
	</CardholderName>
	<ShippingCity>44060</ShippingCity>
	<ShippingAddress1>8100 Tyler Blvd</ShippingAddress1>
	<ShippingAddress2></ShippingAddress2>
	<ShippingPostalCode>44060</ShippingPostalCode>
	<BillingPostalCode>44060</BillingPostalCode>
	<BillingState>OH</BillingState>
	<ShippingState>OH</ShippingState>
	<Email>cardinal.mobile.test@gmail.com</Email>
	<ShippingCountryCode>840</ShippingCountryCode>
	<Amount>1400</Amount>
    <AcquirerId>12345</AcquirerId>
	<AcquirerMerchantId>1234</AcquirerMerchantId>
	<CategoryCode>5712</CategoryCode>
	<CountryCodeOverride>840</CountryCodeOverride>
	<MerchantName>Store Front</MerchantName>
	<MessageCategory>01</MessageCategory>
	<ProductCode>01</ProductCode>
	<CurrencyCode>826</CurrencyCode>
	<AuthenticationInfo></AuthenticationInfo>
	<OverridePaymentMethod></OverridePaymentMethod>
	<AddressMatch></AddressMatch>
	<Installment></Installment>
	<MerchantRiskInfo></MerchantRiskInfo>
	<RecurringEnd></RecurringEnd>
	<RecurringFrequency></RecurringFrequency>
	<SourceVersion>2.10</SourceVersion>
	<AuthenticationIndicator>01</AuthenticationIndicator>
	<MerchantUrl>http://www.cardinalcommerce.com</MerchantUrl>

    <!-- Virtual SDK Lookup Request Fields  -->
	<DeviceChannel>sdk</DeviceChannel>
	<ChallengeRenderInterface>03</ChallengeRenderInterface>
	<ChallengeRenderType>01</ChallengeRenderType>
	<ChallengeRenderType>02</ChallengeRenderType>
	<ChallengeRenderType>03</ChallengeRenderType>
	<ChallengeRenderType>04</ChallengeRenderType>
	<ChallengeRenderType>05</ChallengeRenderType>
	<SdkMaxTimeout>25</SdkMaxTimeout>
	<SdkTransId>78d42267-6d59-486e-8dba-3a3f427cf375</SdkTransId>
	<SdkEncData>SdkEncData</SdkEncData>
    <SdkEphemPubKey>{"kty":"EC","crv":"P-256","x":"qkStspK65NrI8Dej0oRYGkoEvmWvl18JY_q8FKP20ag","y":"w9HVQNM02zLJ0YAcMaPUCybnAelPpjHKZqUu7aRjZkE"}</SdkEphemPubKey>
	<SdkAppId>dd86e2ba-626e-4a3e-9c03-324940d47e72</SdkAppId>
	<SdkReferenceNumber>3DS_LOA_SDK_CACC_020100_00063</SdkReferenceNumber>
</CardinalMPI>

Virtual SDK Required Fields

The table below includes the required fields for the Virtual SDK implementation. These have been separated from the rest of the lookup documentation as they are specific to the Virtual SDK.

Virtual SDK Lookup Request Fields (Required)

Field Name	Description	Required	Field Definition
SdkEphemPubKey	The public key component of the ephemeral key pair generated by the 3DS SDK and used to establish session keys between the 3DS SDK and ACS.	Y	JSON Object(6000)
SdkTransId	Universally unique transaction identifier assigned by the 3DS SDK to identify a single transaction.	Y	String(36)
SdkAppId	Universally Unique ID created upon all installations and updates of the 3DS Requestor App on a Consumer Device. This will be newly generated and stored by the 3DS SDK for each installation or update.	Y	String(36)
SdkReferenceNumber	Identifies the vendor and version for the 3DS SDK that is integrated into a 3DS Requestor App, assigned by EMVCo when the 3DS SDK is approved.	Y	String(32)
SdkEncData	JWE object containing data encrypted by the SDK for the DS to decrypt.	Y	String(64000)
SdkMaxTimeout	Maximum time the SDK will wait for all message (in minutes). Accepted Values: Greater than or = 05	Y	N(2)
DeviceChannel	Determines the channel that the transaction came through. Possible Values: SDK NOTE: The value of SDK is required for Cardinal Virtual SDK transactions	Y	AN(10)
DeviceRenderOptions	Defines the SDK UI types that the device supports for displaying specific challenge user interfaces within the SDK	N	JSON Object

Virtual SDK Lookup Response Fields

Field Name	Description	Required	Field Definition
ACSSignedContent	Contains the JWS object created by the ACS and returned on the ARes message. The JWS object contains the following data: ACS URL ACS Ephemeral Public Key SDK Ephemeral Public Key	C	String(5000)
ACSReferenceNumber	Unique identifier assigned by the EMVCo secretariat upon testing and approval	C	String(32)
ACSTransactionID	Unique transaction identifier assigned by the ACS to identify a single transaction.	C	String(36)
ThreeDSServerTransactionId	Unique transaction identifier assigned by the 3DS Server to identify a single transaction.	C	String(36)

Example

Virtual SDK Lookup Request Example

<CardinalMPI>
	<ProcessorId>123</ProcessorId>
	<MerchantId>MERCHANT_ID</MerchantId>
	<TransactionPwd>123456789</TransactionPwd>
	<Version>1.7</Version>
	<MsgType>cmpi_lookup</MsgType>
	<TransactionType>C</TransactionType>
	<OrderNumber>abc123doerayme</OrderNumber>
	<AcctNumber>4012000000010288</AcctNumber>
	<PurchaseAmount>0</PurchaseAmount>
	<PurchaseCurrency>840</PurchaseCurrency>
	<CardNumber>4012000000010288</CardNumber>
	<CardExpMonth>09</CardExpMonth>
	<CardExpYear>2020</CardExpYear>
	<BillingCity>Mentor</BillingCity>
	<BillingAddress1>8100 Tyler Blvd 100</BillingAddress1>
	<BillingAddress2></BillingAddress2>
	<BillAddrPostCode>44094</BillAddrPostCode>
	<BillingCountryCode>840</BillingCountryCode>
	<BillAddrState>OH</BillAddrState>
	<CardholderName>
		<BillingFirstName>John Doe</BillingFirstName>
		<BillingLastName>John Doe</BillingLastName>
		<BillingFullName>John Doe</BillingFullName>
	</CardholderName>
	<ShippingCity>44094</ShippingCity>
	<ShippingAddress1>8100 Tyler Blvd 100</ShippingAddress1>
	<ShippingAddress2></ShippingAddress2>
	<ShippingPostalCode>44094</ShippingPostalCode>
	<DFReferenceId></DFReferenceId>
	<BillingPostalCode>44094</BillingPostalCode>
	<BillingState>OH</BillingState>
	<ShippingState>OH</ShippingState>
	<Email>cardinal.mobile.test@gmail.com</Email>
	<ShippingCountryCode>840</ShippingCountryCode>
	<Amount>0</Amount>
	<CurrencyCode>840</CurrencyCode>
	<SourceVersion>2.10</SourceVersion>
	<ChallengeRenderInterface>01</ChallengeRenderInterface>
	<ChallengeRenderType>01</ChallengeRenderType>
	<ChallengeRenderType>02</ChallengeRenderType>
	<ChallengeRenderType>03</ChallengeRenderType>
	<ChallengeRenderType>04</ChallengeRenderType>
	<ChallengeRenderType>05</ChallengeRenderType>
	<ThreeDSVersion>2.1.0</ThreeDSVersion>
	<DeviceChannel>sdk</DeviceChannel>
	<MerchantUrl>http://www.cardinalcommerce.com</MerchantUrl>
	<AcquirerId>88888</AcquirerId>
	<AcquirerMerchantId>89111</AcquirerMerchantId>
	<CategoryCode>5712</CategoryCode>
	<CountryCodeOverride>840</CountryCodeOverride>
	<MerchantName>Sid</MerchantName>
	<MessageCategory>01</MessageCategory>
	<ProductCode>01</ProductCode>

	<SdkMaxTimeout>25</SdkMaxTimeout>
	<AuthenticationIndicator>01</AuthenticationIndicator>
	<SdkTransId>e1c72b78-8534-49d2-ae18-1e9050e13c61</SdkTransId>
	<SdkEncData>ENCRYPTED DATA</SdkEncData>
	<SdkEphemPubKey>{"kty":"EC","crv":"P-256","x":"_NohgCJdJMwqAJLf0KvBibZk-kiiBLfVr1aFjq_MXsg","y":"xVWNBHhJpaMb8G6FMwSiD7CyxGji6GYMSyW1A380wuM"}</SdkEphemPubKey>
	<SdkAppId>6d9f1f0f-b15c-4200-a2d8-953181edfc6e</SdkAppId>
	<SdkReferenceNumber>SdkReferenceNumber</SdkReferenceNumber>
</CardinalMPI>

Unable to render {include} The included page could not be found.

Copy of Step 2: Submitting & Receiving the Lookup