Main data file

Version 1.0Version 2.0

This page outlines the specifications for the primary data file to be sent to SurePay via SFTP. Follow these guidelines to ensure your file is correctly formatted and processed efficiently.

File Purpose

To transmit account data securely. The file ensures that the account data shared with SurePay is accurate, consistent, and complete. By following the specified format and structure, organizations can minimize errors and discrepancies in the data transmission process.

File Naming

Name convention: accounts_bank.pgp

  • Replace 'bank' with your institution's name.
  • For example, accounts_ABCBank.pgp.

File Structure

  • Each file consists of multiple records (lines).
  • Each record should be an individual XML line.
  • Upload the file to the root folder.

The dummy file below contains an example of how the file should be structure:

Fields and formatting

Within the following fields, you will encounter shared attributes applicable to both Natural Persons and Organisations. However, each of these entities also possesses distinct attributes, which can be located within the "Persons" and "Organisations" objects respectively. It's important to mention that a file can contain multiple records from both Natural persons and Organisations.

  • Name
    account
    Type
    object
    Tag(s)
    Mandatory
    Description

    Object containing the accounts’ information.

    • Name
      iban
      Type
      string
      Tag(s)
      Mandatory
      Description

      Full IBAN bank account. No spaces are allowed. Mod97 compliant.

      • Format: [A-Z]{2}[0-9]{2}[a-zA-Z0-9]{30} [18-34] characters
      • Example: NL88SRPY9056000789
    • Name
      status
      Type
      Enum
      Tag(s)
      Mandatory
      Description

      The status of the account.

      • ACTIVE: account is a valid account and supported for checks.
      • INACTIVE: account is a valid account marked as inactive by the account holding bank, by a third party or by SurePay if SurePay has reason to believe that the account should be marked as inactive.
    • Name
      startDate
      Type
      Date
      Tag(s)
      Mandatory
      Description

      The date when the account was opened and registered by the bank. Reflects the real start date of the account.

      • Format: 'YYYY-MM-DD'
    • Name
      ascription
      Type
      String
      Tag(s)
      Mandatory
      Description

      The name under which the account is registered at the bank. In case the name of the account holder is longer than the permitted characters, this has to be shortened until it reaches the max. number of allowed characters.

      • Format: [2-70] characters
    • Name
      bgcName
      Type
      String
      Tag(s)
      Description

      The account name which is used for non-cash payments exchanged through the Dutch clearing system (BGC or Equens).

      • Format: [2-24] characters
    • Name
      bankAccountType
      Type
      Enum
      Tag(s)
      Mandatory
      Description

      The type of bank account. The possible values are:

      • PAYMENTS - A payments account, also known as a checking account.
      • SAVINGS - A savings account.
      • MORTGAGE - A mortgage account.
      • TRUST - Also known as derdengeldenrekening or Escrow account. Used by notary offices, lawyers and bailiffs.
      • COLLECTION - Also known as beheer rekening. typically owned by a collection agency or a debt buyer. But can also be used by Collecting Payment Service Providers.
      • INVESTMENT - An account used for investing (Also known as brokerage account or beleggingsrekening).
      • OTHER - Other products.
      • UNKNOWN - Unknown account type.
  • Name
    accountHolder
    Type
    Object
    Tag(s)
    Mandatory
    Description

    The root element for ‘person’/’organisation’ (only one of these two types could be included within it).

  • Name
    person
    Type
    Object
    Tag(s)
    Description
  • Name
    organisation
    Type
    Object
    Tag(s)
    Description

XML Line (Record)

Natural Person
   <account iban="NL88SRPY9056000789" startDate="2022-10-30" ascription="JOHN MARK PETERSON" status="active" bankAccountType="PAYMENTS"><accountHolder><person fullGivenName="JOHN MARK" initials="J.M." correspondence="J.M. MIREY" birthName="MIREY"/></accountHolder></account>

XML Line (Record)

Multiple Natural Persons
   
<account iban="NL57SRPYB0906840880" startDate="1997-05-08" ascription="VOORN MATHIAS RODRIGUEZ en M.A. SMITH-RODRIGUEZ" status="active" bankAccountType="MORTGAGE"><accountHolder><person fullGivenName="VOORN MATHIAS" initials="V.M." surnameCombined="VOORN" correspondence="V.M. RODRIGUEZ" birthName="RODRIGUEZ"/><person fullGivenName="MARIE ALEXANDRA" initials="M.A." surnameCombined="SMITH-RODRIGUEZ" correspondence="M.A. SMITH" birthName="SMITH"/></accountHolder></account>

