Rules API

Visit Rules for an introduction to rules and route types.

Including Route Type in API calls

You can specify the RouteType as part of the API call; if no route type is specified, the default is BankAccount.

Example of a payment to Sweden without specifying the RouteType:

{
    SendCurrency: "GBP",
    SendValue: 12.99,
    Recipient:
    {
        Name: "Blibo Baggins",
        Country: "SE",
        Currency: "SEK",
        RecipientReference: "Thanks for the gold",
        Account:
        {
            Swift: "USAUSA01",
            AccountNumber: "1234567812345678"
        }
    }
}

To choose BankGiro (which is a specific route to Sweden), you need to specify the RouteType in the API:

{
    SendCurrency: "GBP",
    SendValue: 12.99,
    Recipient:
    {
        Name: "Blibo Baggins",
        Country: "SE",
        Currency: "SEK",
        RecipientReference: "Thanks for the gold",
        Account:
        {
            BankGiro: "1234567"
        }
    },
    RouteType: "BankGiro"
}

Getting the Rules

You can call the Rules API and provide a country and a currency to retrieve the set of fields that are required when using that country/currency/route type.

If calling the API for CA/CAD you will receive data such as the following...

[
  {
    "Field": "SwiftCode",
    "FieldName": "Swift Code",
    "FieldType": "AlphaNumeric",
    "MaximumLength": 11,
    "MinimumLength": 8,
    "Options": "Optional",
    "Path": "request.Recipient.Account.Swift"
  },
  {
    "Field": "AccountNumber",
    "FieldName": "Account Number",
    "FieldType": "Numeric",
    "MaximumLength": 12,
    "MinimumLength": 5,
    "Options": "Mandatory",
    "Path": "request.Recipient.Account.AccountNumber"
  },
  ...
]

This provides details of each field, whether it is mandatory, optional or conditional, and also provides details of the field datatype, name and so on.

Some rules are Conditional - in that they cannot easily be expressed as just on/off options. One example is when sending payments to the UK, where you can address an account using either the AccountNumber and SortCode, or the IBAN and SWIFT. These are encoded in the API as Conditional, and the condition can be viewed in the merchant admin system.

The Path element defines what element of the API request you use to specify a value for the field, so in the above example the account number field is specified as part of the Recipient.Account data.

{
    ...
    Recipient:
    {
        ...
        Account:
        {
            ...
            AccountNumber: "1234567812345678"
        }
    }
}

The first part of the path is defined as request, this simply means the HTTP request itself and should not be included as part of the API call.

By adding the extra route type parameter to the API call, the API will respond with the fields that are required for the specific route type. If a route type is not available for a given country and currency combination then a 404 will be returned.

GET api/rules/SE/SEK/BankGiro

[
  {
    "Field": "BankGiro",
    "FieldName": "BankGiro",
    "FieldType": "Numeric",
    "MaximumLength": 9,
    "MinimumLength": 7,
    "Options": "Mandatory",
    "Path": "request.Recipient.Account.BankGiro"
  }
]

Field Types

The data returned from the Rules API is an array of fields that contain name, length and other details including the FieldType. This specifies the type of data that field supports, and is one of the following options...

• Alpha - A-Z and a-z only
• AlphaNumeric - Allows A-Z, a-z and 0-9 only
• Any - Permits all characters to be used
• DateTime - Data must be a date time
• Email - Parses the data as a valid email address
• ExtendedAlphaNumeric - Allows numbers, letters and spaces
• Numeric - Allows 0-9 only

When calling the API the fields are validated, and you will receive an error such as the following when the data for a given field does not match the field type...

{
  "Code": "ArgumentInvalid",
  "Message": "One or more arguments passed to the API call have an invalid value",
  "MoreInfo": "https://docs.vitessepsp.com/reference#section-argumentinvalid",
  "ModelState": {
    "request.Recipient.Account.AccountNumber": {
      "Errors": [
        {
          "ErrorMessage": "The AccountNumber can only contain Numeric characters, but was '1234567A'"
        }
      ]
    }
  }
}

Our error messages tend to be very specific so it should be completely evident what's wrong with the incoming data.

Additional Example

API response for a request to get system rules for country US, currency USD and Cheque route combination:

[
    {
        "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"
    }
]

In addition to standard system rules, we also have added Additional Validations to the system which can be setup on a per-account basis. This allows you to define more restrictive rules for transactions - you might require that all transactions have a mandatory 10 digit code in the ExternalReference1 field, or you might wish to specify that a value passed to the API is contained in a set of known values. Please see the section on Additional Validations.