Page Comparison

Warning

title	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.

Interpreting the Lookup Response

There are two paths you can go down within the flow based on what has been received in the Lookup Response. Those paths are as follows:

Frictionless

Frictionless traction is completed at this point in the flow. There is no challenge necessary and the details needed to complete Step 4: Get the Needed information for Authorization that would have been passed back to you in this response.

Below is an example of a frictionless response:

Code Block

theme	Emacs
title	Frictionless Example
linenumbers	true
collapse	true

<CardinalMPI>
    <ErrorNo>0</ErrorNo>
    <TransactionId>Ndh6c5JGNixB1ay86FE0</TransactionId>
    <Payload></Payload>
    <ErrorDesc></ErrorDesc>
    <Cavv>AJkBA2aQCJFWcHJJJZAIAAAAAAA=</Cavv>
    <PAResStatus>Y</PAResStatus>
    <Enrolled>Y</Enrolled>
    <ACSTransactionId>de367f13-2392-41d8-8796-93a0c9d91219</ACSTransactionId>
    <EciFlag>05</EciFlag>
    <ACSUrl></ACSUrl>
    <ThreeDSServerTransactionId>50f03fe5-b924-4f67-9935-37343ab43f94</ThreeDSServerTransactionId>
    <CardBin>401200</CardBin>
    <ACSReferenceNumber>EMVACSVENDOR-1</ACSReferenceNumber>
    <CardBrand>VISA</CardBrand>
    <DSTransactionId>2f4a3a4e-fc91-4b8d-8de5-0ea76e50c6c5</DSTransactionId>
    <ThreeDSVersion>2.1.0</ThreeDSVersion>
    <OrderId>8000141658132035</OrderId>
    <ChallengeRequired></ChallengeRequired>
    <SignatureVerification>Y</SignatureVerification>
</CardinalMPI>

Challenge

A challenge is required when indicated by the lookup response. An example of that response can be seen below:

Code Block

theme	Emacs
title	Challenge Example
linenumbers	true
collapse	true

