Skip to main content

Walkthrough

Register a Contract​

To create a contract you need to instantiate a RegisterCodeV2 object. You will need to insert the App User ID (which identifies the user in TrustFactor services), Username (that is shown to the user and listed in backoffice), the duration of the code and, optionally, auxiliary data. You can also activate the RequirePreciseLocation flag, which requires the registration made with this code to be performed with a precise (GPS) device location.

The recovery of transaction history depends on the contract’s app user ID. That is, if an application wants the user to continue to have access to the transaction history after the registration of a new contract, then it has to reuse the same app user ID that it he had before.

using TrustFactorSDK.V2;
using TrustFactorSDK.V2.Requests;
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();
    
    // Creates a register code request
    int duration = 60; // code duration of 60 seconds
    RegisterCodeV2.Params request = new RegisterCodeV2.Params(appUniqueID, appUsername, duration, null);
    // Optionally, require the registration to be made with a precise (GPS) device location
    request.RequirePreciseLocation = true;
}

After the request is created we need to send it to the TrustFactor services, and we do it by calling the SendRequest method in the ApplicationConfig.

using TrustFactorSDK.V2;
using TrustFactorSDK.V2.Requests;
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();
    
    // Creates a register code request
    int duration = 60; // code duration of 60 seconds
    RegisterCodeV2.Params request = new RegisterCodeV2.Params(appUniqueID, appUsername, duration, null);
    // Optionally, require the registration to be made with a precise (GPS) device location
    request.RequirePreciseLocation = true;
    
    // Sends a register code request
    RegisterCodeV2.Response response = client.SendRequest<RegisterCodeV2.Response>(request);
}

When we get the RegisterCodeV2 response we have two possible flows for the user to complete the registration:

  • DeepLink URL
  • QR Code

The DeepLink URL is used when the user is in a mobile device and can’t scan the QR Code from their own screen. This allows him to tap a button that redirects him to the mobile application and completes the registration. With the QR Code there are two possible options. Either with the QR Code URL or with the QR Code image.

  • QR Code URL - Made for a custom HTTP client or to obtain the payload parameter (which is in the URL) and generate the QR Code
  • QR Code - Returns a Base64 encoded image with a QR Code that the user should scan in order to complete the registration

The registration QR Code encodes the registration DeepLink URL itself. This means that, besides being readable by the agent application’s in-app scanner, the QR Code can also be scanned with the device’s native camera application, which opens the deep link and redirects the user straight to the agent application to complete the registration.

Note that for the SDK to obtain the Base64 encoded QR Code it needs to call the TrustFactor Services. Consequently, if the application has a tool to generate the QR Codes it can do so, while saving some network traffic.

Depending on the platform (web or mobile) the user is on, you may want to adjust their registration flow accordingly.

using TrustFactorSDK.V2;
using TrustFactorSDK.V2.Requests;
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();
    
    // Creates a register code request
    int duration = 60; // code duration of 60 seconds
    RegisterCodeV2.Params request = new RegisterCodeV2.Params(appUniqueID, appUsername, duration, null);
    // Optionally, require the registration to be made with a precise (GPS) device location
    request.RequirePreciseLocation = true;
    
    // Sends a register code request
    RegisterCodeV2.Response response = client.SendRequest<RegisterCodeV2.Response>(request);
    
    // Handles the response 
    var size = 400;  // Size in pixels of the qr code
    string deeplinkUrl = client.GenerateRegistrationDeeplinkURL(response);
    string qrCodeUrl = client.GenerateRegistrationQRCodeURL(response, size);
    string qrCode = client.GetRegistrationQRCode(response, size);
}

Finally, when the user finishes the contract registration the TrustFactor services send a callback to notify the 3rd-party application that the user finished the registration. The callback contains information such as the device key, contract key, app user id and device info.

using TrustFactorSDK.V2;
using TrustFactorSDK.V2.Callbacks;
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();
    
    string data; // received in the request body, HTTP server logic not shown here
    Register register = client.HandleCallback<Register>(data);
}

Create a Transaction​

To create a transaction you first need to instantiate the wanted object such as GenericTransaction for a generic transaction. Keep in mind that there may be several versions of the GenericTransaction class, therefore always use the most recent one to get the latest features.

Old method versions are kept for compatibility reasons and may be deprecated in future SDK versions.

using TrustFactorSDK.V2;
using TrustFactorSDK.V2.Requests;
using TrustFactorSDK.V2.Models.TransactionCreation.V3;
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();
    
    // Creates a generic transaction
    GenericTransaction transaction = new GenericTransaction
    {
        Message = "Test",
        ActionName = "Action",
        TransactionDuration = 30,
        Core = new Core
        {
            MetaData = new TrustFactorSDK.V2.Models.Metadata
            {
                Timestamp = 1619705292,
                UserAgent = "TrustFactor CSharp SDK",
                Platform = "",
                Channel = "Mobile",
                SourceIP = "1.2.3.4"
            }
        },
        CustomHeaders = 
        new Dictionary<string, string>() { { "X-Custom-Header", "Header value" } }
    };
}

