Transactions in depth
In this chapter we will go in depth about how to create transactions, starting from which types you can create, which transactions types requires an operation and which parameters the transaction requires or may have.For further information about risk modules and how to create them, please visit Risk Modules In Depth chapter.
For some transaction types, specifically NORMAL_TRANSACTION and ACTIONABLE_TRANSACTION, 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 |
import com.securityside.trustfactor.model.transaction.creation.v3.auxiliary.Metadata;
import com.securityside.trustfactor.model.transaction.creation.v3.Core;
import com.securityside.trustfactor.model.transaction.creation.v3.NormalTransaction;
import com.securityside.trustfactor.model.transaction.creation.v3.auxiliary.MessageEngine;
public class Main {
public static void main(String[] args) {
NormalTransaction normalTransaction = NormalTransaction.builder()
.action("transfer")
.core(Core.builder()
.metadata(Metadata.builder()
.timestamp(1619705292L)
.userAgent("TrustFactor Java SDK")
.channel("Mobile")
.sourceIp("1.2.3.4")
.build())
.build())
.messageEngine(MessageEngine.builder()
.message("This is a message to show to the user")
.build())
.build();
}
}
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 | Requires the Agent to send a precise (GPS) device location when deciding the transaction. | Yes |
requireConfirmationCode | Requires the user to select the correct confirmation code on the Agent to approve the transaction. The correct code and the presented options are returned in the transaction creation response (Confirmation Code), so the application can show the code to the user. | Yes |
confirmationCode | Confirmation code generation settings, used when requireConfirmationCode is enabled. Defines the number of options presented to the user and the number of digits of each code. When omitted, the default settings are used. | 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 |
import com.securityside.trustfactor.constants.enums.AuthenticationMechanism;
import com.securityside.trustfactor.constants.enums.RiskLevel;
import com.securityside.trustfactor.constants.enums.RiskModule;
import com.securityside.trustfactor.model.transaction.creation.v3.auxiliary.MessageEngine;
import com.securityside.trustfactor.model.transaction.creation.v3.auxiliary.Metadata;
import com.securityside.trustfactor.model.transaction.creation.v3.ActionableTransaction;
import com.securityside.trustfactor.model.transaction.creation.v3.ConfirmationCodeSettings;
import com.securityside.trustfactor.model.transaction.creation.v3.Core;
import com.securityside.trustfactor.model.transaction.creation.v3.auxiliary.Param;
import com.securityside.trustfactor.model.transaction.creation.v3.auxiliary
.riskmodules.input.IRiskModuleInput;
import com.securityside.trustfactor.model.transaction.creation.v3.auxiliary
.riskmodules.input.RiskModuleInputLRC;
import com.securityside.trustfactor.model.transaction.creation.v3.auxiliary
.riskmodules.input.TransactionAgentInput;
import java.util.Arrays;
import java.util.HashMap;
public class Main {
public static void main(String[] args) {
ActionableTransaction transaction = ActionableTransaction.builder()
.action("transfer")
.messageEngine(MessageEngine.builder()
.message("This is a message to show to the user")
.build())
.core(Core.builder()
.metadata(Metadata.builder()
.timestamp(1619705292L)
.userAgent("TrustFactor Java SDK")
.channel("Mobile")
.sourceIp("1.2.3.4")
.build())
.build())
.customHeaders(new HashMap<String, String>()
{{
put("X-Custom-Header", "Header value");
}})
.requiredAuthentications(Arrays.asList(
AuthenticationMechanism.AUTHENTICATION_BIOMETRICS,
AuthenticationMechanism.AUTHENTICATION_PASSWORD)
)
.requirePreciseLocation(true)
.RequireConfirmationCode(true)
.ConfirmationCode(ConfirmationCodeSettings.builder()
.options(3)
.digits(2)
.build())
.overrideRiskCalculation(true)
.risk(RiskLevel.LOW)
.params(new HashMap<String, Param>()
{{
put("source_account", Param.builder()
.value("leandro.pinto")
.build());
put("destination_account", Param.builder()
.value("hilario.coelho")
.build());
put("amount", Param.builder()
.value(100)
.aux(new HashMap<String, String>(){{
put("currency", "EUR");
}})
.build());
}})
.riskModules(TransactionAgentInput.builder()
.input(new HashMap<RiskModule, IRiskModuleInput>() {{
put(RiskModule.LRC, RiskModuleInputLRC.builder()
.lat(1)
.lon(2)
.accuracy(20)
.build());
}})
.build())
.build();
}
}
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 | Requires the Agent to send a precise (GPS) device location when deciding the transaction. | Yes |
requireConfirmationCode | Requires the user to select the correct confirmation code on the Agent to approve the transaction. The correct code and the presented options are returned in the transaction creation response (Confirmation Code), so the application can show the code to the user. | Yes |
confirmationCode | Confirmation code generation settings, used when requireConfirmationCode is enabled. Defines the number of options presented to the user and the number of digits of each code. When omitted, the default settings are used. | 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 |
import com.securityside.trustfactor.constants.enums.AuthenticationMechanism;
import com.securityside.trustfactor.constants.enums.RiskLevel;
import com.securityside.trustfactor.constants.enums.RiskModule;
import com.securityside.trustfactor.model.transaction.creation.v3.auxiliary.Metadata;
import com.securityside.trustfactor.model.transaction.creation.v3.ConfirmationCodeSettings;
import com.securityside.trustfactor.model.transaction.creation.v3.Core;
import com.securityside.trustfactor.model.transaction.creation.v3.GenericTransaction;
import com.securityside.trustfactor.model.transaction.creation.v3.auxiliary
.Param;
import com.securityside.trustfactor.model.transaction.creation.v3.auxiliary
.riskmodules.TransactionRiskModuleToUse;
import com.securityside.trustfactor.model.transaction.creation.v3.auxiliary
.riskmodules.TransactionRiskModulesToUse;
import com.securityside.trustfactor.model.transaction.creation.v3.auxiliary
.riskmodules.input.IRiskModuleInput;
import com.securityside.trustfactor.model.transaction.creation.v3.auxiliary
.riskmodules.input.RiskModuleInputLRC;
import com.securityside.trustfactor.model.transaction.creation.v3.auxiliary
.riskmodules.input.TransactionAgentInput;
import com.securityside.trustfactor.model.transaction.creation.v3.auxiliary
.riskmodules.output.TransactionAgentOutput;
import com.securityside.trustfactor.model.transaction.creation.v3.auxiliary
.riskmodules.output.TransactionRiskModuleOutput;
import com.securityside.trustfactor.model.transaction.creation.v3.auxiliary
.riskmodules.output.agent.ModuleOutput;
import com.securityside.trustfactor.model.transaction.creation.v3.auxiliary
.riskmodules.output.agent.eventdata.Coordinates;
import com.securityside.trustfactor.model.transaction.creation.v3.auxiliary
.riskmodules.output.agent.eventdata.Map;
import com.securityside.trustfactor.model.transaction.creation.v3.auxiliary
.riskmodules.output.agent.eventdata.Pinpoint;
import java.util.Arrays;
import java.util.HashMap;
public class Main {
public static void main(String[] args) {
GenericTransaction transaction = GenericTransaction.builder()
.message("Test")
.actionName("Action")
.action("test action")
.transactionDuration(30)
.core(Core.builder()
.metadata(Metadata.builder()
.timestamp(1619705292L)
.userAgent("TrustFactor Java SDK")
.channel("Mobile")
.sourceIp("1.2.3.4")
.build())
.build())
.customHeaders(new HashMap<String, String>() {{
put("X-Custom-Header", "Header value");
}})
.requiredAuthentications(Arrays.asList(
AuthenticationMechanism.AUTHENTICATION_BIOMETRICS,
AuthenticationMechanism.AUTHENTICATION_PASSWORD)
)
.requirePreciseLocation(true)
.RequireConfirmationCode(true)
.ConfirmationCode(ConfirmationCodeSettings.builder()
.options(3)
.digits(2)
.build())
.risk(RiskLevel.LOW)
.params(new HashMap<String, Param>() {{
put("source_account", Param.builder()
.value("leandro.pinto")
.build());
put("destination_account", Param.builder()
.value("hilario.coelho")
.build());
put("amount", Param.builder()
.value(100)
.aux(new HashMap<String, String>() {{
put("currency", "EUR");
}})
.build());
}})
.paramsOrder(new HashMap<String, Long>() {{
put("source_account", 0L);
put("destination_account", 1L);
put("amount", 2L);
}})
.riskModules(TransactionAgentInput.builder()
.input(new HashMap<RiskModule, IRiskModuleInput>() {{
put(RiskModule.LRC, RiskModuleInputLRC.builder()
.lat(1)
.lon(2)
.accuracy(20)
.build());
}})
.build())
.riskModulesAdded(TransactionAgentOutput.builder()
.output(new HashMap<String, TransactionRiskModuleOutput>() {{
put("new_risk_module", TransactionRiskModuleOutput.builder()
.agentModuleOutput(ModuleOutput.builder()
.risk(RiskLevel.HIGH)
.message("Some message to notify the risk level")
.onTap(Map.builder()
.title("Origin Location")
.coordinates(Coordinates.builder()
.lat(41.25F)
.lon(-8.5437F)
.accuracy(50F)
.build())
.pinpoint(Pinpoint.builder()
.country("Portugal")
.city("Porto")
.build())
.build().CreateMapOutput())
.build())
.build());
}})
.build())
.riskModulesToCalculate(TransactionRiskModulesToUse.builder()
.transactionRiskModulesToUse(
new HashMap<RiskModule, TransactionRiskModuleToUse>() {{
put(RiskModule.LRC, TransactionRiskModuleToUse.builder()
.mandatory(true)
.build());
put(RiskModule.IPREP, TransactionRiskModuleToUse.builder()
.mandatory(true)
.build());
}}
)
.build())
.build();
}
}
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 |
import com.securityside.trustfactor.constants.enums.AuthenticationMechanism;
import com.securityside.trustfactor.constants.enums.RiskLevel;
import com.securityside.trustfactor.constants.enums.RiskModule;
import com.securityside.trustfactor.model.transaction.creation.v3.auxiliary.*;
import com.securityside.trustfactor.model.transaction.creation.v3.Core;
import com.securityside.trustfactor.model.transaction.creation.v3.SIBS3DSTransaction;
import com.securityside.trustfactor.model.transaction.creation.v3.auxiliary
.riskmodules.TransactionRiskModuleToUse;
import com.securityside.trustfactor.model.transaction.creation.v3.auxiliary
.riskmodules.TransactionRiskModulesToUse;
import com.securityside.trustfactor.model.transaction.creation.v3.auxiliary
.riskmodules.input.IRiskModuleInput;
import com.securityside.trustfactor.model.transaction.creation.v3.auxiliary
.riskmodules.input.RiskModuleInputLRC;
import com.securityside.trustfactor.model.transaction.creation.v3.auxiliary
.riskmodules.input.TransactionAgentInput;
import com.securityside.trustfactor.model.transaction.creation.v3.auxiliary
.riskmodules.output.TransactionAgentOutput;
import com.securityside.trustfactor.model.transaction.creation.v3.auxiliary
.riskmodules.output.TransactionRiskModuleOutput;
import com.securityside.trustfactor.model.transaction.creation.v3.auxiliary
.riskmodules.output.agent.ModuleOutput;
import com.securityside.trustfactor.model.transaction.creation.v3.auxiliary
.riskmodules.output.agent.eventdata.Coordinates;
import com.securityside.trustfactor.model.transaction.creation.v3.auxiliary
.riskmodules.output.agent.eventdata.Map;
import com.securityside.trustfactor.model.transaction.creation.v3.auxiliary
.riskmodules.output.agent.eventdata.Pinpoint;
import java.util.Arrays;
import java.util.HashMap;
public class Main {
public static void main(String[] args) {
SIBS3DSTransaction transaction = SIBS3DSTransaction.builder()
.message("Test")
.actionName("Action")
.transactionDuration(30)
.core(Core.builder()
.metadata(Metadata.builder()
.timestamp(1619705292L)
.userAgent("TrustFactor Java SDK")
.channel("Mobile")
.sourceIp("1.2.3.4")
.build())
.build())
.requiredAuthentications(Arrays.asList(
AuthenticationMechanism.AUTHENTICATION_BIOMETRICS,
AuthenticationMechanism.AUTHENTICATION_PASSWORD)
)
.risk(RiskLevel.LOW)
.riskModules(TransactionAgentInput.builder()
.input(new HashMap<RiskModule, IRiskModuleInput>() {{
put(RiskModule.LRC, RiskModuleInputLRC.builder()
.lat(1)
.lon(2)
.accuracy(20)
.build());
}})
.build())
.riskModulesAdded(TransactionAgentOutput.builder()
.output(new HashMap<String, TransactionRiskModuleOutput>() {{
put("new_risk_module", TransactionRiskModuleOutput.builder()
.agentModuleOutput(ModuleOutput.builder()
.risk(RiskLevel.HIGH)
.message("Some message to notify the risk level")
.onTap(Map.builder()
.title("Origin Location")
.coordinates(Coordinates.builder()
.lat(41.25F)
.lon(-8.5437F)
.accuracy(50F)
.build())
.pinpoint(Pinpoint.builder()
.country("Portugal")
.city("Porto")
.build())
.build().CreateMapOutput())
.build())
.build());
}})
.build())
.riskModulesToCalculate(TransactionRiskModulesToUse.builder()
.transactionRiskModulesToUse(
new HashMap<RiskModule, TransactionRiskModuleToUse>() {{
put(RiskModule.LRC, TransactionRiskModuleToUse.builder()
.mandatory(true)
.build());
put(RiskModule.IPREP, TransactionRiskModuleToUse.builder()
.mandatory(true)
.build());
}}
)
.build())
.typeData(SIBS3DSTransactionTypeData.builder()
.amount(100)
.currency("EUR")
.mbWaySDKRegistrationData(MBWaySDKRegistrationData.builder().build())
.serviceOperationPlayerCode("")
.build())
.build();
}
}
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 |
import com.securityside.trustfactor.constants.enums.AuthenticationMechanism;
import com.securityside.trustfactor.constants.enums.RiskLevel;
import com.securityside.trustfactor.constants.enums.RiskModule;
import com.securityside.trustfactor.model.transaction.creation.v3.SIBS3DSTransactionV2;
import com.securityside.trustfactor.model.transaction.creation.v3.auxiliary.*;
import com.securityside.trustfactor.model.transaction.creation.v3.Core;
import com.securityside.trustfactor.model.transaction.creation.v3.auxiliary
.riskmodules.TransactionRiskModuleToUse;
import com.securityside.trustfactor.model.transaction.creation.v3.auxiliary
.riskmodules.TransactionRiskModulesToUse;
import com.securityside.trustfactor.model.transaction.creation.v3.auxiliary
.riskmodules.input.IRiskModuleInput;
import com.securityside.trustfactor.model.transaction.creation.v3.auxiliary
.riskmodules.input.RiskModuleInputLRC;
import com.securityside.trustfactor.model.transaction.creation.v3.auxiliary
.riskmodules.input.TransactionAgentInput;
import com.securityside.trustfactor.model.transaction.creation.v3.auxiliary
.riskmodules.output.TransactionAgentOutput;
import com.securityside.trustfactor.model.transaction.creation.v3.auxiliary
.riskmodules.output.TransactionRiskModuleOutput;
import com.securityside.trustfactor.model.transaction.creation.v3.auxiliary
.riskmodules.output.agent.ModuleOutput;
import com.securityside.trustfactor.model.transaction.creation.v3.auxiliary
.riskmodules.output.agent.eventdata.Coordinates;
import com.securityside.trustfactor.model.transaction.creation.v3.auxiliary
.riskmodules.output.agent.eventdata.Map;
import com.securityside.trustfactor.model.transaction.creation.v3.auxiliary
.riskmodules.output.agent.eventdata.Pinpoint;
import java.util.Arrays;
import java.util.HashMap;
public class Main {
public static void main(String[] args) {
SIBS3DSTransactionV2 transaction = SIBS3DSTransactionV2.builder()
.message("Test")
.actionName("Action")
.transactionDuration(30)
.core(Core.builder()
.metadata(Metadata.builder()
.timestamp(1619705292L)
.userAgent("TrustFactor Java SDK")
.channel("Mobile")
.sourceIp("1.2.3.4")
.build())
.build())
.requiredAuthentications(Arrays.asList(
AuthenticationMechanism.AUTHENTICATION_BIOMETRICS,
AuthenticationMechanism.AUTHENTICATION_PASSWORD)
)
.risk(RiskLevel.LOW)
.riskModules(TransactionAgentInput.builder()
.input(new HashMap<RiskModule, IRiskModuleInput>() {{
put(RiskModule.LRC, RiskModuleInputLRC.builder()
.lat(1)
.lon(2)
.accuracy(20)
.build());
}})
.build())
.riskModulesAdded(TransactionAgentOutput.builder()
.output(new HashMap<String, TransactionRiskModuleOutput>() {{
put("new_risk_module", TransactionRiskModuleOutput.builder()
.agentModuleOutput(ModuleOutput.builder()
.risk(RiskLevel.HIGH)
.message("Some message to notify the risk level")
.onTap(Map.builder()
.title("Origin Location")
.coordinates(Coordinates.builder()
.lat(41.25F)
.lon(-8.5437F)
.accuracy(50F)
.build())
.pinpoint(Pinpoint.builder()
.country("Portugal")
.city("Porto")
.build())
.build().CreateMapOutput())
.build())
.build());
}})
.build())
.riskModulesToCalculate(TransactionRiskModulesToUse.builder()
.transactionRiskModulesToUse(
new HashMap<RiskModule, TransactionRiskModuleToUse>() {{
put(RiskModule.LRC, TransactionRiskModuleToUse.builder()
.mandatory(true)
.build());
put(RiskModule.IPREP, TransactionRiskModuleToUse.builder()
.mandatory(true)
.build());
}}
)
.build())
.typeData(SIBS3DSV2TransactionTypeData.builder()
.amount(100)
.currency("EUR")
.merchantName("")
.merchantLocation("")
.maskedPan("")
.serviceOperationPlayerCode("")
.mbWaySDKRegistrationDataV2(MBWaySDKRegistrationDataV2.builder().build())
.build())
.build();
}
}