Get Payment Rules

This endpoint allows developers to retrieve the specific payment data validation requirements for foreign exchange (FX) payments based on a given currency and country code.

This helps ensure that when you submit the payment instructions, they conform to the rules for that currency and country pair. You can pass the currency and country codes in ISO format in the request URL, and the API returns detailed validation requirements for that combination.

Request

Endpoint: /api/v{version}/paymentvalidationrules?buyCurrency={CurrencyCode}&countryCode={CountryCode}

Method: GET

The API requires you to pass the currency and country codes in the request URL.

URL Parameter	Type	Required	Description
`buyCurrency`	string	Yes	The currency code in ISO 4217 format (e.g., AED, USD).
`countryCode`	string	Yes	The country code in ISO 3166-1 alpha-2 format (e.g., AE for UAE, US for USA).

Response

The validation rules are returned as objects so if a currency has multiple validation rules, then the response will contain an array of objects where each object denotes validations for one Instruct API field.

Within each response object, you can find the name of the relevant Instruct API request in the mappings field.

The rules array within each object contains the details of the validation rules. Each Instruct API field can have multiple rules applied to it.

Example 1

In the below example, for Country = AE and Currency = AED, the CreditorAgent.RoutingCode field has multiple rules that need to met for the payment instruction to be successful

Rule 1: Mandatory - The routing code field is mandatory
Rule 2: Fix Length - The routing code needs to be between 8-11 characters
Rule 3: Allowed Character Set - The routing code can only contains values from the allowed character set
Rule 4: Format BIC - The routing code must have the standard Swift BIC format

{
        "mappings": [
            "CreditorAgent.RoutingCode"
        ],
        "autoCompletes": [
            {
                "fieldId": "InstitutionName",
                "fieldIdReference": "BeneficiaryBankName"
            },
            {
                "fieldId": "OpCity",
                "fieldIdReference": "BeneficiaryBankAddressCity"
            },
            {
                "fieldId": "OpStreetAddress1",
                "fieldIdReference": "BeneficiaryBankAddressStreet"
            }
        ],
        "currencyCode": "AED",
        "countryCode": "AE",
        "fieldIdentifier": "BankCode",
        "fieldName": "Bank Code",
        "fieldLabelIdentifier": "SwiftBICCode",
        "fieldLabel": "Swift BIC Code",
        "displayByDefault": true,
        "order": 3,
        "displaySection": "Beneficiary Details",
        "rules": [
            {
                "ruleName": "MANDATORY",
                "ruleValues": [],
                "priority": 1,
                "errors": [
                    {
                        "errorCode": "ERR001",
                        "unformattedMessage": "{Field Label} is mandatory."
                    }
                ]
            },
            {
                "ruleName": "FIX LENGTH",
                "ruleValues": [
                    "8",
                    "11"
                ],
                "priority": 4,
                "errors": [
                    {
                        "errorCode": "ERR015",
                        "unformattedMessage": "{Field Label} must be {value (comma sep)} characters."
                    }
                ]
            },
            {
                "ruleName": "ALLOWED CHARACTER SET",
                "ruleValues": [
                    "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789 "
                ],
                "priority": 3,
                "errors": [
                    {
                        "errorCode": "ERR020",
                        "unformattedMessage": "{Field Label} can only contain {value}"
                    }
                ]
            },
            {
                "ruleName": "FORMAT BIC",
                "ruleValues": [],
                "priority": 2,
                "errors": [
                    {
                        "errorCode": "ERR030",
                        "unformattedMessage": "{Field Label} must have a valid Swift BIC format"
                    }
                ]
            }
        ],
        "displayInPayments": null,
        "displayInBeneficiaryTemplate": null,
        "id": "",
        "createdDate": "0001-01-01T00:00:00",
        "modifiedDate": "0001-01-01T00:00:00",
        "createdBy": "",
        "modifiedBy": "",
        "optimisticVersion": 1
    },

Example 2

In the below example, for Country = TH and Currency = THB, the Creditor.Street field has multiple rules that need to met for the payment instruction to be successful.

Rule 1: Mandatory - The street field is mandatory
Rule 2: Max Length - The street field can contain up to 70 characters
Rule 3: Allowed Character Set - The street field can only contains values from the allowed character set

 "mappings": [
            "Creditor.Address.Street"
        ],
        "autoCompletes": [],
        "currencyCode": "THB",
        "countryCode": "TH",
        "fieldIdentifier": "BeneficiaryAddressStreet",
        "fieldName": "Beneficiary Address Street",
        "fieldLabelIdentifier": "BeneficiaryStreetAddress",
        "fieldLabel": "Beneficiary Street Address",
        "displayByDefault": true,
        "order": 11,
        "displaySection": "Additional Information",
        "rules": [
            {
                "ruleName": "MANDATORY",
                "ruleValues": [],
                "priority": 1,
                "errors": [
                    {
                        "errorCode": "ERR001",
                        "unformattedMessage": "{Field Label} is mandatory."
                    }
                ]
            },
            {
                "ruleName": "MAX LENGTH",
                "ruleValues": [
                    "70"
                ],
                "priority": 4,
                "errors": [
                    {
                        "errorCode": "ERR010",
                        "unformattedMessage": "{Field Label} cannot be greater than {value} characters."
                    }
                ]
            },
            {
                "ruleName": "ALLOWED CHARACTER SET",
                "ruleValues": [
                    "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789/\\-?:().,'+ "
                ],
                "priority": 3,
                "errors": [
                    {
                        "errorCode": "ERR020",
                        "unformattedMessage": "{Field Label} can only contain {value}"
                    }
                ]
            }
        ],
        "displayInPayments": null,
        "displayInBeneficiaryTemplate": null,
        "id": "",
        "createdDate": "0001-01-01T00:00:00",
        "modifiedDate": "0001-01-01T00:00:00",
        "createdBy": "",
        "modifiedBy": "",
        "optimisticVersion": 1
    },

List of All Validation Rules

Rule Name	Rule Definition
MANDATORY	Field Must be Provided
CONDITIONAL MANDATORY ON AMOUNT	Condition, Amount, CurrencyofAmount e.g (gt, 5000000, TWD) (lt,10000,USD) FIELD IS MANDATORY
CONDITIONAL MANDATORY ON Account NAME	Partial Match (Contains) Strings FIELD IS MANDATORY
FORMAT EMAIL	Valid email format
FORMAT BIC	Valid SWIFT BIC format
FORMAT IBAN	SWIFT Standard and same country code as the Country
PREFIX VALUE	Field should Begin with value provided
ALLOWED CHARACTER SET	Only characters within the list are allowed
RESTRICTED TO SET LIST OF VALUES	Only FULL Match strings in the array are allowed
PROHIBITED KEYWORD	Partial Match (Contains) Strings in this list are not allowed
MANDATORY KEYWORD	Partial Match (Contains) Strings must be provided
MIN LENGTH	Minimum length of field
MAX LENGTH	Maximum length of field
FIX LENGTH	Has to match exact length of at least 1 value in Array
ISO COUNTRY CODE	List of country using the ISO 2 check
FORMAT BANKCODE	Has to match the bank code format provided
REGEX VALIDATION	Has to match the regex expression provided