3DS Mobile SDK (iOS)

Note: Native mobile support is a new feature of 3DS2, for responses that are 3DS1 a webview is required for the challenge.

On this page

Get started

Before you begin integration, you must:

  1. Contact your Worldpay Relationship Manager to request the use of 3DS Mobile SDK and 3DS Flex
  2. Receive confirmation from your Worldpay Relationship Manager that your account has been created
  3. Have received your Cardinal SDK credentials from your Worldpay Support Team

SDK integration overview

This guide takes elements from Cardinal (Mobile SDK) and Worldpay (3DS Flex) documentation to provide step by step instructions for iOS integration.

Note: This content is updated periodically.
If you have questions, or require additional support, please contact your Worldpay support team.

Access the Cardinal SDK for iOS

Download the CardinalMobile.framework/CardinalMobile.scframework file using the following cURL. You will need to include the username provided by your Worldpay Relationship Manager.

curl -L -u <USER_NAME>


curl -L -UserName:ApiKey "" -o

In your XCode project, drag CardinalMobile.framework file into the Frameworks group in your Xcode Project (create the group if it doesn't already exist). In the import dialog, tick the box to Copy items into destinations group folder (or Destination: Copy items if needed). The iOS SDK files are now available for linking to your project.

Add the cardinalMobile.framework

  1. Open Xcode and click on your project in the source list to the left of the main editor area
  2. Select your application under the Targets section and go to the General tab
  3. Expand the Embedded Binaries section then click the small “+” button at the bottom of the list
  4. Add the CardinalMobile.framework from the list

Configure the Mobile SDK

Mobile SDK for iOS

Create a new instance of the cardinal object by [CardinalSession new]. Multiple configuration options are available (if not specified, everything is set to default). Use the code snippet below to complete the configuration.

Note: Call method <getWarnings> to get the list of all the warnings for the particular device. Take further action based on the warnings found. List of warnings can be accessed as follows: NSArray*warnings = [session getWarnings]; Contact your Worldpay Support Team for further details.

Setup the initial call

Setup the initial call

Calling Cardinal Session Setup will begin the communication process with Cardinal. To ensure your user's experience is seamless Cardinal authenticate your credentials (serverJwt) and complete the data collection process. The data collection process includes DDC (Device Data Collection). All necessary pre-processing is complete by the time the shopper is ready to checkout. Use the code snippet below for completing the cardinal session setup.

The following function call must be placed in your Checkout ViewController.

Send the initial request (WPG)

In the initial request you must include the sessionId returned in the setup call response. Submit the sessionId as the dfReferenceId in your XML payment request. An authentication request is submitted by WPG to Cardinal Commerce, to determine if a challenge is required.

Note: If you use Split authentication from Worldpay, you must send the request with <paymentDetails action="AUTHENTICATE">. Refer to theSplit authentication guidefor details. If you require further assistance, please contact your Worldpay Relationship Manager or Worldpay Support team.

Receive the response (WPG)

In the response you receive the dfReferenceId and payload. The dfReferenceId and payload must be sent from your server to the Mobile SDK on the shopper's mobile device. The Mobile SDK controls the process on the mobile device. The information in the payload determines whether the shopper is presented with a success screen, or the challenge screen.

Ensure you can handle the WPG first response

WPG handles the cmpi_lookup request. Check the CMPI_Lookup_Response for the following fields :

ThreeDSVersion = 2.X ( 2.0, 2.1, etc) Enrolled = Y PAResStatus = C

Upon validating the above fields, you will call [session continueWithTransactionId.. ] to hand control to SDK for performing the challenge between the user and the issuing bank. Use the code snippet below for completing the session's continue.

cardinal session continue is updated without the hardcoded directoryServerID.

[session continueWithTransactionId: @"[TRANSACTION_ID]" payload: @"[PAYLOAD]" directoryServerID: CCADirectoryServerIDVisa didValidateDelegate: self];

In continue for Quick Integration, a class conforming to a protocol CardinalValidationDelegate (and implement a method stepUpDidValidate) should be passed as a parameter. Following is the example of class conforming to CardinalValidationDelegate protocol.

3DS2 challenge

The shopper completes the 3DS2 authentication challenge. To complete the authorisation process you must send a second call to WPG.

Note: You must include the WPG sessionId included in the first request as the sessionId to WPG not as the dfReferenceId.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE paymentService PUBLIC "-//WorldPay//DTD WorldPay PaymentService v1//EN"""&gt;
<paymentService version="1.4" merchantCode="YOUR_MERCHANT_CODE">
   <order orderCode="YOUR_ORDER_CODE">
     <session id="ssn42abcd023">

Second request (WPG)

Use this request for the ReturnUrl to trigger the second request (remember to also set the machine cookie on the Cookie HTTP header):

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE paymentService PUBLIC "-//Worldpay//DTD Worldpay PaymentService v1//EN" "" >
<paymentService version="1.4" merchantCode="YOUR_MERCHANT_CODE">  
    <order orderCode="YOUR_ORDER_CODE"> <!--The order code supplied in the first request-->
      <session id="SESSION_ID"/> <!--The session id supplied in the first request-->

Be sure sure to include the same orderCode and session id you used in the initial request. You must also include the Machine Cookie received in the header of the first response.

You receive a Worldpay response with the payment outcome.

For additional support, and to request a full app example, contact your Worldpay support team.

JWT validation

Once the response JWT arrives in the onValidated, you will need to send the response JWT to your backend for verification and consumption. We recommend that any values sent to 3rd parties are sourced from the response JWT after it has been properly validated.

Warning: For security reasons, all JWT validation must be done on the server side.