Web

Device Data Collection (DDC)

The /payments response contains a JWT, URL and BIN. Use this to create and submit the DDC form.

A SessionId representing this collection is then used as part of the risk analysis by the issuer.

If you do not provide a collectionReference, you will see an increased number of challenged and even authenticationFailure outcomes.

Device Data Collection form

Here's an example of how you would set-up the DDC form in an iframe.

Create a hidden iframe and set the src attribute with the URL of the page that will POST the DDC form. This URL should contain in query string parameters the deviceDataCollection.jwt, deviceDataCollection.bin and deviceDataCollection.url as those will be used in the DDC form.

<iframe height="1" width="1" style="display: none;" src="replace-this-with-the-url-of-your-page-that-posts-the-ddc-form"></iframe>

Create and host the page that POSTs the DDC form.

<html>
<head>
</head>
<body>
<!-- Using your preferred programming language, set the 'action' attribute with the value of the query string parameter containing the 'deviceDataCollection.url' from the device data initialization response -->
<form id="collectionForm" name="devicedata" method="POST" action="https://ddcUrl.example.com">

<!-- Using your preferred programming language, set the 'value' attribute with the value of the query string parameter containing the 'deviceDataCollection.bin' from the device data initialization response -->
<input type="hidden" name="Bin" value="555555" />


<!-- Using your preferred programming language, set the 'value' attribute with the value of the query string parameter containing the 'deviceDataCollection.jwt' from the device data initialization response -->

 <input type="hidden" name="JWT" value="eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJPcmdVbml0SWQiOiJPcmdVbml0IiwiaXNzIjoiYXBpSWQiLCJleHAiOjE1NjI5MjMzNDYsImlhdCI6MTU2MjkyMzQwNiwianRpIjoiYTAzMWVhOGEtN2E0Zi00YTQwLWI1NjMtOTUzMzYzMzVhZGNmIn0.0IK74OIXBxFsxqeOURJz1TFnz14ZTbFJTdTWo9cHUJQ" />

</form>

<script>
window.onload = function() {
  document.getElementById('collectionForm').submit();
 }
</script>
</body>
</html>

Example device data form

The form below allows you to submit the 3DS device data details provided in the API response. You then receive the sessionId/collectionReference, back in the postMessage, for use in the /3dsDeviceData request. This is useful if using tools such as postman/insomnia to test your integration.

Device Data Collection postMessage

Once the DDC form is submitted and is successfully sent to the card issuer, you are notified via a postMessage event.

For security, verify the sender's identity using the postMessage origin property as detailed here.

Environment	Origin
Try	https://centinelapistag.cardinalcommerce.com
Production	https://centinelapi.cardinalcommerce.com

An example postMessage response:

{
  "MessageType": "profile.completed",
  "SessionId": "0_3XXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXX6b5",
  "Status": true
}

Key	Value
`messageType`	`profile.completed`
`SessionId`	UUID, not present or `undefined`
`Status`	`true` - Use the `SessionId` value in `collectionReference` as part of the `3dsDeviceData` request `false` - SessionId is empty. Either retry DDC or proceed without the `collectionReference`.

The DDC call typically takes 1-2 seconds, depending on the latency between the customer's device, the Cardinal servers and, in part, the type of Device Data Collection performed by the different issuers. The 3DS specification has the maximum response time at 10 seconds.

Note

If no postMessage is provided either retry DDC or send proceed without the collectionReference.

Continue with the payment

Once device data has been completed post to /3dsDeviceData to resume the payment

Challenge & Verification

Create a self submitting form within an iframe to display the issuers challenge screen.

To display the issuers challenge screen within the iframe, use the following parameters from the /3dsDeviceData response:

challenge.url
challenge.jwt

The content within the iframe is from the issuing bank. The bank performs an identity check on your customer.

Optional MD field

Pass data specific to your checkout session and it will be echoed back in the challenge.returnUrl originally provided. This could, for example, be a checkout sessionId. Any value provided must be URL encoded with a maximum of 1024 characters.

Challenge form

Once you have the JWT and URL you can create and submit the Challenge form.

Here's an example of how you would set-up the challenge form in an iframe.

Create an iframe and set the src attribute with the URL of the page that will POST the challenge form. This URL should contain in query string parameters the challenge.jwt, challenge.url and optionally MD as those will be used in the challenge form.

