How to use Payment Rules

The payments rules endpoint allows you check the payment requirements for any currency and country combination.

Users should look at the payment rules to identify which fields in the Instruct endpoint are required for payments to certain currencies and what type of values are allowed in those fields.

Mandatory Fields

The Payment Rules endpoint returns objects with mappings and rules. This mean all the fields specified under mappings are mandatory for the currency

"mappings": [
            "CreditorAccountName",
            "Creditor.Name"
        ],

            {
                "ruleName": "MANDATORY",
                "ruleValues": [],
                "priority": 1,
                "errors": [
                    {
                        "errorCode": "ERR001",
                        "unformattedMessage": "{Field Label} is mandatory."
                    }
                ]
            },

Bank Name lookup

The Payment Rules will also return a list of Bank related fields under the variable autoCompletes. These are the values that are auto-populated by StoneX when you provide CreditorAgent.RoutingCode

In the below example, the following fields are auto-populated using our bank data lookup so you don't need to provide them in the Instruction.

Bank Name
Bank City
Bank Street

        "mappings": [
            "CreditorAgent.RoutingCode"
        ],
        "autoCompletes": [
            {
                "fieldId": "InstitutionName",
                "fieldIdReference": "BeneficiaryBankName"
            },
            {
                "fieldId": "OpCity",
                "fieldIdReference": "BeneficiaryBankAddressCity"
            },
            {
                "fieldId": "OpStreetAddress1",
                "fieldIdReference": "BeneficiaryBankAddressStreet"
            }
        ],

Payment Codes

For certain currencies, Purpose of Payment Code (PurposeOfPayment.StructuredInfo) is mandatory and the value must be one of the values that are allowed for that currency/country. The Payment Rules endpoint will also return the list of value that are allowed. Please provide one of the values from this list.

{
                "ruleName": "RESTRICTED TO SET LIST OF VALUES",
                "ruleValues": [
                    "/CCTFDR/",
                    "/COCADR/",
                    "/CCDNDR/",
                    "/CGODDR/",
                    "/CSTRDR/"
                ],
                "priority": 3,
                "errors": [
                    {
                        "errorCode": "ERR050",
                        "unformattedMessage": "{value} is invalid for {Field Label}"
                    }
                ]
            }

Rule Priority

Some fields have multiple rules applied to them. For example - CreditorAgent.RoutingCode can have different rules applied to it such as Mandatory, Fix Length & Allowed Character Set and Format BIC.

Each rule is applied on the basis on priority assigned to the rule.

In this example, the Mandatory rule is applied first. If it fails (field is empty), you will get an error saying this field is mandatory.

If the field passes the Mandatory rule, then the Format BIC rule is applied.

If the value provided is a valid BIC, then the Allowed Character Set rule is applied and so on.

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