Android and iOS

You must have a username and password for Jfrog Artifactory to access the SDK. To receive these please contact your Implementation Manager.

You can find the JFrog login page here. Once logged in you can generate a token that you can use as access for your build.

Cardinal provides and maintains the SDK itself. The steps here act as guidance for using the Cardinal SDK with the Access Payments API.

SDK updates

We strongly recommend signing up here so you are kept informed of SDK updates.

1. Add the threeDS object

Adding the threeDS object to your payment request will enable 3DS.

If 3DS authentication is not available/applicable (e.g. subsequent recurring (MIT), Apple Pay) a validation error message will be returned.

Recommended key:values for high authentication rates

"instruction": {
  ....
  "threeDS": {
    "type": "integrated",
    "mode": "always",
    "challenge": {
      "returnUrl": "http://payment.example.com",
    },
    "deviceData": {
      "acceptHeader": "text/html",
      "userAgentHeader": "Mozilla/5.0 (iPhone; CPU iPhone OS 17_7_2 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/18.3 Mobile/15E148 Safari/604.1",
      "channel": "native"
    }
  }
}

See how much data to provide for guidance on the values to include in the request related to 3DS, and the impact this may have on authentication rates.

View the full API Request schema

2.Device Data Collection (DDC)

The /payments response will return an outcome of 3dsDeviceDatarequired. This contains a JWT that will be used to initialize the SDK.

{
  "transactionReference": "Memory265-13/08/1876",
  "outcome": "3dsDeviceDataRequired",
  "deviceDataCollection": {
    "jwt": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJPcmdVbml0SWQiOiI2NjAzMDA3YWJlMjMxZTM1ZTNmNTRjODkiLCJpc3MiOiI2NjAzMDA3YTE2ZGQ5YTdlNmEwMzM0MDciLCJleHAiOjE3MTIyNDg3MTIsImlhdCI6MTcxMjI0ODExMiwianRpIjoiZjdjZGVhZWUtMTY4MS00NjlhLTgxZmEtMzBkY2MyOTYzODA3In0.T1a6hOCPVVsQmcCKU3eczwmxlHoWK83tUqIJ_VG4fwc",
    "url": "https://centinelapistag.cardinalcommerce.com/V1/Cruise/Collect",
    "bin": "400000"
  },
  "_actions": {
    "supply3dsDeviceData": {
      "href": "https://try.access.worldpay.com/api/payments/eyJrIjoxLCJkIjoiR0ZSM3R2Z1d4OTI5SEdSVlVaWlk0cllQV3p4TU5raU85Y0ZwSkd2b09FWGo0SnVHYXI0MzJqZlM4RHp5UnRaaiJ9/3dsDeviceData",
      "method": "POST"
    }
  }
}

SDK initialization

The Access 3DS API is periodically tested against the latest version of the Cardinal SDK. Current tested Cardinal SDK version:

Android: v2.2.7
iOS: v2.2.5

Setup the Cardinal SDK

Initial call to Cardinal

You will receive the consumerSessionId

3. Continue with the payment

Once device data has been completed use the supply3dsDeviceData action (from the /payments response) to resume the payment, including the consumerSessionId (Aka: collectionReference) in the request body.

// Action to continue the payment (from /payment response)
"_actions": {
    "supply3dsDeviceData": {
      "href": "https://try.access.worldpay.com/api/payments/eyJrIjoxLCJkIjoiR0ZSM3R2Z1d4OTI5SEdSVlVaWlk0cllQV3p4TU5raU85Y0ZwSkd2b09FWGo0SnVHYXI0MzJqZlM4RHp5UnRaaiJ9/3dsDeviceData",
      "method": "POST"
    }
}

// Include the sessionId (Aka: collectionReference) in the body
{
  "collectionReference": "0_3XXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXX6b5"
}

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

The issuer then performs a risk assessment using a combination of data from the Payments API request and the Device Data Collection above. If it passes the payment will proceed to authorization. If not the issuer may request a challenge to verify the identity of the customer.

4.Challenge and Verification

If the response outcome from the supply3dsDeviceData action is 3dsChallenged you must display a challenge screen from the issuer to check the customers identity.