<iframe height= "400" width= "390" src="replace-this-with-the-url-of-your-page-that-posts-the-challenge-form"></iframe>

The size you specify for the iframe depends on whether you have provided a challenge.windowSize in the payments request. If not supplied use the default 400x500.

Create and host the page that POSTs the challenge form.

<html>
<head>
</head>
<body>

  <!-- Using your preferred programming language, set the 'action' attribute with the value of the query string parameter containing the 'challenge.url' from the authentication response -->
  <form id="challengeForm" method= "POST" action="https://challengeUrl.example.com">

    <!-- Using your preferred programming language, set the 'value' attribute with the value of the query string parameter containing the 'challenge.jwt' from the authentication response -->
    <input type = "hidden" name= "JWT" value= "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJqdGkiOiI1NDQzOGIzYS1iYjUzLTEyY2QtODY0My0xNTM2YmU3M2ZmMzUiLCJpYXQiOiIzODU2NzI5NDgyIiwiaXNzIjoiNWJkOWUwZTQ0NDRkY2UxNTM0MjhjOTQwIiwiT3JnVW5pdElkIjoiNWJkOWI1NWU0NDQ0NzYxYWMwYWYxYzgwIiwiUmV0dXJuVXJsIjoiaHR0cDovL21lcmNoYW50LmV4YW1wbGUuY29tL3RocmVlZHNjaGFsbGVuZ2Vjb21wbGV0ZSIsIlBheWxvYWQiOnsiQUNTVXJsIjoiaHR0cHM6Ly9hY3MuZXhhbXBsZS5jb20vM2RzMi9jaGFsbGVuZ2U_aWQ9MTIzNDU2Nzg5IiwiUGF5bG9hZCI6IlZHaHBjeUJwY3lCaElHSmhjMlVnTmpRZ1pXNWpiMlJsWkNCbGVHRnRjR3hsSUc5bUlHRWdNMFJUSUNKd1lYbHNiMkZrSWc9PSIsIlRyYW5zYWN0aW9uSWQiOiJzUk1QV0NRb1FyRWlWeGVoVG51MCJ9LCJPYmplY3RpZnlQYXlsb2FkIjp0cnVlfQ.3Dqjr5MuEC9AG7uvsJCft94-d70NmgR94zIeru8fAYE" />

    <!-- Optional field (max 1024 characters) for you to pass url parameters in the challenge form that will be included/echoed in the response url (`challenge.returnUrl`) after the challenge is complete -->
    <input type="hidden" name="MD" value="merchantSessionId=1234567890" />

  </form>

  <script>
    window.onload = function() {
      // Auto submit form on page load
      document.getElementById('challengeForm').submit();
    }
  </script>

</body>
</html>

Note

If you get a 400 response on POST of the challenge form ensure:

The JWT has not expired (10 minutes)
Element/form data names are upper case e.g. JWT as shown in the example

Test challenge form

The form below allows you to submit the 3DS challenge details provided in the API response and display the issuer challenge. This is useful if using tools such as postman/insomnia to test your integration.

Challenge returnUrl

Once the issuer challenge is complete there is a POST to the challenge.returnUrl (you provide in the payments request). This should go to your backend where you can retrieve any of the form data, initiate the verification request and display a page in the iframe depending on the outcome in the verification response.

Form data in returnUrl POST:

TransactionId - same value as challenge.reference from the 3dsDeviceData response.
MD - If included as part of the challenge form.

Continue with the payment

Once the challenge form has been completed post to /3dsChallenges to resume the payment

If everything is fine the payment will proceed. You could receive the following two outcomes if the authentication has failed or a downstream error means the authentication details were not returned (unavailable).

{
	"transactionReference": "05651339-d94e-4fdd-82e9-a41d3df47c7d",
	"outcome": "3dsAuthenticationFailed",
	"authentication": {
		"version": "2.1.0",
		"eci": "07",
		"transactionId": "ec89944d-c5b1-4d4b-b39a-a2dc80dd5565"
	}
}

Outcome details

In the final payment response a summary of the 3DS authentication is included.

...
"threeDS": {
  "outcome": "authenticated",
  "issuerResponse": "frictionless"
}
...

Web

Device Data Collection (DDC)

Device Data Collection form

Example device data form

Device Data Collection postMessage

Continue with the payment

Challenge & Verification

Optional MD field

Challenge form

Test challenge form

Challenge returnUrl

Continue with the payment

Outcome details

Do you like our page?