Link Search Menu Expand Document

Simplified 3DS Interface

Table of contents
  1. Overview
  2. Actors & flow diagram
  3. Initialization
  4. Authenticating
    1. Android
      1. The AuthSpec parameter
      2. The authCallbacks parameter
      3. The complete example
    2. iOS
  5. How SDK calls back from authenticate?


The simplified interface gives the application developer a single method to perform the complete 3DS flow behind the scenes and does not require auth parameters, passing them to the backend, or parsing ARes to find out whether a challenge flow is requested and so on and so forth. The simplified interface gives a single authenticate method that performs the whole 3DS transaction and notifies the application in the end.

Actors & flow diagram

When the simplified interface is used, the mobile SDKs expect the requestor backend to expose two endpoints. The SDKs call the endpoints at different moments of a 3DS transaction lifecycle. The two endpoints are:

  1. Supported Versions
  2. Authenticate

The application needs to pass the two URLs for the endpoints above along with other transaction data in authenticate method as described further in this document.

The endpoints are then called by SDK in sequence. It first calls the “Supported Versions” endpoint to get one or more Directory Servers for given account number. Then, when a Directory Server is known, it calls “Authenticate” which essentially performs a 3DS transaction.

Note, the SDK will prompt the user to pick a Directory Server if there were more than one returned from the “Supported Versions” endpoint.


For initialization is uses the initialize method that is shown in Pure 3DS Interface section.


When the user makes a purchase, the authenticate method is called.


The method is called like this:

threeDS2Service.authenticate(authSpec, authCallback);

The authSpec argument encloses the parameters the SDK needs in order to perform a transaction and the authCallback object is what the SDK calls back when a 3DS transaction completes.

Warning - avoid parallel execution authenticate method and make sure it is called in the main thread because it may need interaction with user via UI.

The AuthSpec parameter

The parameter encapsulates all the data the app passes to the SDK in authenticate method:

public class AuthSpec {

    // An Android activity instance that invokes authenticate method.
    // Requred.
    private Activity currentActivity;

    // An identifier of card what will be used during transaction. 
    // It can be either account number or an identifier of a card 
    // in the wallet/profile.
    // Required.
    private String cardId;

    // This is an arbitrary object that SDK will convey to the 
    // Merchant Backend. It is the recommended place to put purchase related
    // information in, such as the purchase amount, the line items, etc.
    // Required.
    private PurchaseInfo purchaseInfo;

    // Is this a payment authentication? 
    //   TRUE  - payment 
    //   FALSE - non-payment (adding a card to the wallet for instance)
    private boolean isPaymentAuthentication;

    // An URL where the SDK sends a supported-versions request to get the DS 
    // for the transaction.
    // Required.
    private String supportedVersionsURL;

    // A URL where the SDK sends a authentication data to
    // Required.
    private String authURL;

    // If the requestor backend (Gateway) requires user authorization, 
    // then here the app passes the HTTP Headers that SDK will include 
    // when sending requests to the four URLs above.
    // Optional. An empty map is assumed if not passed.
    private Map<String, String> authorizationHeaders;

The authCallbacks parameter

This is an interface used by the SDK to call the Android application back when transaction finishes, gets canceled by the user, or gets erred:

public interface AuthCallback {

    // called when the transaction completed successfully - transStatus is Y, A, I
    void authenticated(String threeDSServerTransID, TransStatus status);

    // called when the transaction NOT completed successfully - transStatus is N, U, R etc
    void notAuthenticated(String threeDSServerTransID, TransStatus status);

    // If decoupled auth (transStatus=D), 
    // then the result will be known latter. So the app should check on server 
    // for results later.
    void decoupledAuthBeingPerformed(String threeDSServerTransID, TransStatus status);

    // User cancels the transaction
    void cancelled(String threeDSServerTransID);

    // Error case
    void error(String threeDSServerTransID, Exception error);

The complete example

AuthSpec authSpec = new AuthSpec();

Map<String, String> authorizationHeaders = new HashMap<>();
// add parameters to authorizationHeaders

authSpec.setPurchaseInfo(new PurchaseInfo() {
    public JSONObject toJson() {
        // return JSONObject with purchase info here

threeDS2Service.authenticate(authSpec, new AuthCallback() {
    public void authenticated(String transId, TransStatus transStatus) {
        // handle success authentication here

    public void notAuthenticated(String transId, TransStatus transStatus) {
        // handle unsuccess authentication here

    public void decoupledAuthBeingPerformed(String transId, TransStatus transStatus) {
        // handle decoupled authentication here

    public void cancelled(String transId) {
        // handle canceled authentication here

    public void error(String transId, Exception e) {
        // handle error during authentication here


The method is called like this:

    authenticationSpec: authSpec, 
    delegate: authDelegate, 
    currentViewController: viewController)

How SDK calls back from authenticate?

The following diagram explains how the SDK calls the app back and when. It applies to both Android and iOS platforms.