Skip to main content

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​

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.

using TrustFactorSDK.V2;
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 client = 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 or handle callbacks from TrustFactor Services. This is done by calling clientBuilder.Build() method from ClientBuilder

After Client 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 SendRequest for general requests, or CreateTransaction for creating a transaction.

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 :

  • Registration - a user has registered with TrustFactor
  • Transaction Decision - a user has approved or rejected an authentication with TrustFactor
  • Device Removal - a user has removed a device associated with TrustFactor
  • Contract Sharing - a user has shared their profile with another TrustFactor device / app
  • Contract Recovery - a user has recovered their profile on a new TrustFactor app through a Recovery Code

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 HandleCallback method from the Client with the appropriate input object.

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, but this time instead of calling the HandleCallback method from Client, the developer should call GetSIBSRegisterTokenRequest method from the Client. Furthermore, instead of just returning a 200 HTTP status code the developer must call HandleSIBSResponse method from Client with the SIBS activation code. The HandleSIBSResponse 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.