# 3DS iOS SDK > **Note** > > To use our 3DS iOS SDK, you must be able to build and test ARM64 based SDKs during your iOS application's CI/CD process. We have discontinued support for X86_64 architectures in line with the [deprecation of bitcode](https://developer.apple.com/documentation/xcode-release-notes/xcode-14-release-notes#Deprecations). Use our 3D Secure (3DS) iOS SDK to seamlessly handle the end-to-end [3DS](https://www.checkout.com/docs/payments/authenticate-payments/3d-secure.md) authentication flow. With a single method call, the SDK handles: - collecting required device data - communicating with the customer's bank - presenting 3DS challenges when required When used alongside our [non-hosted sessions](https://www.checkout.com/docs/payments/authenticate-payments/3d-secure/standalone-sessions/non-hosted-sessions.md) authentication solution, the 3DS SDK allows you to authenticate within the payment authorization flow. Alternatively, you can use the authentication result to complete the payment manually at a later time. Additionally, the SDK is fully EMVCo and PCI-compliant, ensuring interoperability with card issuers and secure handling of your customers' data. > **Information** > > The SDK only collects data which your app already has permission to collect – the customer will never be prompted to grant new permissions. The device data collected is encrypted throughout the authentication process but is never stored, and the SDK does not retain any personal information about the customer. --- ## 3DS flows 3DS allows you and your payment provider to share additional data with the customer's bank. For example, the customer's device ID and payment history. This data allows the bank to assess the risk of the transaction more accurately, and determine which flow the customer will be required to go through: - frictionless flow - challenge flow ### Frictionless flow If the customer's bank is satisfied with the data and trusts that the cardholder making the payment is genuine, the transaction will be authenticated without interrupting the customer. The customer is only shown a brief _Processing_ UI, with their card scheme's branding. ![A frictionless 3DS mobile experience – no additional customer action is required](https://www.checkout.com/docs/large-media-assets/iOS_frictionless.gif) ### Challenge flow If the bank requires additional evidence to authenticate the cardholder, they will prompt the customer to verify their identity. To do this, the bank may use any of the following methods: - one-time password – the customer is sent a single-use password or code via text or email, which they must enter - single-select or multi-select – the customer is asked a multiple-choice question, with one or more selections allowed - out-of-band – the customer is asked to confirm the transaction through another channel, typically their banking app - HTML – the bank explicitly defines the view that should be presented to the customer via HTML, which can be that of any of the previous methods, or a custom approach ![A challenge 3DS mobile experience – the customer must confirm their identity to proceed](https://www.checkout.com/docs/large-media-assets/iOS_OOB.gif) > **Information** > > To provide a consistent experience across different devices and schemes, there are standard templates and rules that the 3DS challenge screens adhere to. However, there is some leeway around styling. Our SDK gives you control over the display of the native challenges in your app, while ensuring that the rules are followed. --- ## Integrate the 3DS SDK 1. Add the SDK as a project dependency. 1. Initialize the SDK. 1. Configure authentication parameters. 1. Handle authentication results. 1. Customize the 3DS Challenge UI. --- ## Before you start Make sure you have a [test account](https://www.checkout.com/get-test-account) with Checkout.com. To use the SDK, you'll also need to have onboarded with our [non-hosted sessions](https://www.checkout.com/docs/payments/authenticate-payments/3d-secure/standalone-sessions/non-hosted-sessions.md) authentication solution. You'll also need the following: - a [public key](https://www.checkout.com/docs/developer-resources/api/manage-api-keys/api-keys.md#Public_API_keys), to initialize the SDK and authenticate your payment request - a [secret key](https://www.checkout.com/docs/developer-resources/api/manage-api-keys/api-keys.md#Secret_API_keys) or [OAuth 2.0 client credentials](https://www.checkout.com/docs/developer-resources/api/manage-api-keys/oauth-2-0-client-credentials.md), to use as an authentication mechanism --- ## Add the SDK as a project dependency The [3DS SDK for iOS](https://github.com/checkout/checkout-3ds-sdk-ios) is available as a package dependency on GitHub. > **Information** > > You can subscribe to the GitHub repository to be notified about updates to the SDK. ### Minimum requirements The minimum requirements to use the iOS SDK are: - Xcode 15.3 or later - iOS 13.0 or later as a deployment target ### Add the SDK dependency Install the library in your app’s project using Swift Package Manager (SPM). Follow Apple’s documentation to [add a package dependency](https://developer.apple.com/documentation/xcode/adding-package-dependencies-to-your-app) to your app and set: - the repository URL to `https://github.com/checkout/checkout-3ds-sdk-ios` - the version to `` --- ## Initialize the SDK Initialize the SDK and set the: - environment – for example, `production` or `sandbox` - locale - 3DS challenge UI configuration ```swift // Option 1: initialize with default configuration let checkout3DS = Checkout3DSService() // Option 2: initialize with custom configuration let checkout3DS = Checkout3DSService( environment: .production, locale: Locale(identifier: "en_GB"), uiCustomization: uiCustomization, appURL: URL(string: "https://sampleAppName.com")! ) ``` ### Checkout3DSService The SDK's `Checkout3DSService` class provides the core functionality to perform payment authentication. You only need to initialize the class once for the lifetime of the application. **View Checkout3DSService reference** When you initialize, you can specify any of the following optional configuration options: | Parameter | Type | Description | | --- | --- | --- | | `environment` | `Environment` | The environment the SDK will connect to. For example, `PRODUCTION` or `SANDBOX`.