XML Line (Record)

Organisation
<account iban="NL91SRPY9000000555" startDate="2018-05-12" ascription="AlCAMO BIKE SERVICES" status="active" bankAccountType="SAVINGS"><accountHolder><organisation legalName="AlCAMO BIKE SERVICES" kvkNumber="59581853" kvkBranchNumber="000015063097" residentialPostalCode="1012DH" residentialCountry="NL" legalStructure="LTD" commercialNameShort="ALCAMO BIKES"/></accountHolder></account>

Common Errors and Troubleshooting

To ensure a smooth onboarding process, we've compiled a list of common errors you might encounter when working with the XML file and their respective solutions. If you experience any issues, please refer to the information below.

1. File Naming Error

  • Issue: Incorrect file naming convention.
  • Solution: Ensure the file is named accounts_bank.pgp, replacing bank with the respective bank name.

2. File Format Error

  • Issue: Incorrect end-of-line characters.
  • Solution: Use Unix end-of-line characters for each record.

XML Line (Record)

File Unix end-of-line structure
   <account iban="NL88SRPY9056000789" startDate="2022-10-30" ascription="JOHN MARK PETERSON" status="active" bankAccountType="PAYMENTS"><accountHolder><person fullGivenName="JOHN MARK" initials="J.M." correspondence="J.M. MIREY" birthName="MIREY"/></accountHolder></account>
   <account iban="NL57SRPYB0906840880" startDate="1997-05-08" ascription="VOORN MATHIAS RODRIGUEZ en M.A. SMITH-RODRIGUEZ" status="active" bankAccountType="MORTGAGE"><accountHolder><person fullGivenName="VOORN MATHIAS" initials="V.M." surnameCombined="VOORN" correspondence="V.M. RODRIGUEZ" birthName="RODRIGUEZ"/><person fullGivenName="MARIE ALEXANDRA" initials="M.A." surnameCombined="SMITH-RODRIGUEZ" correspondence="M.A. SMITH" birthName="SMITH"/></accountHolder></account>
   <account iban="NL91SRPY9000000555" startDate="2018-05-12" ascription="AlCAMO BIKE SERVICES" status="active" bankAccountType="SAVINGS"><accountHolder><organisation legalName="AlCAMO BIKE SERVICES" kvkNumber="59581853" kvkBranchNumber="000015063097" residentialPostalCode="1012DH" residentialCountry="NL" legalStructure="LTD" commercialNameShort="ALCAMO BIKES"/></accountHolder></account>

3. IBAN Format Error

  • Issue: Incorrect IBAN format.
  • Solution: Ensure the IBAN is Mod97 compliant and follows the format: [A-Z]{2}[0-9]{2}[a-zA-Z0-9]{30} [18-34] characters
    • Example: NL88SRPY9056000789.

4. Date Format Error

  • Issue: Incorrect date format for 'startDate'.
  • Solution: Use the format 'YYYY-MM-DD'.
  • Example: '2003-03-12'.

5. Mandatory Field Error

  • Issue: Missing mandatory fields.
  • Solution: Ensure all mandatory fields like 'iban', 'status', 'startDate', 'ascription', and 'bankAccountType' are filled correctly.
    • For the 'persons' object: Ensure the mandatory fields like 'birthName' is filled correctly.
    • For the 'organisations' object: Ensure the mandatory fields like 'kvkNumber', 'legalName' and 'residentialPostalCode' are filled correctly.

6. Account Status Error

  • Issue: Invalid account status.
  • Solution: Use either 'ACTIVE' or 'INACTIVE' for the status field.

7. Character Limit Error

  • Issue: Exceeding character limits.
  • Solution: Adhere to the specified character limits for each field.
  • Example: ascription should be 2-70 characters.

8. Invalid Enum Value Error

  • Issue: Invalid enumeration value added to an enum field.
  • Solution: Adhere to the specified values for each field enumeration field.
  • Example: For the field 'bankAccountType', the expected values are PAYMENTS, SAVINGS, MORTGAGE, TRUST, COLLECTION, INVESTMENT, OTHER, UNKNOWN.