<CardinalMPI>
    <ErrorNo>0</ErrorNo>
    <TransactionId>1kMxq83FJB1IXQ0bB1I0</TransactionId>
    <Payload></Payload>
    <ErrorDesc></ErrorDesc>
    <Cavv></Cavv>
    <PAResStatus>C</PAResStatus>
    <Enrolled>Y</Enrolled>
    <ACSTransactionId>6addd7fb-151e-45c8-9d26-1a0633028717</ACSTransactionId>
    <EciFlag>07</EciFlag>
    <ACSUrl></ACSUrl>
    <ThreeDSServerTransactionId>b16d8334-d5b8-43c5-9097-d9b2785ddfbc</ThreeDSServerTransactionId>
    <CardBin>401200</CardBin>
    <ACSSignedContent>eyJ4NWMiOlsiTUlJQ3REQ0NBWnlnQXdJQkFnSUVXakZyMFRBTkJna3Foa2lHOXcwQkFRc0ZBREFjTVJvd0dBWURWUVFEREJGVFpXeG1VMmxuYm1Wa1FVTlRWR1Z6ZERBZUZ3MHhOekV5TVRNeE9EQTFNRFZhRncweE9ERXlNVE14T0RBMU1EVmFNQnd4R2pBWUJnTlZCQU1NRVZObGJHWlRhV2R1WldSQlExTlVaWE4wTUlJQklqQU5CZ2txaGtpRzl3MEJBUUVGQUFPQ0FROEFNSUlCQ2dLQ0FRRUEzOGJnM29JNFwvNDRkMFNPajVhUnpFQmM3WXlKUnAwYXA4eDUwQUkyYVZHZ0pZNFlHclNlbG85eGtSemNZWXc4WDRKZWU3SERVMms2V29JV1pvZWdjT0hoN1JBUjROT0FCWlZNbHpqZW13b29KN1c2QXRuaW1KQ3FWZkVOUXV3aUFLWkdUcWYyTEdpQ29WTDFyZ0huUGhWb0VUeUNpd2N1NFVQWWQ3TWJDU0gxdUNlZStuYklhZ3lGdDVuTEdlUVh4aHRMd2FReG55ZE92YkdxbU1UMUJvaHViVHJHOU9LTklxUVE4VFQzOVFNUml3TWNJVkVGQ2p3dWIwZU5taXM3OENmeTZxdjNLUzNiU2htVW9TUGJJS3A1ZklNWkxNRTF4cXhMUkQ3UzlHR2FCR2llV2xpWlVzMmZZcHZ4MmFpM1JyTmNjdFhPMHIrWjFWMTZOVE5oS0V3SURBUUFCTUEwR0NTcUdTSWIzRFFFQkN3VUFBNElCQVFDbE1ZRHhieXRHT2M3VVAwcHpJN3FjdUNaM0NPMXJuYW0rWkw1YkZmdjhUUlZJYms3YW51YlwvaE01eElvYlZjSmxLcUhMK1N1U3ZRWDRTeXFqVGNsNkg5MVBnME5IVUd5OHhzNVwvY2dZVjloVEZYRDBNbm51SDkwdWJ6Y1VWbWEzWTZuK0lXTGRcL0lDcFRKenVcL2lJZWNPcTdmT2VGNUpFQVR5ZGREMnhzVWJuSXdNOUM5SVFkcWtRVnliRGJQVzZKRG1Nc1pRNzZDQjRVbGhJOVhLK1JEMW85UmlaWHBuWVg0OEVFVGhOYzhQanpmVE1qT2pkeUdUSktIUnNycWMrZzMyVjRiWDc1U3o0a1RxM3RaRERYczJKVUpxWXZxMU9oblZzdGhIbnEwdEhYdFRnNWpZYmlIaXphUmZOWlk3NEM4SXhPT3FSZ3N0U1VrSkU0SWM2bjhyIl0sImFsZyI6IlBTMjU2In0.eyJhY3NVUkwiOiJodHRwczpcL1wvYWNzdjJzdGFnLmNhcmRpbmFsY29tbWVyY2UuY29tXC9WMVwvVGhyZWVEU2VjdXJlMlwvQXBwXC9DaGFsbGVuZ2VcL0NoYWxsZW5nZSIsImFjc0VwaGVtUHViS2V5Ijp7Imt0eSI6IkVDIiwiY3J2IjoiUC0yNTYiLCJ4IjoibnQydXNJY2llalpmT08wWEJVb3dnNjQ0cWxTWFJzSHIyZVFuOG1BekgyOCIsInkiOiJzdkZLZ1k1VXNpY25ic1dBMUtLSjZyOThad0tySHpaNEpYRUxuTEIySmdnIn0sInNka0VwaGVtUHViS2V5Ijp7Imt0eSI6IkVDIiwiY3J2IjoiUC0yNTYiLCJ4IjoiX1Z4REJMc2dOSjAwVHBleUlyalBRX2t1MGZvSnFLQmh3V3doUEl1Rks4MCIsInkiOiJGWElzRTB5cTFlamgyay1NLVZHRTE0dkZLVk4xc29SX3k0dUI4eHhFejhFIn19.Xfv_B-L_VyW5IDjjkwACHbJGgyvrP5gPf_Fqu7mox3j5u3ZsbzHAeD3TRFlBfQwM2cHXYobFZqKu7rrwkUyyM1pDY6U6iEa9GUGxfQOVSblEpWYQv8iGNjn52F2hST3F5jrTNlubR6tVd18PHpe3FUO8xzTres9uj-7mgcPgscGtnUkrfQh-wO5awMJqFEK-pAW8LhswtE1elQN7TcV63JBXUBgfXJ1WKZ3I1mHHPbOshJFtcNhxYHfwGG30MdE6_-EW8FaIukoypa8SHjMyvc4QBPz83DNiomj7v4CwDzMyV2-TR7XVXyV4_HVDFaKFXdV2PaCrvSrkJdVJRixZGA</ACSSignedContent>
    <ACSReferenceNumber>EMVACSVENDOR-1</ACSReferenceNumber>
    <CardBrand>VISA</CardBrand>
    <DSTransactionId>1cb6463d-1585-4926-9920-049029e76b98</DSTransactionId>
    <AuthenticationType>02</AuthenticationType>
    <ThreeDSVersion>2.1.0</ThreeDSVersion>
    <OrderId>8000380308210987</OrderId>
    <ChallengeRequired>N</ChallengeRequired>
    <SignatureVerification>Y</SignatureVerification>