If no value is specified, `PRODUCTION` is used by default. | | `locale` | `Locale` | The customer's locale and preferred language.

If no value is specified, the device locale is used by default. | | `uiCustomization` | `UICustomization` | The UI customization options for the 3DS challenge presented to the customer. | | `appUrl` | `URL` | The application URL, up to 211 characters, used to open and move your application to the foreground.

Providing this URL results in a smoother out-of-band (OOB) challenge experience to the customer as they are automatically redirected to your app after their banking app authorizes the transaction, if the card issuer supports this feature.

Because the authenticating app uses the `appUrl` value to call your app after an OOB authentication occurs, this field should be an [iOS Universal link](https://developer.apple.com/documentation/xcode/allowing-apps-and-websites-to-link-to-your-content). | ### Check for security warnings You can use the `getWarnings()` method to check for any security warnings when you initialize the SDK, or at any time after initialization. **View getWarnings reference** The method returns the following values: | Value | Type | Description | | --- | --- | --- | | `id` | `string` | An identifier for the warning.

Security warnings IDs are prefixed with `SW`, while initialization warning IDs are prefixed with `CW`. | | `message` | `string` | A description of the warning. | | `severity` | `string` | The severity of the warning, as a value of either `LOW`, `MEDIUM`, or `HIGH`. | ### Warning IDs The following table outlines the possible `id` values returned by the `getWarnings()` method: | Warning ID | Severity | Description | | --- | --- | --- | | `SW01` | `high` | The app is running on a device with unauthorized modifications (also referred to as a jailbroken device) | | `SW02` | `high` | The SDK has been tempered with | | `SW03` | `high` | The app is running within an emulator | | `SW04` | `medium` | A debugger is attached to the app | | `SW05` | `high` | The app is running on an unsupported OS version | | `CW01` | `low` | The `appUrl` provided exceeds the 211-character limit and has been ignored | | `CW03` | `low` | The `appUrl` provided is not in a recognized Universal App Link format and has been ignored | --- ## Configure authentication parameters Before you can begin authentication using the SDK, your back end must first request an authentication session using the Sessions API by calling the [Request a session](https://api-reference.checkout.com/tag/Standalone/#operation/createSession) endpoint. In your application code, create an instance of `AuthenticationParameters` and populate it with the values returned in the Session API response: ```swift let authenticationParameters = AuthenticationParameters( sessionID: sessionID, sessionSecret: sessionSecret, scheme: scheme) ``` With the authentication information, the SDK will take care of: - gathering the necessary device data - sharing the information with the customer's bank - if necessary, presenting a native challenge screen to the customer The type of challenge presented to the customer depends on the configuration of the customer’s bank. **View authenticationParameters reference** | Parameter | Type | Description | | --- | --- | --- | | `sessionID` | `string` | The unique ID of the authentication session. | | `sessionSecret` | `string` | The session secret. | | `scheme` | `string` | The customer's card scheme, as a value of either `Visa`, `Mastercard`, `Jcb`, `Amex`, or `Diners`.

The value provided determines which card scheme logo will be displayed to the customer. | --- ## Handle authentication results When the authentication process is completed after you call the `authenticate()` method, the SDK will return the authentication results: - If authentication was successful, you can complete the payment with the [Payments API](https://api-reference.checkout.com/tag/Payments/#operation/requestAPaymentOrPayout) or with an alternative payments service provider. - If authentication was unsuccessful, the SDK returns the reason for the failure as a [3DS SDK error code](https://www.checkout.com/docs/developer-resources/codes/3ds-sdk-error-codes.md) within `AuthenticationError`. Regardless of the outcome, you'll receive an `AuthenticationResult` object with information about the status of the transaction. ```swift checkout3DS.authenticate(authenticationParameters: authenticationParameters) { result in switch authenticationResult { case .success(let authenticationResult): // Handle authentication result - continue with the payment based on transaction status case .failure(let error): // Handle failure scenarios } } ``` > **Note** > > In rare circumstances, there may be inconsistencies between the SDK output and the authentication status. This can be due to timing differences between the SDK, back end, Access Control Server (ACS), and card scheme during the flow. > > To ensure that you receive the accurate authentication status (session status), we recommend implementing one of the following at the end of every authentication flow: > > - Perform a [GET session](https://api-reference.checkout.com/tag/Standalone/#operation/getSession) request, referencing the session status > - Use the [Authentication approved](https://www.checkout.com/docs/developer-resources/event-notifications/event-types/authentication_approved.md), [Authentication expired](https://www.checkout.com/docs/developer-resources/event-notifications/event-types/authentication_expired.md), or [Authentication failed](https://www.checkout.com/docs/developer-resources/event-notifications/event-types/authentication_failed.md) webhooks to understand the true session status of the flow **View authenticate reference** | Parameter | Type | Description | | --- | --- | --- | | `authenticationParameters` | `AuthenticationParameters` | The object containing the authentication parameters. | **View AuthenticationResult reference** | Parameter | Type | Description | | --- | --- | --- | | `sdkTransactionID` | `string` | The SDK transaction ID that was received by the 3DS SDK in the final Challenge Response | | `transactionStatus` | `string` | The transaction status that was received in the Challenge Response | **View AuthenticationError reference** The `AuthenticationError` enum contains all possible errors that you could encounter during payment authentication. Each enum value contains: - a clear name - an error message - an associated error code The value of `transactionStatus` returned in the `AuthenticationResult` object determines whether you can proceed with [requesting a payment authorization](https://api-reference.checkout.com/tag/Payments/#operation/requestAPaymentOrPayout): | Value | Description | Proceed to payment authorization | | --- | --- | --- | | `A` | Attempt at processing performed | ✓ | | `I` | Informational only | ✓ | | `N` | Not authenticated or account not verified | ✗ | | `R` | Authentication or account verification rejected | ✗ | | `U` | Authentication or account verification could not be performed | ✗ | | `Y` | Authentication verification successful | ✓ | > **Information** > > You can view a [transaction's status](https://www.checkout.com/docs/business-operations/use-the-dashboard/payment-activity/track-3ds-events.md#Transaction_status) from the _Payments_ > _Processing_ > _All Payments_ section of the [Dashboard](https://dashboard.checkout.com). --- ## Customize the 3DS Challenge UI With the default SDK implementation, the 3DS challenge screens presented to your customers are displayed with a clean, minimalist UI. The SDK also provides built-in display and accessibility features: - support for different screen sizes and orientations - dynamic text sizing - support for screen-reading technologies, including VoiceOver on iOS and TalkBack on Android - support for 37 languages If you want to customize the screen to match your app's visual design, you can use the SDK's customization options to change the following properties: - fonts and font colors - navigation bar and footer background colors - action button background colors, opacity, shadows, and corner shapes ![Examples of customized 3DS challenge user interfaces](https://www.checkout.com/docs/NAS/3DS SDK/3ds-sdk-custom-challenge-ui-ios.png) To customize the UI, create a new `UICustomization` instance and include it as an argument when you [initialize](#Initialize_the_SDK) `Checkout3DSService`. The following example demonstrates the customization options available: ```swift final class Customization1: UICustomization { let toolbarCustomization: ToolbarCustomization = DefaultToolbarCustomization( backgroundColor: .blue, headerTitle: "3DS Check", buttonTitle: "Cancel", font: UIFont(name: "Optima-Bold", size: 20)!, textColor: .black) let labelCustomization: LabelCustomization = DefaultLabelCustomization( headingTextColor: .purple, headingFont: UIFont(name: "Optima-Bold", size: 16)!, font: UIFont(name: "Optima-Regular", size: 16)!, textColor: .orange) let buttonCustomizations: ButtonCustomizations = DefaultButtonCustomizations( verifyButtonCustomization: DefaultButtonCustomization( backgroundColor: .red, cornerRadius: 24, cornerCurve: .circular, font: UIFont(name: "Optima-Regular", size: 14)!, textColor: .white, borderWidth: 0, borderColor: UIColor.clear.cgColor), continueFlowButtonCustomization: DefaultButtonCustomization( backgroundColor: UIColor.blue, cornerRadius: 24, cornerCurve: .circular, font: UIFont(name: "Optima", size: 14)!, textColor: .white, borderWidth: 0, borderColor: UIColor.clear.cgColor)) let whitelistCustomization: WhitelistCustomization = DefaultWhitelistCustomization( font: UIFont(name: "Optima-Regular", size: 16)!, textColor: .black, switchTintColor: .green) let footerCustomization: FooterCustomization = DefaultFooterCustomization( backgroundColor: .clear, font: UIFont(name: "Optima-Bold", size: 16)!, textColor: .black, labelFont: UIFont(name: "Optima-Regular", size: 16)!, labelTextColor: .blue, expandIndicatorColor: .green) let entrySelectionCustomization: EntrySelectionCustomization = DefaultEntrySelectionCustomization( borderWidth: 1, borderColor: UIColor.blue.cgColor, cornerRadius: 4, cornerCurve: .continuous, font: .systemFont(ofSize: 16), textColor: .black, borderStyle: .line, backgroundColor: .white, unselectedColor: .white, selectedColor: .blue) } ``` --- ## Security In accordance with PCI and EMVCo standards, the 3DS SDK incorporates several security approaches. This maintains the integrity of the SDK and ensures your customers' data is secure. ### SDK integrity protection The 3DS SDK is an encrypted binary. This provides increased protection from a number of threats including tampering and reverse engineering. Additionally, the SDK checks: - if the app was installed from a trusted app store and sends this information to the card issuer - the environment on which it's running and sends warnings to your app and the card issuer if it detects any threat indicators For example, the following scenarios would be classed as a threat indicator: - the device has unauthorized modifications (also referred to as a jailbroken device), which could enable unrestricted access to critical files - the SDK is running on an emulator - the SDK source code has been tampered with or its functionality has been modified - a debugging application is attached > **Information** > > After you initialize the SDK, check the [security warnings](#Check_for_security_warnings) for any potential threat indicators before you proceed with a transaction. ### Sensitive data protection To keep your customers' data secure and protect the 3DS process, the SDK takes the following precautions with sensitive data: - only collects sensitive data where it is essential for the authentication process and uses it solely for this purpose - does not disclose sensitive data to channels outside of the 3D Secure process - does not hardcode sensitive data into the SDK except where necessary and permitted - deletes all sensitive data elements once the 3DS transaction is complete For additional protection, the SDK also: - secures the UI to prevent access from outside the SDK - employs run-time data protection techniques to prevent access by unauthorized services - intercepts and handles any external URL requests contained within 3D Secure HTML – during the 3DS process, the SDK prevents the injection and execution of any JavaScript code by 3D Secure HTML, or any other process outside the 3DS SDK - securely stores any reference data required for the SDK's operation to prevent unauthorized modifications - uses EMVCo-approved cryptographic algorithms and methods in all cryptography handled by the 3DS SDK, and employs cryptographically strong random number generation - uses third-party services to help maintain security ### Communication security The 3DS SDK communicates with various systems managed by the multiple parties involved in the 3D Secure process. Each of these communication channels is secure and all data exchanged is encrypted. Communication with the Checkout.com 3DS Server is secured using the latest versions of Transport Layer Security (TLS). The device data passed to the Checkout.com 3DS Server and forwarded to the card scheme’s Directory Server (DS) is transferred in an encrypted format. Communication with the card issuer’s Access Control Server (ACS) is done over a secure channel that is encrypted end-to-end. The 3DS SDK also uses Certificate Transparency to ensure end-to-end security and to prevent a man-in-the-middle attack. For this purpose, it checks that all certificates were issued by a trusted Certificate Authority. > **Information** > > Do not disable certificate transparency checks by using a wildcard domain in your iOS app’s `.plist` file. This interferes with the SDK operations and may result in a failure. For more information, see the Apple documentation on [NSAppTransportSecurity](https://developer.apple.com/documentation/bundleresources/information_property_list/nsapptransportsecurity) and [NSExceptionDomains](https://developer.apple.com/documentation/bundleresources/information_property_list/nsapptransportsecurity/nsexceptiondomains). Due to the use of Certificate Transparency, the 3DS SDK may not be able to establish a secure connection on devices that are connected to certain SSL Proxy Servers. In these scenarios, the 3DS SDK will return a connectivity error, which you can communicate to your customer. We recommend that your customer switches to a mobile data connection where available. We regularly update our 3DS SDK and review our security guidance. --- ## Compatibility with third-parties As with our core [Standalone](https://www.checkout.com/docs/payments/authenticate-payments/3d-secure/standalone-sessions.md) authentication product, you can use the 3DS SDK to authenticate a payment and continue to payment authorization with a different payment services provider. --- ## Related topics **[3DS SDK error codes](https://www.checkout.com/docs/developer-resources/codes/3ds-sdk-error-codes.md)** View the error codes returned by the 3DS SDKs for Android and iOS. **[Mobile SDKs lifecycle policy](https://www.checkout.com/docs/developer-resources/sdks/mobile-sdks-lifecycle-policy.md)** Learn how we version, support, and deprecate our mobile SDKs, and how long you have to adopt each new release.