SDK Version 2.0 Implementation

This topic summarizes the process of integrating SDK Payer Authentication services into your mobile application. Payer authentication services use the Mobile SDK for iOS or Android to facilitate the authentication. New SDK versions are frequently released. Stay current with the latest release. To stay informed about new releases, subscribe to a distribution list: Cardinal SDK Notifications.

Implementing the SDK in your mobile application requires either Android or iOS platform application programming skills. Android API 21 or iOS 9 and XCode 8 are required.

The SDK is only designed to handle EMV 3-D Secure 2.x transactions.

Implementation Overview

Notify your account representative that you want to implement payer authentication (EMV 3-D Secure). Give the representative the merchant ID that you will use for testing.

Implementation tasks include:

• Download, import, and configure the Mobile SDK for either iOS or Android.
• For each purchase request:
  • Build the authentication request.
  • Invoke the authentication.
  • Handle declines.
  • Make another back-end, server-to-server request for the Payer Authentication Validation service and, if needed, the Card Authorization service.
• Use the test cases to test your preliminary code and make appropriate changes.
• Ensure that your account is configured for production.

Calling the Payer Authentication Setup Service is not required with the SDK mobile version.

Process Flow for SDK Integration

This section describes the steps required to integrate payer authentication into an SDK mobile application.

1. Contact customer support to register for an API key.
2. Download and import the Mobile SDK for either iOS or Android.
3. Set up your build environment.
4. Configure your SDK.
5. Set up the initial request to Cardinal.
6. Create an API request to your merchant server to request the Enrollment Check service, passing in transaction details and the consumerAuthenticationInformation.referenceId request field.
7. If the issuing bank does not require authentication, you receive this information in the Enrollment Check response:
   • E-commerce indicator (consumerAuthenticationInformation.ecommerceIndicator)
   • CAVV — all card types except Mastercard (consumerAuthenticationInformation.cavv)
   • AAV — Mastercard only (consumerAuthenticationInformation.ucafCollectionIndicator)
   • Transaction ID (consumerAuthenticationInformation.xid)
   • 3-D Secure version (consumerAuthenticationInformation.specificationVersion)
   • Directory server transaction ID (consumerAuthenticationInformation.directoryServerTransactionId)
8. If the issuing bank requires authentication, you receive a response with the payload and the transaction ID that you include in the Cardinal.continue request from your SDK.
9. The Mobile SDK displays an authentication window, and the customer enters the authentication information into that window.
10. The bank validates the customer credentials and a JSON Web Token (JWT) is returned by the SDK in the onValidated callback that the merchant is required to validate server-side for security reasons.
11. Create an API request to your merchant server for the Validate Authentication service, extracting the processor transaction ID value from the JWT and sending it in the consumerAuthenticationInformation.authenticationTransactionId request field. You receive the e-commerce indicator, CAVV or AAV, transaction ID, 3-D Secure version, and directory server transaction ID.

Verify that the authentication was successful and continue processing your order.

You must pass all pertinent data for the card type and processor in your authorization request. For more information, see Implementing Payer Authentication with the SDK.

Before you begin implementing the SDK, you must generate an API key. See the "Generate Your API Key" step in Android SDK Setup or iOS SDK Setup.

Mobile Device Data Collected

One of the key components to authenticating a cardholder during an online transaction is to compare information about the mobile device that the buyer is using to the information about mobile devices that the buyer used in past transactions. This information is maintained in the access control server (ACS) at the issuing bank.

In mobile device transactions, information collected about the buyer device can include:

• Device ID
• Device model
• Operating system version
• System language
• Country
• Time zone
• Screen dimensions

A successful device data collection process that includes the eleven browser fields listed in the check enrollment step increases the chances of a frictionless authentication. Business rules configured in the issuer's risk analysis software determine whether a transaction is risky enough to require challenging the buyer to authenticate their identity.