</CardinalMPI>

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)

After a response indicates a challenge, we will need to initiate the step up flow.

Initiating the Step Up

Steps of the Step Up

The step-up flow requires the merchant app to complete encryption of the CReq on the consumer's local device. As seen in the flow above, this includes various components that are returned back to the merchant on the cmpi_lookup response. These steps include:

If Enrolled = Y & PAResStatus = C, then generate the secret key using the acsEphemPubKey (from the ACSSignedContent on the Lookup response) and sdkEphemPrivateKey.
Create and send the cmpi_step_up Request
On cmpi_step_up Response, decrypt the Challenge Response (EncCres), use the Cres to paint the challenge screen.
On user input create a Creq and repeat steps 2 & 3 until you get a challengeCompletionInd = Y in the CRes.

Table of Contents

Key:

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 the transaction to determine if it's required)
- O = Optional (Not required but recommended pass)

cmpi_step_up Request

Merchant identification code. This value is assigned to the Merchant by CardinalCommerce50

Field	Description	Required	Condition	Field Definition
MsgType	The name of the message being sent. Possible Value: cmpi_step_up	Y	-	AN(50)
Version	1.7 The application message version	Y	-	AN(3)
TransactionType	Identifies the transaction type used for processing. Possible Value: C - Credit Card/Debit Card Authentication	Y	-	AN(3)	MerchantId	)
Algorithm	The hash algorithm that was used to generate the Signature for the request. Possible Values: SHA-256 SHA-512	Y	-	AN(7)
Identifier	The unique identifier representing the API Key being used to generate the Signature that is specified on the request. This value will be provided by Cardinal at the time the API Key is generated.	Y	-	AN(255)
OrgUnit	The unique organizational unit for which the request is being processed for. Each merchant within the system will be assigned a unique OrgUnit value by Cardinal.	Y	-	AN(	24)
ProcessorId	Merchant Processor identification code Signature	The signature for the request being submitted. This value is assigned to the Merchant by CardinalCommerce generated by hashing the combination of the Timestamp and the API Key.	Y	-	AN( 20 255)
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. Timestamp	The unix epoch time in milliseconds for the point in time that the request is generated. Example: `1467122891960`	Y	-	AN N( 50 13)
TransactionId	Centinel generated transaction identifier. This value links the request message from cmpi_lookup response message. NOTE: The TransactionId is the preferred identifier for linking the StepUp with the Lookup and Authenticate message.	Y	-	AN(20)
EncCReq	Encrypted JWE value containing the challenge request.	Y	-	AN(5000)

Code Block

language	xml
theme	Emacs
title	Step Up Request

<CardinalMPI>
    <MsgType>cmpi_step_up</MsgType>
    <Version>1.7</Version>
    <TransactionType>C</TransactionType>
    <MerchantId>100a<<Algorithm>SHA-512</MerchantId>
    <ProcessorId>100</ProcessorId>
    <TransactionPwd>12345678</TransactionPwd>Algorithm>
	<Identifier>{{API_KEY_IDENTIFIER}}</Identifier>
	<OrgUnit>{{ORG_UNIT_ID}}</OrgUnit>
	<Signature>{{GENERATED_SIGNATURE_VALUE}}</Signature>
	<Timestamp>{{TIMESTAMP}}</Timestamp>
    <TransactionId>CVHQbFIXm2GwX0wZ0cd0</TransactionId>
	<EncCReq>eyJraWQiOiIwZTNmM2M2My1mMTI0LTRlOTktODQ0OC1kMDc2N2VkMzA4NTkiLCJlbmMiOiJBMTI4R0NNIiwiYWxnIjoiZGlyIn0..AAAAAAAAAAAAAAAA.oJqx2g8SPaDN8XQHIxfUoE1O0aRWZxFlLauzUgNrSp9jMrXSIlwOiAQsljAa3rJF8ifM4KYlkrLjkF5w4Z9hkGWA9G8K1_yYASYG3HJlhMoqvG9e4Fu7oh9DPkvo4YpRusHx3NvY5N0HtXLbOWj1orz-UuhmcUhFmFN1jrQmB0CWpzefIJRgD5UIs2AFGWhhhAOqnCqnVdwpyUTgqKy3nN9z8R4mf19Nk8WLeQEX2Xp8Z123HJvfMfCP-J9pUKo4dl6-Leg8IetDJDfJKAdTZLQZ-jhFeafDEBn3xqgNww9A4W_K43oUvanjwSw.pYkaQFyhkFxD89VdcEv0qw</EncCreq>
