Transactions in depth

In this chapter we will go in depth about how to create transactions, starting from what type you can create, what transactions need operation and the parameters each transaction takes. For further information about risk modules and how to create them, please visit Risk Modules In Depth chapter.

For some transaction types, specifically NormalTransaction and ActionableTransaction, an operation created in backoffice is needed. So for the sake of the examples assume there is a transfer operation created on the backoffice, identified as Attachment #1 on Attachments chapter.

Normal Transaction

Attribute	Description	Optional
`Action`	Overrides `Operation` defined preferred	No
`Core`	Please check `Core` in the Models chapter for further information	No
`MessageEngine`	Please check `Message Engine` in the Models chapter for further information	No

using TrustFactorSDK.V2.Models.TransactionCreation.V3;
using TrustFactorSDK.V2.Models.TransactionCreation.V3.Auxiliary;

class TestTransactions
{
    static void Main(string[] args)
    {
        NormalTransaction normalTransaction = new NormalTransaction
        {
            Action = "transfer",
            Core = new Core
            {
                MetaData = new Metadata
                {
                    Timestamp = 1619705292,
                    UserAgent = "TrustFactor CSharp SDK",
                    Platform = "",
                    Channel = "Mobile",
                    SourceIP = "1.2.3.4"
                }
            },
            MessageEngine = new MessageEngine
            {
                Language = "",
                Message = "This is a message to show to the user",
                MsgIdentifier = ""
            }
        };
    }
}

Actionable Transaction

Attribute	Description	Optional
`Action`	The action of an operation defined in the backoffice	No
`MessageEngine`	Please check `Message Engine` in the Models chapter for further information	No
`Core`	Please check `Core` in the Models chapter for further information	No
`CustomHeaders`	Custom headers are sent along with transaction decision callback. One possible use case scenario would be setting an ID, so the application could correlate the transaction decision request received from TrustFactor services with the one that led to the transaction creation.	Yes
`RequiredAuthentications`	Authentications required to approve the transaction. The possible values come from `Authentication Mechanism` enum.	Yes
`RequirePreciseLocation`	When active, the user’s agent must send a precise (GPS) device location when deciding the transaction.	Yes
`RequireConfirmationCode`	When active, a confirmation code is generated for the transaction and the user must pick the matching option on their agent to approve it. The generated code is returned in the create transaction response, on the `ConfirmationCode` field.	Yes
`ConfirmationCode`	Settings for the generated confirmation code, such as the number of options presented to the user and the number of digits. Please check `Confirmation Code Settings` in the Models chapter for further information. Should only be filled when `RequireConfirmationCode` is active.	Yes
`OverrideRiskCalculation`	You can optionally define the risk of the transaction and / or the parameters as well as the message that is displayed in the risk of the parameters if you activate this flag.	Yes
`Risk`	Sets the transaction risk when the flag `OverrideRiskCalculation` is active. It is possible, but not obligatory when you fill `Risk` field, to fill `Risk` and `RiskMessage` fields from Params. The values from `Risk` and `Risk` and `RiskMessage` fields from Params should be null when the flag `OverrideRiskCalculation` is not active. The values that are possible for `Risk` field of the transaction are in the `Risk Level` enum.	Yes
`Params`	The `Params` are used to send information in the transaction, by setting the values of the operation parameters, obeying the operation template. Each key of the `Params` dictionary corresponds to a key of the params of the operation defined in the `Key` field. Every parameter of the operation should be defined in the `Params` field of the transaction if the flag `Optional` is turned off, otherwise the parameter doesn’t need to be filled. That way we can guarantee that a transaction has the mandatory parameters defined in the operation filled.	Yes
`RiskModules`	Additional parameters for the risk modules calculation. For example the origin coordinates of the transaction to be used by `lrc` risk module. The risk modules calculated are defined in the operation. In the example of `transfer` operation, both `ip_reputation` and `lrc` are to be calculated, but they are not mandatory, meaning they can fail but the transaction will proceed anyway, ignoring the risk score that would have been returned from the risk module.	Yes

