Additional validations

In addition to the System Rules defined for country / currency / route type combinations, we have introduced the concept of Additional Validations (also known as Rulesets). This allows customers to define custom rules, both for system fields or extra data fields dynamically passed within a transaction request. Currently, rulesets can only be assigned at Account level. When a ruleset is assigned to an account, the rules within will apply to any transaction made from this account.

Additional Validations work in a very similar way to system rules when it comes to the underlying data model. However, they allow for a higher degree of flexibility as additional conditions can be assigned.

Each rule field is defined by FieldName and APIPath.

As a result, a field within a ruleset could have the following conditions:

FieldType (i.e., alphanumeric, numeric)
Minimum length
Maximum length
Option (i.e., optional, mandatory)
Allowlist – entered data needs to match an entry of a list of eligible data
Denylist – prevents entry of specific data, I.e., banned words
BlendLookup – can be set to enable matching of entered data against account metadata

A ruleset always consists of a minimum of one rule field.

Where a ruleset defines a field that is also included within the system rules, validation of this field will consider both the system rules as well as the additional validations, and apply the most restrictive rule (i.e., system rules might allow 1-15 characters for External Reference 1, but the additional ruleset only supports 1-10 characters. Taken together, the allowed field length will be 1-10 characters).

Rulesets can be retrieved together with system rules via a single API call by adding an ‘accountId’ query parameter. So, for example if there is a ruleset assigned on an account with the ID 700, the query to the API would be as follows: GET api/rules/US/USD/Cheque?accountId=700

[
    {
        "Conditions": [],
        "Field": "RecipientReference",
        "FieldName": "Recipient Reference",
        "FieldType": "Any",
        "MaximumLength": 50,
        "MinimumLength": 0,
        "Options": "Mandatory",
        "Path": "request.Recipient.RecipientReference"
    },
    {
        "Conditions": [],
        "Field": "BeneficiaryName",
        "FieldName": "Beneficiary Name",
        "FieldType": "Any",
        "MaximumLength": 250,
        "MinimumLength": 0,
        "Options": "Mandatory",
        "Path": "request.Recipient.Name"
    },
    {
        "Conditions": [],
        "Field": "BeneficiaryEmailAddress",
        "FieldName": "Beneficiary Email Address",
        "FieldType": "Email",
        "MaximumLength": 128,
        "MinimumLength": 0,
        "Options": "Mandatory",
        "Path": "request.Recipient.Email"
    },
    {
        "Conditions": [
            {
                "ConditionType": "Denylist",
                "Parameters": {
                    "DenylistId": 10008,
                    "ExactMatch": true
                }
            }
        ],
        "FieldName": "External Reference 2",
        "FieldType": "Any",
        "MaximumLength": 128,
        "MinimumLength": 4,
        "Options": "Mandatory",
        "Path": "request.ExternalReference2"
    },
    {
        "Conditions": [
            {
                "ConditionType": "BlendLookup",
                "Parameters": {
                    "PropertyName": "YOA"
                }
            }
        ],
        "FieldName": "Year Of Account",
        "FieldType": "Numeric",
        "MaximumLength": 4,
        "MinimumLength": 4,
        "Options": "Mandatory",
        "Path": "request.Extra.YearOfAccount"
    },
    {
        "Conditions": [
            {
                "ConditionType": "BlendLookup",
                "Parameters": {
                    "PropertyName": "UMR"
                }
            }
        ],
        "FieldName": "Unique Market Reference",
        "FieldType": "AlphaNumeric",
        "MaximumLength": 128,
        "MinimumLength": 8,
        "Options": "Mandatory",
        "Path": "request.Extra.UniqueMarketReference"
    },
    {
        "Conditions": [
            {
                "ConditionType": "BlendLookup",
                "Parameters": {
                    "PropertyName": "SectionId"
                }
            }
        ],
        "FieldName": "Section ID",
        "FieldType": "Any",
        "MaximumLength": 64,
        "MinimumLength": 64,
        "Options": "Mandatory",
        "Path": "request.Extra.SectionID"
    },
    {
        "Conditions": [
            {
                "ConditionType": "Allowlist",
                "Parameters": {
                    "Choices": [
                        "Indemnity",
                        "DCA Fees",
                        "Considered Fees (Total Fees excluding DCA Fees)"
                    ],
                    "Descriptions": [
                        null,
                        null,
                        null
                    ],
                    "PermitFreeformEntry": false
                }
            }
        ],
        "FieldName": "Fee Indicator",
        "FieldType": "Any",
        "MaximumLength": 64,
        "MinimumLength": 0,
        "Options": "Optional",
        "Path": "request.Extra.FeeIndicator"
    }
]

In this example, the combined rules contain a mix of System rules and Additional Validations. Here, the system rules are derived from country / currency / route combinations (example fields: RecipientReference, BeneficiaryName, BeneficiaryEmailAddress - compare with example from Rules.

Additional Validations in this example are defined for one system field (External Reference 2) and four additional fields, that are passed in the Extra object (Unique Market Reference, Year Of Account, Section Id, Fee indicator). The Extra fields can be identified by the ApiPath starting from 'request.Extra.*'.

The additional conditions can be found in the Conditions collections.

Allowlist condition - defined for Fee Indicator, defines only three possible values for the field (Indemnity, DCA Fees and Considered Fees (Total Fees excluding DCA Fees)). Any other values will be rejected during validation of that field
Denylist condition - defined for External Reference 2, defines the banned words list. If any of these words are used as a value of the field, it will not pass a validation. Since that list may contain sensitive data, it is defined as a system lookup and just the list ID is returned.
Blend lookup condition - defined for Year of Account, Unique Market Reference and SectionId, enforces that the provided value matches that defined in Account Blend metadata.