</CardinalMPI>

cmpi_step_up Response

Field	Description	Required	Condition	Field Definition
StatusCode	Transactions status identifier returned from Centinel. Possible Values: Y - Successful E - Error Note: When an error is received we will populate the ErrorNo & ErrorDesc values	Y	-	AN(1)
ReasonCode	The error code indicating a problem with this transaction.	C	3DS 2.0	N(3)
ReasonDesc	Text and additional detail about the error for this transaction. NOTE: This field concatenates the errorDescription and errorDetail from the authentication response message	C	3DS 2.0	AN(4096)
ErrorNo	Application error number(s). A non-zero value represents the error encountered while attempting to process the message request. NOTE: Multiple error numbers are separated by a comma.	Y	-	AN(255)
ErrorDesc	Application error description for the associated error number(s). NOTE: Multiple error descriptions are separated by a comma. Description for the error returned when ErrorNo is not 0.	Y	-	AN(255)
TransactionId	Centinel transaction identifier. This value identifies the transaction within the Centinel system. To complete the transaction, the value is required to be passed on the StepUp message to link with the Lookup and Authenticate message together. NOTE: The TransactionId is the preferred identifier for linking the Lookup and Authenticate message.	Y	-	AN(20)
EncCRes	Encrypted JWE value containing the challenge response.	Y	-	AN(5000)
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)
SDKFlowType	This field is used to designate the SDK method utilized for the transaction. Example: “Hybrid”	Y	-	N(16)
ChallengeCompletionIndicator	Indicator of the state of the ACS Challenge cycle and whether the challenge has completed or will require additional messages. This will be populated in all CRes messages to convey the current state of the transaction. Note: If set to Y, the ACS will populate the Transaction Status in the CRes Message. The value will be blank as Cardinal will receive these and decrypt from the CRes. Cardinal will pass the field, but it will have a value of zero."	Required on the CRes		A(1)

Code Block

language	xml
theme	Emacs
title	Step Up Response (Challenge Complete)

