# 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](https://cardinalcommerceprod.jfrog.io/ui/login/). 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](https://win.cardinalcommerce.com/CardinalMobileSDKNotifications) 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
Recommended key:values for high authentication rates


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

Minimum
Minimum key:values to enable 3DS


```JSON
"instruction": {
  ....
  "threeDS": {
    "type": "integrated",
    "mode": "always",
    "challenge": {
      "returnUrl": "http://payment.example.com",
    },
    "deviceData": {
      "acceptHeader": "text/html",
      "userAgentHeader": "Mozilla/5.0 (Windows NT 6.1; Win64; x64; rv:47.0)"
    }  
  }
}
```

See [how much data to provide](/products/payments/enable-features/3ds-authentication#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.

See [how to enable authentication outage exemptions](/products/payments/enable-features/3ds-authentication#how-to-enable-authentication-outage-exemptions) to increases the likelihood of receiving a successful authorization (without liability shift) in the event of a 3DS network failure.

View the full API Request schema
## 2.Device Data Collection (DDC)

The [`/payments`](/products/payments/openapi/) response will return an outcome of `3dsDeviceDatarequired`. This contains a `JWT` that will be used to initialize the SDK.


```JSON
{
  "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

- Android
- iOS


#### Initial call to Cardinal

- Android
- iOS


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.


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


```JSON
// 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.

For merchants using `3DS premium` where custom rules can be created using Cardinal, you can also get a 3DS outcome of `bypassed` that will cause the payment to proceed straight to authorization after Device Data Collection.

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 customer's identity.


```JSON
{
  "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](/products/payments/changelog).

### SDK challenge display

- Android
- iOS


### Customize challenge interface

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

- Android
- iOS


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


```JSON
// 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. However, if authentication fails or a downstream error prevents authentication details from being returned, you may encounter different outcomes. For a comprehensive overview, please refer to the [Outcome details](#6-outcome-details) below.

## 6. Outcome details

A summary of the 3DS authentication is included in the final payment response.

Authentication successful

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

Authentication outage
See [how to enable authentication outage exemptions](/products/payments/enable-features/3ds-authentication#how-to-enable-authentication-outage-exemptions)


```JSON
...
"threeDS": {
  "outcome": "authenticationOutage"
}
...
```

Authentication failed
Issuer failed the authentication following the challenge.

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

{
	"transactionReference": "700cb517-02c6-4dfe-a9dc-a5f77ae101bb",
	"outcome": "3dsUnavailable"
}