Step 3: The Lookup Response is a Challenge, What's Next?
- Brian Brotherton
- Chris Bohatka
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:
.png?version=1&modificationDate=1596221368447&cacheVersion=1&api=v2&width=500&height=1018)
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:
Challenge
A challenge is required when indicated by the lookup response. An example of that response can be seen below:
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:
| 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.
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
| 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) |
Algorithm | The hash algorithm that was used to generate the Signature for the request. Possible Values:
| 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) |
Signature | The signature for the request being submitted. This value is generated by hashing the combination of the Timestamp and the API Key. | Y | - | AN(255) |
Timestamp | The unix epoch time in milliseconds for the point in time that the request is generated. Example: | Y | - | N(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) |
<CardinalMPI>
<MsgType>cmpi_step_up</MsgType>
<Version>1.7</Version>
<TransactionType>C</TransactionType>
<Algorithm>SHA-512</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) |
<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>