Skip to content

3D Secure Authentication

Jump to bottom
Josh Monroe edited this page Jan 23, 2019 · 6 revisions

3-D Secure Authentication

Basic 3-D Secure Transaction Lifecycle

3DS Flow

Components

  • Merchant Mobile App: A mobile app integrated with the Gateway Mobile SDK
  • Merchant Web Service: A web service, hosted and maintained on the merchant's servers, which will handle sending authenticated requests to the Gateway.
  • Gateway: An instance of your Gateway provider.
  • Gateway SDK 3DS Web View: A component of the SDK that help render web pages required during the 3DS authentication flow.
  • Issuer Authentication Page: A web page, hosted by the issuing bank of the card being processed. This page will prompt a card holder for additional authentication information then redirect the response to a page hosted on the merchant's servers.
  • Merchant Redirect Page: A landing page that accepts the Issuer's ACS response data and processes it with the Gateway. The resulting information is then sent back to the mobile app by appending it to a custom URL and redirecting the browser. See Merchant Redirect Page below for more information.

Note

API Response for the enrollment check & authnetication has changed for v47 and later. See below for details.

Steps

  1. The mobile app requests a new Session from the merchant service. This is an authenticated call, meaning it requires a private API password, which is why it needs to be carried out on a secure server, rather than the mobile device.
  2. The merchant service calls Create a Session on the Gateway.
  3. Information about the newly created session is returned to the merchant service, including the Session Id.
  4. The Session Id + the version of the API used to create it is returned back to the mobile app. Updating the session with card details must use the same Gateway API version number that created it.
  5. Card information is collected from the card holder and sent directly to the Gateway using the SDK method provided.
  6. A success / fail message is returned to the app in the appropriate callback method.
  7. The mobile app requests the merchant server check for 3DS enrollment using the Session Id containing the new card details.
  8. The merchant service calls Check 3DS Enrollment on the Gateway, including the redirect URL that will be used during the 3DS operation.
  9. An enrollment status message is returned to the merchant service, including HTML needed in the mobile SDK web view. (There are 2 methods of generating this initial 3DS page. For simplicity, we are illustrating a solution using pageGenerationMode = 'SIMPLE')
  10. The enrollment status and HTML is then returned to the mobile app.
  • v46 & below check gatewayResponse.3DSecure.summaryStatus
  • v47 & above check gatewayResponse.response.gatewayRecommendation
  1. If enrolled, the mobile app passes the HTML (and an optional page title) to the SDK-provided 3DS web view, where the card holder carries out authentication with their Issuer. If not enrolled, skip to step 13.
  2. After authentication, the Issuer redirects response data to a Merchant Redirect Page. That page process this data and passes back the Gateway3DSecureResult to the app using a custom URL scheme.
  • v46 check 3DSecure.summaryStatus
  • v47 check response.gatewayRecommendation
  1. The app then requests to complete the transaction by sending the 3DSecureId to the merchant service.
  2. The merchant service performs the appropriate transaction operation with the Gateway.
  3. The Gateway returns the summary of the transaction attempt to the merchant service.
  4. The success / fail status is returned to the mobile app.

Implementation

To support 3-D Secure 1.0 transactions, the Gateway SDK provides a view controller that you can use in your app to help display the 3-D Secure HTML and handle web-page redirects during the process. *Refer to the Basic Transaction Lifecycle wiki page for information on how to collect card information with the SDK.

// create the Gateway3DSecureViewController
let threeDSecureView = Gateway3DSecureViewController(nibName: nil, bundle: nil)

// Optionally, customize the presentation
threeDSecureView.title = "3-D Secure Auth"
threeDSecureView.navBar.tintColor = UIColor(red: 1, green: 0.357, blue: 0.365, alpha: 1)

// present the 3DSecureViewController
present(threeDSecureView, animated: true)

While the view is presenting, Provide the 3-D Secure view controller with the html body content that was received from the call to check 3-D Secure enrollment and a completion handler to handle the result. The authentication lifecycle will take place within the WKWebView contained in this view controller and a status message (or error) will be returned to the caller via the completion closure passed to the authenticatePayer function.

// provide the html content and a handler
threeDSecureView.authenticatePayer(htmlBodyContent: "HTML STRING FROM CHECK ENROLLMENT") { (threeDSView, result) in
  // dismiss the 3-D Secure view controller
  threeDSView.dismiss(animated: true)

  // handle the result case
  switch result {
  case .completed(status: "<FAILED STATUS>", id: _):
    // failed authentication
  case .completed(status: _, id: let id):
    // continue with the payment for all other statuses
  default:
    // authentication was cancelled
  }
}

Merchant Redirect Page

When 3-D Secure authentication completes, the Issuer's ACS will redirect the phone's browser to the URL provided during Check Enrollment Status. For apps using the Gateway SDK, this is expected to be a URL to a page hosted by your merchant service. That page should accept the PaRes data from the redirect and process it with the Gateway using the Process ACS Result method. The response data from this call should be placed in a mobile-specific redirect URL containing summaryStatus and 3DSecureID. The structure of that URL should be gatewaysdk://3dsecure?summaryStatus=&3DSecureId=. This is the URL pattern that signals to the SDK that 3-D Secure authentication is complete and the result has been processed. The SDK will then deliver the message back to the app thru the appropriate callback method.

Clone this wiki locally