using System.Collections.Generic;
using TrustFactorSDK.V2.Constants;
using TrustFactorSDK.V2.Models.TransactionCreation.V3;
using TrustFactorSDK.V2.Models.TransactionCreation.V3.Auxiliary;
using TrustFactorSDK.V2.Models.TransactionCreation.V3.Auxiliary.RiskModules.input;

class TestTransactions
{
    static void Main(string[] args)
    {
        ActionableTransaction actionableTransaction = new ActionableTransaction
        {
            Action = "transfer",
            MessageEngine = new MessageEngine
            {
                Language = "",
                Message = "This is a message to show to the user",
                MsgIdentifier = ""
            },
            Core = new Core
            {
                MetaData = new 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" } },
            RequiredAuthentications = new List<AuthenticationMechanism>
            {
                AuthenticationMechanism.AuthenticationBiometrics,
                AuthenticationMechanism.AuthenticationPassword
            },
            RequirePreciseLocation = true,
            RequireConfirmationCode = true,
            ConfirmationCode = new ConfirmationCodeSettings
            {
                Options = 3,
                Digits = 2
            },
            OverrideRiskCalculation = true,
            Risk = RiskLevel.Low,
            Params = new Dictionary<string, Param>
            {
                {
                "source_account", new Param
                    {
                        Value = "leandro.pinto"
                    }
                },
                {
                "destination_account", new Param
                    {
                        Value = "hilario.coelho"
                    }
                },
                {
                "amount", new Param
                    {
                        Value = 100,
                        Aux = new Dictionary<string, dynamic>()
                        {
                            {
                                "currency", "EUR"
                            }
                        }
                    }
                }
            },
            RiskModules = new TransactionAgentInput()
            {
                Input = new Dictionary<RiskModule, IRiskModuleInput>()
                {
                    {
                        RiskModule.LRC,
                        new RiskModuleInputLRC(){
                            Lat = 41.15F,
                            Lon = -8.61024F,
                            Accuracy = 20 // accuracy in km
                        }
                    },
                    {
                        RiskModule.IPReputation,
                        new RiskModuleInputIPRep(){}
                    }
                }
            }
        };
    }
}

Generic Transaction

Attribute	Description	Optional
`Message`	Transaction message to be shown to the user	No
`Action`	This field is only used for filtering in the backoffice, not to be compared with `Action` field from `NormalTransaction` or `ActionableTransaction`. Ideally this field should be versioned, so when a change in the schema is made the version is bumped to keep track of the different parameters.	No
`TransactionDuration`	The duration of the transaction limited between 30 seconds and 150 seconds.	No
`Core`	Please check `Core` in the Models chapter for further information	No
`ActionName`	The action name for this transaction that the user will see in his Agent.	Yes
`CustomHeaders`	Custom headers are sent along with transaction decision callback. One possible use case scenario would be setting an ID, so the application could correlate the transaction decision request received from TrustFactor services with the one that led to the transaction creation.	Yes
`RequiredAuthentications`	Authentications required to approve the transaction. The possible values come from `Authentication Mechanism` enum.	Yes
`RequirePreciseLocation`	When active, the user’s agent must send a precise (GPS) device location when deciding the transaction.	Yes
`RequireConfirmationCode`	When active, a confirmation code is generated for the transaction and the user must pick the matching option on their agent to approve it. The generated code is returned in the create transaction response, on the `ConfirmationCode` field.	Yes
`ConfirmationCode`	Settings for the generated confirmation code, such as the number of options presented to the user and the number of digits. Please check `Confirmation Code Settings` in the Models chapter for further information. Should only be filled when `RequireConfirmationCode` is active.	Yes
`Risk`	Sets the transaction risk. The values that are possible are in the `Risk Level` enum. When filled the transaction will assume the defined risk, and the params risk should be filled as well if applicable.	Yes
`Params`	The `Params` are used to send information in the transaction, but does not obey an operation template. Meaning that the transaction can send whatever they want.	Yes
`RiskModules`	Additional parameters for the risk modules calculation. For example the origin coordinates of the transaction to be used by `lrc` risk module.	Yes
`RiskModulesAdded`	Additional risk modules that are shown to the user. New risk modules can be added to the output shown to the user	Yes
`RiskModulesToCalculate`	Risk modules to calculate and specify if they are mandatory, because there is not an operation to decide which risk modules to calculate	Yes

using System.Collections.Generic;
using TrustFactorSDK.V2.Constants;
using TrustFactorSDK.V2.Models.TransactionCreation.V3;
using TrustFactorSDK.V2.Models.TransactionCreation.V3.Auxiliary;
using TrustFactorSDK.V2.Models.TransactionCreation.V3.Auxiliary.RiskModules;
using TrustFactorSDK.V2.Models.TransactionCreation.V3.Auxiliary.RiskModules.input;
using TrustFactorSDK.V2.Models.TransactionCreation.V3.Auxiliary.RiskModules.output;
using TrustFactorSDK.V2.Models.TransactionCreation.V3.Auxiliary.RiskModules
    .output.Agent;
using TrustFactorSDK.V2.Models.TransactionCreation.V3.Auxiliary.RiskModules
    .output.Agent.EventData;
using Coordinates = TrustFactorSDK.V2.Models.TransactionCreation.V3.Auxiliary
    .RiskModules.output.Agent.EventData.Coordinates;

class TestTransactions
{
    static void Main(string[] args)
    {
        GenericTransaction genericTransaction = new GenericTransaction
        {
            Message = "Test",
            ActionName = "Action",
            Action = "test action",
            TransactionDuration = 30,
            Core = new Core
            {
                MetaData = new 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" } },
            RequiredAuthentications = new List<AuthenticationMechanism>
            {
                AuthenticationMechanism.AuthenticationBiometrics,
                AuthenticationMechanism.AuthenticationPassword
            },
            RequirePreciseLocation = true,
            RequireConfirmationCode = true,
            ConfirmationCode = new ConfirmationCodeSettings
            {
                Options = 3,
                Digits = 2
            },
            Risk = RiskLevel.Low,
            Params = new Dictionary<string, Param>
            {
                {
                "source_account", new Param
                    {
                        Value = "leandro.pinto"
                    }
                },
                {
                "destination_account", new Param
                    {
                        Value = "hilario.coelho"
                    }
                },
                {
                "amount", new Param
                    {
                        Value = 100,
                        Aux = new Dictionary<string, dynamic>()
                        {
                            {
                                "currency", "EUR"
                            }
                        }
                    }
                }
            },
            ParamsOrder = new Dictionary<string, long>()
            {
                {
                    "source_account", 0
                },
                {
                    "destination_account", 1
                },
                {
                    "amount", 2
                }
            },
            RiskModules = new TransactionAgentInput()
            {
                Input = new Dictionary<RiskModule, IRiskModuleInput>()
                {
                    {
                        RiskModule.LRC,
                        new RiskModuleInputLRC(){
                            Lat = 41.15F,
                            Lon = -8.61024F,
                            Accuracy = 20 // accuracy in km
                        }
                    },
                    {
                        RiskModule.IPReputation,
                        new RiskModuleInputIPRep(){}
                    }
                }
            },
            RiskModulesAdded = new TransactionAgentOutput()
            {
                Output = new Dictionary<string, TransactionRiskModuleOutput>()
                {
                    {
                        "new_risk_module",
                        new TransactionRiskModuleOutput()
                        {
                            AgentModuleOutput = new ModuleOutput()
                            {
                                Risk = RiskLevel.High,
                                Message = "Some message to the user to notify the risk level",
                                OnTap = new Map(
                                    new Coordinates(){
                                        Lat = 41.15F,
                                        Lon = -8.61024F,
                                        Accuracy = 20 // accuracy in km
                                    },
                                    "Origin Location",
                                    new Pinpoint(){
                                        Country = "Portugal",
                                        City = "Porto"
                                    }
                                ).CreateMapOutput()
                            }
                        }
                    }
                }
            },
            RiskModulesToCalculate = new TransactionRiskModulesToUse()
            {
                ModulesToUse = new Dictionary<RiskModule, TransactionRiskModuleToUse>()
                {
                    {
                        RiskModule.IPReputation,
                        new TransactionRiskModuleToUse(){
                            Mandatory = true
                        }
                    },
                    {
                        RiskModule.LRC,
                        new TransactionRiskModuleToUse(){
                            Mandatory = true
                        }
                    }
                }
            }
        };
    }
}

SIBS 3DS Transaction

Attribute	Description	Optional
`Message`	Transaction message to be shown to the user	No
`ActionName`	The action name for this transaction that the user will see in his Agent.	No
`TransactionDuration`	The duration of the transaction limited between 30 seconds and 150 seconds.	No
`Core`	Please check `Core` in the Models chapter for further information	No
`TypeData`	Information needed for the SIBS transaction. In this version it is not possible to input the SIBS details in the transaction, so the agent retrieves that information from SIBS. The drawback is that it is only possible to get the details one time with SIBS that will be with the first agent that registered in the MBWay SDK and consult them. If for instance you have two agents on your contract you cannot see the details on the second one (the one who didn’t perform the transaction)	No
`RequiredAuthentications`	Authentications required to approve the transaction. The possible values come from `Authentication Mechanism` enum.	Yes
`Risk`	Sets the transaction risk. The values that are possible are in the `Risk Level` enum. When filled the transaction will assume the defined risk, and the params risk should be filled as well if applicable.	Yes
`RiskModules`	Additional parameters for the risk modules calculation. For example the origin coordinates of the transaction to be used by `lrc` risk module.	Yes
`RiskModulesAdded`	Additional risk modules that are shown to the user. New risk modules can be added to the output shown to the user	Yes
`RiskModulesToCalculate`	Risk modules to calculate and specify if they are mandatory, because there is not an operation to decide which risk modules to calculate	Yes

using System.Collections.Generic;
using TrustFactorSDK.V2.Constants;
using TrustFactorSDK.V2.Models.TransactionCreation.V3;
using TrustFactorSDK.V2.Models.TransactionCreation.V3.Auxiliary;
using TrustFactorSDK.V2.Models.TransactionCreation.V3.Auxiliary.RiskModules;
using TrustFactorSDK.V2.Models.TransactionCreation.V3.Auxiliary.RiskModules.input;
using TrustFactorSDK.V2.Models.TransactionCreation.V3.Auxiliary.RiskModules.output;
using TrustFactorSDK.V2.Models.TransactionCreation.V3.Auxiliary.RiskModules
    .output.Agent;
using TrustFactorSDK.V2.Models.TransactionCreation.V3.Auxiliary.RiskModules
    .output.Agent.EventData;
using Coordinates = TrustFactorSDK.V2.Models.TransactionCreation.V3.Auxiliary
    .RiskModules.output.Agent.EventData.Coordinates;

class TestTransactions
{
    static void Main(string[] args)
    {
        SIBS3DSTransaction sibs3DSTransaction = new SIBS3DSTransaction()
        {
            Message = "Test",
            ActionName = "Action",
            TransactionDuration = 30,
            Core = new Core
            {
                MetaData = new Metadata
                {
                    Timestamp = 1619705292,
                    UserAgent = "TrustFactor CSharp SDK",
                    Platform = "",
                    Channel = "Mobile",
                    SourceIP = "1.2.3.4"
                }
            },
            RequiredAuthentications = new List<AuthenticationMechanism>
            {
                AuthenticationMechanism.AuthenticationBiometrics,
                AuthenticationMechanism.AuthenticationPassword
            },
            Risk = RiskLevel.Low,
            RiskModules = new TransactionAgentInput()
            {
                Input = new Dictionary<RiskModule, IRiskModuleInput>()
                {
                    {
                        RiskModule.LRC,
                        new RiskModuleInputLRC(){
                            Lat = 41.15F,
                            Lon = -8.61024F,
                            Accuracy = 20 // accuracy in km
                        }
                    },
                    {
                        RiskModule.IPReputation,
                        new RiskModuleInputIPRep(){}
                    }
                }
            },
            RiskModulesAdded = new TransactionAgentOutput()
            {
                Output = new Dictionary<string, TransactionRiskModuleOutput>()
                {
                    {
                        "new_risk_module",
                        new TransactionRiskModuleOutput()
                        {
                            AgentModuleOutput = new ModuleOutput()
                            {
                                Risk = RiskLevel.High,
                                Message = "Some message to the user to notify the risk level",
                                OnTap = new Map(
                                    new Coordinates(){
                                        Lat = 41.15F,
                                        Lon = -8.61024F,
                                        Accuracy = 20 // accuracy in km
                                    },
                                    "Origin Location",
                                    new Pinpoint(){
                                        Country = "Portugal",
                                        City = "Porto"
                                    }
                                ).CreateMapOutput()
                            }
                        }
                    }
                }
            },
            RiskModulesToCalculate = new TransactionRiskModulesToUse()
            {
                ModulesToUse = new Dictionary<RiskModule, TransactionRiskModuleToUse>()
                {
                    {
                        RiskModule.IPReputation,
                        new TransactionRiskModuleToUse(){
                            Mandatory = true
                        }
                    },
                    {
                        RiskModule.LRC,
                        new TransactionRiskModuleToUse(){
                            Mandatory = true
                        }
                    }
                }
            },
            TypeData = new SIBS3DSTransactionTypeData()
            {
                Amount = 100,
                Currency = "EUR",
                MBWaySDKRegistrationData = new MBWaySDKRegistrationData
                {
                    // data to be filled with The MBWay SDK
                },
                ServiceOperationPlayerCode = ""
            }
        };
    }
}

SIBS 3DS V2 Transaction

Attribute	Description	Optional
`Message`	Transaction message to be shown to the user	No
`ActionName`	The action name for this transaction that the user will see in his Agent.	No
`TransactionDuration`	The duration of the transaction limited between 30 seconds and 150 seconds.	No
`Core`	Please check `Core` in the Models chapter for further information	No
`TypeData`	Information needed for the SIBS transaction. In this version of the SIBS transaction you need to input the SIBS details to the transaction. As the SIBS details stay with the TrustFactor transaction you can consult those details anytime with any agent you have registered in your contract, since it is not dependent of SIBS anymore.	No
`RequiredAuthentications`	Authentications required to approve the transaction. The possible values come from `Authentication Mechanism` enum.	Yes
`Risk`	Sets the transaction risk. The values that are possible are in the `Risk Level` enum. When filled the transaction will assume the defined risk, and the params risk should be filled as well if applicable.	Yes
`RiskModules`	Additional parameters for the risk modules calculation. For example the origin coordinates of the transaction to be used by `lrc` risk module.	Yes
`RiskModulesAdded`	Additional risk modules that are shown to the user. New risk modules can be added to the output shown to the user	Yes
`RiskModulesToCalculate`	Risk modules to calculate and specify if they are mandatory, because there is not an operation to decide which risk modules to calculate	Yes

using System.Collections.Generic;
using TrustFactorSDK.V2.Constants;
using TrustFactorSDK.V2.Models.TransactionCreation.V3;
using TrustFactorSDK.V2.Models.TransactionCreation.V3.Auxiliary;
using TrustFactorSDK.V2.Models.TransactionCreation.V3.Auxiliary.RiskModules;
using TrustFactorSDK.V2.Models.TransactionCreation.V3.Auxiliary.RiskModules.input;
using TrustFactorSDK.V2.Models.TransactionCreation.V3.Auxiliary.RiskModules.output;
using TrustFactorSDK.V2.Models.TransactionCreation.V3.Auxiliary.RiskModules
    .output.Agent;
using TrustFactorSDK.V2.Models.TransactionCreation.V3.Auxiliary.RiskModules
    .output.Agent.EventData;
using Coordinates = TrustFactorSDK.V2.Models.TransactionCreation.V3.Auxiliary
    .RiskModules.output.Agent.EventData.Coordinates;

class TestTransactions
{
    static void Main(string[] args)
    {
        SIBS3DSV2Transaction sibs3DSV2Transaction = new SIBS3DSV2Transaction()
        {
            Message = "Test",
            ActionName = "Action",
            TransactionDuration = 30,
            Core = new Core
            {
                MetaData = new Metadata
                {
                    Timestamp = 1619705292,
                    UserAgent = "TrustFactor CSharp SDK",
                    Platform = "",
                    Channel = "Mobile",
                    SourceIP = "1.2.3.4"
                }
            },
            RequiredAuthentications = new List<AuthenticationMechanism>
            {
                AuthenticationMechanism.AuthenticationBiometrics,
                AuthenticationMechanism.AuthenticationPassword
            },
            Risk = RiskLevel.Low,
            RiskModules = new TransactionAgentInput()
            {
                Input = new Dictionary<RiskModule, IRiskModuleInput>()
                {
                    {
                        RiskModule.LRC,
                        new RiskModuleInputLRC(){
                            Lat = 41.15F,
                            Lon = -8.61024F,
                            Accuracy = 20 // accuracy in km
                        }
                    },
                    {
                        RiskModule.IPReputation,
                        new RiskModuleInputIPRep(){}
                    }
                }
            },
            RiskModulesAdded = new TransactionAgentOutput()
            {
                Output = new Dictionary<string, TransactionRiskModuleOutput>()
                {
                    {
                        "new_risk_module",
                        new TransactionRiskModuleOutput()
                        {
                            AgentModuleOutput = new ModuleOutput()
                            {
                                Risk = RiskLevel.High,
                                Message = "Some message to the user to notify the risk level",
                                OnTap = new Map(
                                    new Coordinates(){
                                        Lat = 41.15F,
                                        Lon = -8.61024F,
                                        Accuracy = 20 // accuracy in km
                                    },
                                    "Origin Location",
                                    new Pinpoint(){
                                        Country = "Portugal",
                                        City = "Porto"
                                    }
                                ).CreateMapOutput()
                            }
                        }
                    }
                }
            },
            RiskModulesToCalculate = new TransactionRiskModulesToUse()
            {
                ModulesToUse = new Dictionary<RiskModule, TransactionRiskModuleToUse>()
                {
                    {
                        RiskModule.IPReputation,
                        new TransactionRiskModuleToUse(){
                            Mandatory = true
                        }
                    },
                    {
                        RiskModule.LRC,
                        new TransactionRiskModuleToUse(){
                            Mandatory = true
                        }
                    }
                }
            },
            TypeData = new SIBS3DSV2TransactionTypeData()
            {
                Amount = 100,
                Currency = "EUR",
                Description = "",
                MerchantName = "",
                MerchantLocation = "",
                MaskedPAN = "",
                ServiceOperationPlayerCode = "",
                MBWaySDKRegistrationData = new MBWaySDKRegistrationDataV2
                {
                    // data to be filled with The MBWay SDK
                }
            }
        };
    }
}

Transactions in depth

Normal Transaction​

Actionable Transaction​

Generic Transaction​

SIBS 3DS Transaction​

SIBS 3DS V2 Transaction​

Normal Transaction

Actionable Transaction

Generic Transaction

SIBS 3DS Transaction

SIBS 3DS V2 Transaction