{
  "outcome": "3dsChallenged",
  "transactionReference": "Memory265-13/08/1876",
  "authentication": {
    "version": "2.1.0"
  },
  "challenge": {
    "reference": "706hovL8DK1tIGGzQUV1",
    "url": "https://centinelapistag.cardinalcommerce.com/V2/Cruise/StepUp",
    "jwt": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJPcmdVbml0SWQiOiI2NjAzMDA3YWJlMjMxZTM1ZTNmNTRjODkiLCJPYmplY3RpZnlQYXlsb2FkIjpmYWxzZSwiaXNzIjoiNjYwMzAwN2ExNmRkOWE3ZTZhMDMzNDA3IiwiUmV0dXJuVXJsIjoiaHR0cDovL3BheW1lbnQuZXhhbXBsZS5jb20iLCJQYXlsb2FkIjoie1wiUGF5bG9hZFwiOlwiZXlKdFpYTnpZV2RsVkhsd1pTSTZJa05TWlhFaUxDSnRaWE56WVdkbFZtVnljMmx2YmlJNklqSXVNUzR3SWl3aWRHaHlaV1ZFVTFObGNuWmxjbFJ5WVc1elNVUWlPaUppTkRKbE5UWmpaaTAyWkRrMkxUUXpNek10T0dJMk5DMWlNbVU0TldZMFpURTFaVGtpTENKaFkzTlVjbUZ1YzBsRUlqb2laV1ZqWldZeE1ETXRNRE13TVMwMFpUbGtMVGsxTmpFdE56ZGlNbVkzTlRFMk5HUmhJaXdpWTJoaGJHeGxibWRsVjJsdVpHOTNVMmw2WlNJNklqQTBJbjBcIixcIkFDU1VybFwiOlwiaHR0cHM6XFwvXFwvMW1lcmNoYW50YWNzc3RhZy5jYXJkaW5hbGNvbW1lcmNlLmNvbVxcL01lcmNoYW50QUNTV2ViXFwvY3JlcS5qc3BcIixcIlRyYW5zYWN0aW9uSWRcIjpcIjcwNmhvdkw4REsxdElHR3pRVVYxXCJ9IiwiZXhwIjoxNzEyMzA2MDk0LCJpYXQiOjE3MTIzMDU0OTQsImp0aSI6IjE4YTIwYzNkLTZhZmMtNDA5My04NGEwLTQ2OGEyYTY5MTE0OCJ9.YEpOuTxnqrXRiHan-givWBd6FfTDJOfNg-h2dF2yA6A",
    "payload": "eyJtZXNzYWdlVHlwZSI6IkNSZXEiLCJtZXNzYWdlVmVyc2lvbiI6IjIuMS4wIiwidGhyZWVEU1NlcnZlclRyYW5zSUQiOiJiNDJlNTZjZi02ZDk2LTQzMzMtOGI2NC1iMmU4NWY0ZTE1ZTkiLCJhY3NUcmFuc0lEIjoiZWVjZWYxMDMtMDMwMS00ZTlkLTk1NjEtNzdiMmY3NTE2NGRhIiwiY2hhbGxlbmdlV2luZG93U2l6ZSI6IjA0In0"
  },
  "_actions": {
    "complete3dsChallenge": {
      "href": "https://try.access.worldpay.com/api/payments/eyJrIjoxLCJkIjoiZXlOaXNtU0lzQnVLTm5BQkt1WjEyMVFxeXg2bUZtb2hEcEpFeDdyYXZ3SDE3NFBpUTBsWUpwekptbW9hR3VVSyJ9/3dsChallenges",
      "method": "POST"
    }
  }
}

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.

3DS challenge display

You need the following values from the response to use in the SDK.

Access Name	Cardinal SDK Name
`challenge.reference`	`transactionId`
`challenge.payload`	`payload`

The Access 3DS API is periodically tested against the latest version of the Cardinal SDK. You can see the latest tested version in the change log

SDK challenge display

Customize challenge interface

As part of SDK setup you can customize the challenge user interface

5. Continue with the payment

Once the challenge form has been completed use the action from the 3dsDeviceData response. No body is required.

If you do not complete the challenge display the payment will fail when you post the action below.

// Action to continue the payment (from /3dsDeviceData response)
"_actions": {
    "complete3dsChallenge": {
      "href": "https://try.access.worldpay.com/api/payments/eyJrIjoxLCJkIjoiZXlOaXNtU0lzQnVLTm5BQkt1WjEyMVFxeXg2bUZtb2hEcEpFeDdyYXZ3SDE3NFBpUTBsWUpwekptbW9hR3VVSyJ9/3dsChallenges",
      "method": "POST"
    }
  }

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"
	}
}

6. Outcome details

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

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