After creating the request object you will need to call an ApplicationConfig method, in this case you will need to use either CreateTransactionV3WithUserID or CreateTransactionV3WithKey to create the transaction, respectively with the User ID or the Contract Key. For this example we opted for the CreateTransactionV3WithUserID.

using TrustFactorSDK.V2;
using TrustFactorSDK.V2.Requests;
using TrustFactorSDK.V2.Models.TransactionCreation.V3;
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();
    
    // Creates a generic transaction
    GenericTransaction transaction = new GenericTransaction
    {
        Message = "Test",
        ActionName = "Action",
        TransactionDuration = 30,
        Core = new Core
        {
            MetaData = new TrustFactorSDK.V2.Models.Metadata
            {
                Timestamp = 1619705292,
                UserAgent = "TrustFactor CSharp SDK",
                Platform = "",
                Channel = "Mobile",
                SourceIP = "1.2.3.4"
            }
        },
        CustomHeaders = new Dictionary<string, string>() { { "X-Custom-Header", "Header value" } }
    };
    
    // Send the create generic transaction
    CreateTransactionV3WithUserID.Response response = 
      client.CreateTransactionV3WithUserID
        <CreateTransactionV3WithUserID.Response>("john.doe", transaction);
}

When the generic transaction request is completed a CreateTransactionV3WithUserID response is created, inherited from a generic response class GenericResponse. The response contains the transaction Unique ID, the Contract Key as well as the fields from the GenericResponse presented earlier.

Transactions can also require a precise device location and a confirmation code. When the RequirePreciseLocation flag is active, the user’s agent must send a precise (GPS) device location when deciding the transaction. When the RequireConfirmationCode flag is active, TrustFactor services generate a confirmation code for the transaction and return it in the response’s ConfirmationCode field, containing the generated Code and the full list of Options presented on the user’s agent. The application should display the Code on the channel that initiated the transaction, so the user can pick the matching option on their agent to approve it. The number of options and their number of digits can be customized through the transaction’s ConfirmationCode settings. Please check the Transactions in depth chapter for further information.

Apart from deciding a transaction using a push notification, a transaction deep link url can also be used on mobile. The GenerateTransactionDeeplinkURL can be used when the user is in a mobile device and does not receive a notification for the transaction. This allows him to tap a button that redirects him to the mobile application and decide the transaction.

using TrustFactorSDK.V2;
using TrustFactorSDK.V2.Requests;
using TrustFactorSDK.V2.Models.TransactionCreation.V3;
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();
    
    // Creates a generic transaction
    GenericTransaction transaction = new GenericTransaction
    {
        Message = "Test",
        ActionName = "Action",
        TransactionDuration = 30,
        Core = new Core
        {
            MetaData = new TrustFactorSDK.V2.Models.Metadata
            {
                Timestamp = 1619705292,
                UserAgent = "TrustFactor CSharp SDK",
                Platform = "",
                Channel = "Mobile",
                SourceIP = "1.2.3.4"
            }
        },
        CustomHeaders = new Dictionary<string, string>() { { "X-Custom-Header", "Header value" } }
    };
    
    // Send the create generic transaction
    CreateTransactionV3WithUserID.Response response = 
      client.CreateTransactionV3WithUserID
        <CreateTransactionV3WithUserID.Response>("john.doe", transaction);
        
    string transactionURL = client.GenerateTransactionDeeplinkURL(response)
}

When the user decides the transaction or when it expires, TrustFactor services will send a callback to the 3rd-party application notifying its final status.

using TrustFactorSDK.V2;
using TrustFactorSDK.V2.Callbacks;
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();
    
    string data; // received in the request body, HTTP server logic not shown here
    Transaction transaction = client.HandleCallback<Transaction>(data);
}

Handle SIBS callback​

When the application receives this callback it means that SIBS transactions v2 are active, and the user needs an activation code to communicate with the MBWay SDK.

using TrustFactorSDK.V2;
using TrustFactorSDK.V2.Util.Crypto;
using TrustFactorSDK.V2.Models;
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();
    
    string data; // received in the request body, HTTP server logic not shown here
    GetSIBSRegisterTokenRequest regCodeRequest = client.HandleSIBSRequest(data);
    
    // Requests SIBS activation code
    
    string seeAtvCodSdk = "see_atv_cod_sdk"; // registration token for SIBS
    Envelope envelope = client.HandleSIBSResponse(seeAtvCodSdk);
}