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.

  • accountobjectMandatory

    Object containing the accounts' information.

    • ibanstringMandatory

      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
    • statusEnumMandatory

      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.
    • startDateDateMandatory

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

      • Format: 'YYYY-MM-DD'
    • ascriptionStringMandatory

      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
    • bgcNameString

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

      • Format: [2-24] characters
    • bankAccountTypeEnumMandatory

      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.
  • accountHolderObjectMandatory

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

  • personObject

    Object containing information from a natural person's account. For multiple account holders, a "person" object has to be added by each account holder. Check example "Multiple Natural Persons" in the code snippet.

    • fullGivenNameString

      All first names as registered in the Passport. Separate with spaces. Last names/surname cannot be added in this field.

      • Example: "Susanne", "Ramon Mark"
      • Format: [2-70] characters.
    • initialsString

      Abbreviation of all first names. Needs to be separated with periods in between.

      • Example: "P.J.", "A."
      • Format: [1-50] characters.
    • birthNamePrefixString

      Prepositions and/or articles preceding the birth name (surname). Only if applicable.

      • Example: "Van", "Ter", "De".
      • Format: [1-25] characters.
    • birthNameStringMandatory

      The birth name or surname, as formally registered at the BRP (Basisregistratie Personen) or Identification Document, stripped of all prefixes.

      • Example: "Smith Roy", "Doe".
      • Format: [1-100] characters.
    • partnerNamePrefixString

      Prepositions and/or articles preceding the partner name.

      • Example: "van der", "ter", "de".
      • Format: [1-25] characters.
    • partnerNameString

      The surname of the person's official partner. This field is only filled if a person uses the surname of his/her partner after marriage.

      • Example: "Goossens-Janssen", "Smith-Doe".
      • Format: [1-100] characters.
    • surnameShortString

      A shortened version of the surname.

      • Example: "Hdez" for "Hernandez", "Rguez" for "Rodriguez".
      • Format: [1-100] characters.
    • surnameCombinedString

      This field can contain a combination of birth and partner name of the account holder, separated by " - ". Also, it excludes any prefixes of the first surname mentioned. The surnames added in this field have to be validated in the passport of the account holder.

      • Example: "Jong", "Hoekstra - Geurts".
      • Format: [1-100] characters.
    • surnamePrefixString

      Prepositions and/or articles preceding the surname. Only if applicable.

      • Example: "van der" "der" .
      • Format: [1-25] characters.
    • surnameSuffixString

      Prepositions and/or articles positioned after the surname. Only if applicable.

      • Example: "Jr.".
      • Format: [1-25] characters.
    • givenNameString

      The nickname or commonly used first name of a natural person. This name does not necessarily have to be registered in the passport.

      • Example: "Flo" for "Florence", "Liz" or "Elizabeth", "Andy" for "Andrew".
      • Format: [1-35] characters.
    • unvalidatedPartnerNamePrefixString

      Prepositions and/or articles preceding the 'unvalidatedPartnerName'. Only if applicable. Only if applicable.

      • Example: "Van der".
      • Format: [1-100] characters.
    • unvalidatedPartnerNameString

      The surname of the account holder's official partner. This field should be filled only if the account holder uses the surname of his/her partner after marriage. Only if applicable.

      • Example: "Bakker" is the birth name but the account holder uses "Jassen" after marriage.
      • Format: [1-100] characters.
    • nameQualificationPrefixString

      The qualifier prefix is added to the account holder to distinguish them by specifying a generational standing, an achievement or honor that the person has attained. Only if applicable.

      • Example: "Prof".
      • Format: [1-25] characters.
    • nobilitySalutationString

      Nobility title of the account holder. Only if applicable.

      • Example: "Lord".
      • Format: [1-100] characters.
    • nickNamesString

      A familiar name given to the account holder instead of or as well as the real name.

      • Example: For "Elizabeth", the nickname would be "Liz".
      • Format: [1-100] characters.
    • middleNameString

      The middle name is the second, third, fourth, etc name, if any.

      • Example: "Elizabeth" for "Marie Elizabeth", "Jonh" for "Louis Jonh".
      • Format: [1-100] characters.
    • correspondenceString

      The name that is used for correspondence with the account holders.

      • Example: "M.E. Janssen", "Louis Jonh McKenzie".
      • Format: [1-200] characters.
    • residentialCountryString

      The code identifying the country of the account holder address conformed by ISO 3166-1.

      • Example: "NL"
      • Format: [A-Z] 2 characters.
  • organisationObject

    Object containing information from an organisational account.

    • kvkNumberStringMandatory

      The unique identifier of the organisation allocated by the Chamber of Commerce in the Netherlands. Used to match against KvK registered commercial names. In case the KVK cannot be provided for an account, the customer can insert a "null" value instead by adding eight zeros (check example below).

      • Example: "77251733" Customer does not have KVK number of an account:
      • Example: "00000000"
      • Format: [0-9] 8 characters.
    • kvkBranchNumberString

      The branch number (vestigings-nummer).

      • Example: "012345678901".
      • Format: [0-9] 12 characters. (use leading zeros if necessary).
    • legalNameStringMandatory

      The official name of the organisation as stated in its rules and regulations. This name will be suggested if there is no match found.

      • Example: "SurePay B.V."
      • Format: [1-200] characters.
    • residentialPostalCodeStringMandatory

      The postal code where the organisation is situated. If there is no match, the municipality name will be provided in the response.

      • Example: "0123"
      • Format: [0-9] 4 characters.
    • residentialCountryString

      The code identifying the country of the business address conformed by ISO 3166-1.

      • Example: "NL"
      • Format: [A-Z] only 2 characters.
    • legalStructureString

      The code of the legal form of the organisation as registered at the Chamber of Commerce.

      • Example: "BV", "LLC", "LTC"
    • commercialNameShortString

      Shortened commercial name of the organisation.

      • Example: "SurePay".

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.