Structured remittance

The structured remittance is the associated information of a payment is being made, in a structured format. It is used to provide a unique reference issued by the creditor.

🚧

Having both structured and unstructured remittance for the same payment is not allowed.

The structured remittance contains:

• Reference: unique reference, as assigned by the creditor, to unambiguously refer to the payment transaction
• Code: identifies the type of reference supplied
• Issuer: further identifies the type of reference supplied

Example:

If the Issuer field is populated with the value "ISO" and the Code field is populated with the value "SCOR" then the Reference must contain a correct ISO 11649 reference. Excerpt from a payment initiation request:

{
  "paymentInitiationRequest": {
    "remittanceInformationStructured": {
        "code": "SCOR",
        "issuer": "ISO",
        "reference": "RF8856SHF846SH37SHD73HFY5"
    }
  }
}

The values required for the structured remittance are defined in the payment options described in the Options section.

Options

In the payment options, for each payment type, you can find the related structured remittance options that are available for a payment, in the RemittanceInformationStructured property.

{
    "SepaCreditTransfers": {
        "PaymentInitiationRequestOptions": {
            "RemittanceInformationStructured": {
                "AllowedCodes": [
                ],
                "AllowedIssuers": [
                ],
                "Code": "int",
                "CodeConstraints": {
                    "AcceptedChars": "string",
                    "MaxLength": "int",
                    "MinLength": "int",
                    "Regex": "string"
                },
                "Issuer": "int",
                "IssuerConstraints": {
                    "AcceptedChars": "string",
                    "MaxLength": "int",
                    "MinLength": "int",
                    "Regex": "string"
                },
                "Reference": "int",
                "ReferenceConstraints": {
                    "AcceptedChars": "string",
                    "MaxLength": "int",
                    "MinLength": "int",
                    "Regex": "string"
                },
                "Supported": "bool"
            }
        }
    }
}

In the structured remittance options we have several properties:

Supported Values

This section lists the available values of the properties Code and Issuer.

🚧

We will enforce the reference by checking it and raise a validation error if the check don't succeed

Issuer

Code

Reference Calculation

The Reference property needs a specific format. This format is specified by the selected Issuer.
In this section we'll go through how to convert a base reference into the required format.

BBA

Structure: A numeric string with 12 digits. The last two digits serve as check digits.
Calculation:

• Start with a base reference number of 10 digits: 1111111111
• Calculate the modulo 97 of those 10 digits to get the check digits: 1111111111 mod 97 = 70
• Append the check digits to the base reference: 111111111170

ISO/INTL

Structure: The creditor reference is an alphanumeric string, 25 characters long, with the letters "RF" at the beginning. After the letters are two check digits, which confirm that the reference will be entered correctly. The remaining part of the creditor reference (up to 21 alphanumeric characters) is the reference. The content of the creditor reference can be determined without any restrictions.
Calculation:

• Start with a base reference number: 123456789012345678901
• To the base reference number, add "RF00" as a suffix: 123456789012345678901RF00
• Convert it to a numeric string with each letter being it's corresponding base36 value (A = 10, Z = 35): 123456789012345678901271500
• Calculate the modulo 97 of the previous number: 123456789012345678901271500 mod 97 = 58
• The final reference should be valid if it has a remainder of 1 when divided by 97, so we subtract the modulo 97 we calculated previously from 98 to account for this: 98 - 58 = 40
• Add RF and the calculated check digits as a prefix to the base reference number: RF40123456789012345678901

SEBG

Structure: Numeric string, between 2 and 25 characters long. The last two digits are control digits.
Calculation:

• Start with a base reference number: 1234567890
• Add 2 to the length of the base reference to account for the final length with both control digits: 10 + 2 = 12
• Calculate the modulo 10 of this new length, which will serve as our length control digit: 12 mod 10 = 2
• Append the length control digit to the base reference: 12345678902
• From the base reference number, we calculate a weighted sum of all digits. All digits of the reference (with the added length control digit) are multiplied from right to left with alternating values 2 and 1 (2, 1, 2, 1...) and added to the sum. If the product of multiplying a digit by it's weight is greater than 9, we subtract 9 from the product before adding it to the sum: (2 x 2) + 0 + ((9 x 2) - 9) + 8 + ((7 x 2) - 9) + 6 + ((5 x 2) - 9) + 4 + (3 x 2) + 2 + (1 x 2) = 47
• Calculate the modulo 10 of the weighted sum: 47 mod 10 = 7
• Subtract the previous value from 10. This is the sum control digit: 10 - 7 = 3
• Append both the length control and sum control digits to the base reference: 123456789023

NORF

Structure: Numeric string, between 4 and 25 characters long. The last digit is the control digit. The other digits are the Customer Id (required), Payment Type (optional) and Invoice Id (required). The Customer Id is a unique ID for a payer and should be consistent in all payments related to a specific customer or subscription. The Payment Type is used to differentiate between different products or services paid for by a single customer. The Invoice Id is unique for each invoice or payment and is used to distinguish each invoice in a payer/payee relationship.
Calculation:

• Start with a base reference number: 12345670112345
• From the base reference number, we calculate a weighted sum of all digits. Starting from the rightmost digit, each digit is multiplied by it's weight, alternating between 2 and 1. The resulting products are added to the weighted sum. If the product of multiplying a digit by it's weight has 2 digits we don't add the value to the weighted sum. Instead, we add the sum of the product's digits:
  (5 x 2) + 4 + (3 x 2) + 2 + (1 x 2) + 1 + (0 x 2) + 7 + (6 x 2) + 5 + (4 x 2) + 3 + (2 x 2) + 1 =
  = (1 + 0) + 4 + 6 + 2 + 2 + 1 + 0 + 7 + (1 + 2) + 5 + 8 + 3 + 4 + 1 = 47
• We subtract the last digit from the weighted sum from 10 to get the control digit (if the last digit is 0 the control digit will be 0): 10 - 7 = 3
• Append this control digit to the base reference: 123456701123453

FIRF

Structure: Numeric string, between 4 and 20 characters long. The last digit is the control digit.
Calculation:

• Start with a base reference number: 1234567890
• From the base reference number, we calculate a weighted sum of all digits. Starting from the rightmost digit, each digit is multiplied by it's weight, alternating between 7, 3 and 1. The resulting products are added to the weighted sum: (0 x 7) + (9 x 3) + 8 + (7 x 7) + (6 x 3) + 5 + (4 x 7) + (3 x 3) + 2 + (1 x 7) = 153
• This weighted sum is them subtracted from the next multiple of 10. This new value is the control digit (it will be 0 is the difference is 10): 160 - 153 = 7
• Append this control digit to the base reference: 12345678907