<CardinalMPI>
    <StatusCode>Y</StatusCode>
    <ReasonCode></ReasonCode>
    <ErrorDesc></ErrorDesc>
    <ErrorNo>0</ErrorNo>
    <Payload></Payload>
    <SDKFlowType>HYBRID</SDKFlowType>
    <TransactionId>G9udYeLvnPlGbTPtMZ30</TransactionId>
    <ReasonDesc></ReasonDesc>
    <OrderId></OrderId>
    <EncCRes>
        eyJraWQiOiI5ZjQzNThiZC1hZjdkLTQwYTItYTlkZC0wYTdiYmVkNmE0MzgiLCJlbmMiOiJBMTI4R0NNIiwiYWxnIjoiZGlyIn0..______________8A.0J7mLx404FZIQzdqimWyKplRoVc0AOSoR-Gppm3-0vZF5ECUUjdBsaKslw0-I2LdAvAiBfLa3XcpUbnjX-XycFg3YX5Gnrtprc-pofNg7v4AFVfXJJwYlCGhZmep7GL3ChWGJnS7xFshWFWSeacVf7byZ6-DRNVEDjC048-HlkU6DH51_X7I4Iurd9lIX44DrtWlTPUFGrdtxmsxKeTuj3Z_aQ-PqnURF-O_4N8glwqhD_wLZbPbdKfo-2DugNMcMHsMt60nk1SVj14aBLrfdnqlySmCZ6oJmV2C0b8wjU1P1gaB_YaJ0z97-sM9n2xJgTCdq9aYWouPWxzYOuC-U5-9vYGuzTjiVc-X6CFrBXHccOz7aUSKREVhXMp4i2rvUrXkK-pkQPl49TrKl31ivYMGN97L7aiRqXRrU5X7O77kMffUkc4Bzf8gzULNRYNiU0LN96a1nutGrQZ-mu4EQXSHpMqGJBQZGM7VlPSMOaMYS_8L4DwUojs2_4jHuwuFIAzwscAhY2uCScSm5J4CZXMEN3HgNN5Evoqko61mt7xRPL4_4rlsK4krpJ90X7Z7gh8-TyVkM7uY2a-NW-9Q6OkoZi7_nkwOFdveP_qGI9HtfFK_6ZzC75fcmPiCsBqpIzjXLkQk8mRc6cVq-q3pk79U9RZRhTdzfDtQYW0OLHpQVxFlI76fM2QQA2QPwOo--HMuE-FmZgcGzejbIgNfYDhv9YrZfn7VaAJ3D3wEaZVfTNvYj1BVmh0Hp4bUcdWZOGndJ9v8UH2f76DXbtjWJrADGyRN-G2P8a5nimuHNvEoTZpzT_hXFivnvPutj5-r06opHfo1OwUSg4ZAOWLhwYmYMcK0AeKIQ6heeivuZ-cLcaMyCrrWt7nx7un7lfB87tnuISltkILntnrAM-xuGYuwv3foH8XKG-TTa0FTO79DNtqj7DDgstQItZG0a_1wx-z-5wBD3ZWUin1WzCcI2zvkXNMhDYD55Bx34sYW-izG90nvRUNOIedxBwgoUgOVW-qVyc5sFyBY0_GHhY4Ga5OI2h1gg85Nd_KymSNt3OAwCIVjmyYhc7XYACvFYify4FyDlrua0WY6p62xPD2OE__iOvVR_vGgPIeLPju289W5zuW2W72Wxn4FtkJGRIiToSikqfLAcr-H7OQ4lb7PqheblDhV7gWPoKDJp8mNXBwiOupKV6kEFW5w1mL8RAQh8Z2nOTsyLXeCb080sElNacItZsKLQ0WSDtOOYERw8XiOFmaUCV0K_qgyc8oAL-CM6Vj-fcVwqojfCzLIZoL80-S40fhsFhSkgq77sLTjJSMMW5u0T1wLzN-DRtvmQEuXIwq52B_rYrUXCH0sbXkgNxj6mPxxcEXpmWfZlCuA3frqTeGqb1-W4gMXjUz8AreNHV77ynkpLKCFFGsWcZl-mx7P_ttFaOx9bNqjwqB72b_mPVeFb7nbJjbzRvrWYwbIQRhyvbU1lyuxzdsZkeJBwMZM4EnaM6RtUImpOnhepdgIzNsff_B0Fb4VQEfZq_ua2JADSachPQTwigave_PFZ8YCgiDNZItntlqpH-6oGkI5Mkg4gf6ZdRH5zxgaLsyAonO1YlZlyIFfJbE6gpcKyIQjUn-ZNhaLoFkfh4Uc8kVhQlDn5Vf5gQj7DZEr401sPTScSyihq6uWKGDhaO3EOCtGAgLfkuTzXkwLLjff3ZCq8SieVOsHPN7xA1lZb5yYa2IBJaVFAKujJLaGCHmaIdQn7Q398vBpMgc1aA6QVReuW3UVG8y8-AQfhss71Wnoh20YH3HIHHYzevLXfbqh7ue7pwNAvbuU3waq7av_KDsoD34w_agy3Q-QEN7boXX0F1C3KCGhkTgtnKC1iq45BM8A4TyFVWZ9JaJv0ATUlo3cRv7asx7xyROc3PuGvOwYgjgDveVM8QIWJCnOaZisEEVfkDDQkuIF_VVnx1fCWRLU7shdIv1sORm_2WIxy1mN.rj63L64MhR0_yeTcG6wNsg
    </EncCRes>
</CardinalMPI>

Versions Compared

Old Version 1

New Version Current

Key

Interpreting the Lookup Response

Frictionless

Challenge

Virtual SDK Lookup Response Fields

Initiating the Step Up

Steps of the Step Up

cmpi_step_up Request

cmpi_step_up Response