First Steps

Before you begin

There are two types of TrustFactor Agent applications (mobile apps):

TrustFactor App - maintained by SecuritySide for Android and iOS
CustomApps - built and customized for customers, this option may have different features and allow for more API calls than the TrustFactor App.

CustomApps have their own dedicated cloud environment and so will have a different endpointUrl than the TrustFactor App. With their own cloud environment, they allow better control over the BackOffice and also extended functionality as is the case of embedding the SIBS MBWay SDK in order to perform 3D-Secure credit card payment authorizations through the TrustFactor Agents.

Throughout this document, if a particular API or functionality requires a CustomApp, it will be noted through a “CustomApps only” reference.

Client and Callback Handler

Before starting to integrate the TrustFactor SDK in their application, the developer should have the following necessary data:

Endpoint Address - Ensure there are no network policies restricting an HTTP Connection to/from the endpoint
Endpoint Public Key - Authenticates communications to the TrustFactor services
TrustFactor Public Key - Authenticates communications to your application on the TrustFactor services
Application Private Key - This is a secret value that the application should save, and it should not be shared with anyone else but the client

All of these settings can be set or changed through the Application Settings on the TrustFactor BackOffice. Please check the BackOffice documentation for more information.

To instantiate the Client there is a new ClientBuilder to help with the secondary endpoint and secondary endpoint pub. This new secondary properties are obligatory, but can be the same as the primary property maintaining the same behavior as the previous Client.

import com.securityside.trustfactor.client.Client;
import com.securityside.trustfactor.client.ClientBuilder;
import com.securityside.trustfactor.util.exception.CryptoException;

public class Main {
    public static void main(String[] args) {
        ClientBuilder clientBuilder = new ClientBuilder();
        clientBuilder.SetPrimaryEndpoint("https://applications.trustfactor.app");
        clientBuilder.SetSecondaryEndpoint("https://applications.trustfactor.app");
        clientBuilder.SetPrimaryEndpointPub(new PublicKey("WMIskJyIJo36PO93Qju351cL0CDAuM8KYXTj3hoaYHw="));
        clientBuilder.SetSecondaryEndpointPub(new PublicKey("WMIskJyIJo36PO93Qju351cL0CDAuM8KYXTj3hoaYHw="));
        clientBuilder.SetTFPub(new PublicKey("craE8nZ9eCjUOFwArwTqfdNuruUrDtCNIQhYBt4vyYQ="));
        clientBuilder.SetAppPriv(new PrivateKey("redacted"));
        clientBuilder.SetDeeplinkBaseURL("https://open.trustfactor.securityside.com");
        Client appClient = clientBuilder.Build();
    }
}

The first step in order to use the SDK is to instantiate a Client object which acts as a Client. This is the central point which you can use in order to make API Calls to TrustFactor Services. This is done by calling clientBuilder.Build() method from ClientBuilder

In order to handle callbacks you will need to instantiate a CallbackHandler object, using the CallbackHandlerBuilder, the same way as ClientBuilder.

import com.securityside.trustfactor.callback.CallbackHandler;
import com.securityside.trustfactor.callback.CallbackHandlerBuilder;
import com.securityside.trustfactor.util.exception.CryptoException;

public class Main {
    public static void main(String[] args) {
        CallbackHandlerBuilder callbackBuilder = new CallbackHandlerBuilder();
        callbackBuilder.SetPrimaryEndpoint("https://applications.trustfactor.app");
        callbackBuilder.SetSecondaryEndpoint("https://applications.trustfactor.app");
        callbackBuilder.SetPrimaryEndpointPub(new PublicKey("WMIskJyIJo36PO93Qju351cL0CDAuM8KYXTj3hoaYHw="));
        callbackBuilder.SetSecondaryEndpointPub(new PublicKey("WMIskJyIJo36PO93Qju351cL0CDAuM8KYXTj3hoaYHw="));
        callbackBuilder.SetTFPub(new PublicKey("craE8nZ9eCjUOFwArwTqfdNuruUrDtCNIQhYBt4vyYQ="));
        callbackBuilder.SetAppPriv(new PrivateKey("redacted"));
        CallbackHandler handler = callbackBuilder.Build();
    }
}

After the Client and CallbackHandler initialization, everything is ready to properly communicate with TrustFactor services.

Send Request

In order to call TrustFactor services we need to instantiate the intended request, and then use the Client (created earlier) to call the method for the request. Every request for the TrustFactor services has an associated method in the Client.

All the requests’ responses extend an abstract class called GenericResponse, that have generic fields for all responses such as a dictionary with error codes, if any occurred, the request correlation id, and the HTTP status code.

Handle Callbacks

When the TrustFactor services need to communicate some change, they do so by sending a request to the application, from now on referred to as a callback. There are five different types of callbacks, with detailed explanations in the Callbacks section :

Callback	Description	Callback Handle Method
Registration	A user has registered with TrustFactor	`handleRegisterCallback`
Transaction Decision	A user has approved or rejected an authentication with TrustFactor	`handleTransactionCallback`
Device Removal	A user has removed a device associated with TrustFactor	`handleRemoveDeviceContractCallback`
Contract Sharing	A user has shared their profile with another TrustFactor device	`handleShareContractCallback`
Contract Recovery	A user has recovered their profile on a new TrustFactor app through a Recovery Code	`handleContractRecoverCallback`

There is a Production Mode setting on the backoffice when a callback fails. Please consult the Backoffice manual for further information about the Production Mode.

The application developer must expose five different routes, one for each callback type. The resulting URLs must be configured through the TrustFactor BackOffice (see the BackOffice documentation for more information).
After the five routes are exposed in an HTTP Server, to handle the callbacks using the SDK, one needs only to call the respective method from the CallbackHandler with the respective input.

When SIBS transactions v2 are active, there is an additional callback for SIBS transactions that functions in a slightly different way.
The application developer still needs to expose an HTTP route specific for the callback, this time calling the handleGetSIBSRegisterTokenRequest method from CallbackHandler. Furthermore, instead of just returning a 200 HTTP status code the developer must call handleGetSIBSRegisterTokenResponse method from CallbackHandler with the SIBS activation code. The handleGetSIBSRegisterTokenResponse method returns an Envelope object with the encrypted data that should be JSON serialized and sent in the body of the response.
An example of this callback can be seen here.

Please consult the BackOffice documentation for further information about SIBS transactions v2 activation.

First Steps

Before you begin​

Client and Callback Handler​

Send Request​

Handle Callbacks​

Before you begin

Client and Callback Handler

Send Request

Handle Callbacks