Rules API

Use the Rules API to retrieve the validation rules that apply to a payment destination, currency, and route type.

The response identifies the fields required for a transaction request, where to place them in the request payload, and how Vitesse validates them.

For a general introduction to rules and route types, see Rules.

Retrieve rules for a route

Retrieve the validation rules for a specific destination country, currency, and route type.

GET /api/rules/{country}/{currency}/{routeType}

Example request

GET /api/rules/CA/CAD/BankAccount

The API returns an array of rule fields.

Example response (truncated)

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

Read a rule field

Each item in the response describes one field in the transaction request.

Use the Path value

The Path value tells you where to place the field in the transaction request.

For example, this path:

request.Recipient.Account.PaymentPurpose

means that PaymentPurpose belongs in the Recipient.Account object:

{
  "Recipient": {
    "Account": {
      "PaymentPurpose": "Insurance claim settlement"
    }
  }
}

Do not include the request prefix in the JSON payload. It represents the HTTP request body.

Conditional rules

Some fields have an Options value of Conditional. This means you provide the field only when a specific validation condition applies.

Where a rule includes a ConditionCode, use the condition code description to determine the additional validation that applies.

Condition codes

Some validation requirements cannot be expressed using field length, data type, or requirement level alone. In these cases, the Rules API returns a ConditionCode.

The condition code identifies the additional validation that applies to the field or payment route.

X13 Brazil account number validations

Additional validations

Vitesse can configure additional validations for an account to apply more restrictive validation rules to transactions. For example, ExternalReference1 can contain a mandatory 10-digit code, or we can restrict a field to a predefined set of permitted values.

For more information, see Additional validations.