Ch 15: Continue with Consumer Authentication

Owned by Suyash Somani
Last updated: Jul 14, 2020 by Chris Bohatka
2 min read

Changes made on 2020-07-14 are delineated below.

  • Additions are underlined in Green.

  • Deletions are underlined in Red.

  • Modifications are underlined in Blue.

Update occurred on: Cardinal Cruise API

Changelog Highlights:

  • Added ReferenceId callout in Step 4

  • Updated instruction surrounding Step Up iFrame sizing

  • Added definition of an instruction for use of MD field on the Step Up

  • Updated code samples

  • Added MD field in sample of POST to ReturnUrl in Step 5

Step 4: Continue with Consumer Authentication

After the Lookup Response is returned, you will then need to generate a JSON Web Token (JWT) with the following values: ACSUrl, Payload, TransactionId, your ReturnUrl and (Cardinal generated) ReferenceId. The ReferenceId is the same value that you had previously passed as DFReferenceId on the Lookup Request. 

When adding these values to the JWT, you will securely sign them with a secret key provided during the onboarding process. 

StepUp JWT Sample

{   "jti": "4595beb0-a4a9-11e8-8fd8-bdf5ff435fec",   "iat": 1534790755,   "iss": "Midas-XXXXX-Key",   "OrgUnitId": "59c2745f2f3e7357b4aa516a",   "ReturnUrl": "http://localhost:8189/cart/enterprise/term",   "ReferenceId": "c88b20c0-5047-11e6-8c35-8789b865ff15",   "Payload": {     "ACSUrl": "https://merchantacsdev.cardinalabs.com/MerchantACSWeb/pareq.jsp?vaa=b&gold=AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",     "Payload": "eNpVUV1PwjAUfe+vIMRX13ZAMsmlCTKJmIAwBzw3XeMaWTe6TfHf25ZNtE/3nNv7cc6FNDdSxm9StEYyWMu65u9yoLLZsE7W2+NiV+7MkzpcZJ7qlgwZbOeJPDP4lKZWpWY0IEEIuIfItjAi57phwMX5cbVh1D3AHUJQSLOKr6xPXDECzQvJ1irj9X36VcZl85oD9iQCUba6Md8sGhPAPUDQmhPLm6aaYtfFj61VIwNRFoBdEgG+7bNtXVRbmReVMUFfNvtlFu+PD4n4OFQHnZ/4MmmzdD4D7H4gyHgjWUhoRKKQDGg0HU+mI6vW8wh44TZhd3QSELtXBxFUbtD8iujEpf4yVk1rjNSil9MjBPJSlVraP3bGb2w13DZfPDtfRWMdG9HQ2+qBr1XWlJCQkS9W3iHsCnB3M9yd10b/zv4DGhKoaw==",     "TransactionId": "sRMPWCQoQrEiVxehTnu0"   },   "ObjectifyPayload": true }

Once you have the StepUp JWT, you will need to pass that to the web front-end and create an iFrame to POST the StepUp JWT to the StepUpUrl that was returned on the Lookup Response. The size of the iFrame is in your control, and can be tailored to your current checkout experience. The Cruise API Step Up will acknowledge this size and look to fill both the height and width completely. Please keep in mind the following guidelines for Step Up frame sizing:

  • In 3DS 1.0.2, most issuers have designed content around a standard 400x400 pixel size

  • In EMV 3DS, issuers have designed content around the following 4 available challenge window sizes: 250x400, 390x400, 500x600, 600x400

    • You can help inform the issuer of your preferred size by using the ACSWindowSize property on the Lookup Request

We recommend using the ThreeDSVersion property on the Lookup Response to help identify the sizing of your iFrame.

Alongside the JWT, you may also opt to post another field with a name of MD. The MD field allows you to pass any data specific to your checkout session and have it echoed back to you on your ReturnUrl. For example, you may utilize this to reference your SessionId related to the consumer, allowing you to maintain the consumers experience pre- and post-authentication. Any value provided in this field must be URL encoded.

NOTE: it is not recommended to deviate from iFrame usage; performing a full page redirect may be technically possible, though it is not an officially supported method of render.

POST to StepUpUrl Example

<iFrame height="400" width="390">      <form name="stepup" method="POST" action="https://centinelapistaging.cardinalcommerce.com/V2/Cruise/StepUp">         <input type="hidden" name="JWT" value="JWT generated by merchant per spec" />         <input type="hidden" name="MD" value="ABC123XYZ456" />     </form> </iFrame>

Step 5: Handling the Consumer Authentication response

…

TransactionId=BwNsDeDPsQV4q8uy1Kq1&MD=ABC123XYZ456&Response=eyJtZXNzYWdlVHlwZSI6IkNSZXEiLCJtZXNzYWdlVmVyc2lvbiI6IjIuMS4wIiwidGhyZWVEU1NlcnZlclRyYW5zSUQiOiI1YjdlMmMxNC0xYTUzLTRlN2EtODNmMS1kMGVhMWVjMjM5MDEiLCJhY3NUcmFuc0lEIjoiZDk3NmNiNWUtYzlmZC00NDc1LWI3ZGMtMDcwNWUzNThlMjFjIiwiY2hhbGxlbmdlV2luZG93U2l6ZSI6IjAyIn0