Main data file

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

Document History

VersionDateDescription
1.015 Jan 2025Original Digital Version. Aligned with PDF V1.1
1.117 Jan 2025Added minor fix. Added 'commercialNames' to the 'organisationAccountHolder' section.
Version 1.0Version 2.0 (NEW)

File Naming

  • Name convention: (pspname)accounts(unixepoch).ndjson
  • Name convention after the encription: (pspname)accounts(unixepoch).pgp
    • Replace ‘pspname’ with your institution's name
    • For example, SurePayPSP_accounts_1731685567.pgp or SurePayPSP_accounts_1731685567.ndjson

File Structure

  • Each file consists of multiple records (lines).
  • The content of the file should be in Newline Delimited JSON (.ndjson) format.
  • Upload the file to the root folder assigned to you by SurePay

The dummy files below contain the example of how the files should be structured:

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 "Person" and "Organisation" objects respectively. It's important to mention that a file can only contain records from either Natural persons and Organisations. Characters set in the files should always be encoded using UTF-8.

  • 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", "BE12345678901234".
  • Name
    status
    Type
    Enum
    Tag(s)
    Description

    The status of the account.

    • ACTIVE: account is a valid account and supported for checks.
    • INACTIVE: An account has been marked as 'closed' permanently. It's 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. Banks should only deliver INACTIVE account details for no more than 12 months.

    Note: Banks that don’t provide INACTIVE as a status can elect to use an ‘Inactive Logic” which is a feature that will return an INACTIVE response to a request for any accounts not found in the account file provided by the bank.

  • Name
    startDate
    Type
    Date
    Tag(s)
    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
    accountName
    Type
    String
    Tag(s)
    Mandatory
    Description

    The name under which the account is registered at the bank. This field should be provided specifically for the Organisation's account. 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.

    • For Natural Persons, the account name can be a combination of: "allFirstNames" + "surname", "initials" + "surname".
    • For Organisations, the account name can be taken from the following field: "legalName".
    • Format: 140 characters
  • Name
    unstructuredRemittanceInformation
    Type
    String
    Tag(s)
    Description

    Unstructured remittance information is the information in addition to the iban that should be entered by the Payer and used by the Responder to enable them to identify the underlying Account Name in their books. The iban could be a collection account with multiple names and 'additionalInformationAccount' details.

  • Name
    bankAccountType
    Type
    Enum
    Tag(s)
    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 - 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 and pensions accounts (Also known as brokerage account ).
    • OTHER - Other products.
    • UNKNOWN - Unknown account type.
  • Name
    personalAccountHolders
    Type
    Object
    Tag(s)
    Conditional
    Description
  • Name
    organisationAccountHolder
    Type
    Object
    Tag(s)
    Conditional
    Description

ndJSON Line (Record)

Natural Person
{"iban": "NL88SRPY9056000789", "accountName": "J.R. van der Werff", "status": "ACTIVE", "personalAccountHolders": [{"initials": "J.R.", "allFirstNames": "John Richard", "surname": "de Jong - van der Werff", "birthName": "van der Werff"}]}

ndJSON Line (Record)

Natural Person
{"iban": "NL88SRPY9056000789", "accountName": "J.R. van der Werff", "status": "ACTIVE", "personalAccountHolders": [{"allFirstNames": "John Richard", "surname": "van der Werff", "birthNamePrefix": "van der", "birthName": "Werff"}]}

ndJSON Line (Record)

Multiple Natural Persons
{"iban": "BE57SRPYB0906840880", "accountName": "J.R. van der Werff & J. de Jong", "status": "ACTIVE", "personalAccountHolders": [{"initials": "J.R.", "allFirstNames": "John Richard", "surname": "de Jong - van der Werff", "birthName": "van der Werff"}, {"initials": "J.", "allFirstNames": "Julia", "surname": "van der Werff - de Jong", "birthName": "de Jong"}]}

ndJSON Line (Record)

Organisation
{"iban": "BE57SRPYB0906840880", "accountName": "Sports active 123 B.V.", "organisationAccountHolder": {"legalName": [{"language": "NL", "name": "Sports actief 123 B.V."}, {"language": "EN", "name": "Sports active 123 B.V."}], "commercialNames": ["Sports Company", "123 incorporated", "Active 123"], "companyId": [{"type": "BE_KBO", "value": "5658305221"}, {"type": "EU_VAT", "value": "BE5658305221"}]}}

ndJSON Line (Record)

Organisation
{"iban": "BE57SRPYB0906840880", "accountName": "Sports active 123 B.V.", "organisationAccountHolder": {"legalName": [{"language": "NL", "name": "Sports actief 123 B.V."}, {"language": "EN", "name": "Sports active 123 B.V."}], "commercialNames": ["Sports Company", "123 incorporated", "Active 123"], "companyId": [{"type": "BE_KBO", "value": "5658305221"}, {"type": "EU_VAT", "value": "BE5658305221"}], "legalStructure": "BV", "postalAddress": {"countryCode": "NL", "townName": "Utrecht"}}}

List of Enumeration values

CompanyId

The following table contain a list of enumeration values:

Enumeration valueDescriptionFormatExample
NL_KVKIdentifying number for a registration in the Netherlands Business Register.Format: [0-9]{8}Example: '12345678'
NL_KVK_BRANCHIdentifying number of a branch. It gives the information about the specific branch.Format: [0-9]{12}Example: '123456789101'
FR_SIRENThe unique French business identification number.Format: [0-9]{9}Example: '123456789'
FR_SIRETThe number that provides information about the location of the business in France. The registration number contains extra 5 digits (added onto the end of the SIREN number makes the full SIRET number).Format: [0-9]{14}Example: '12345678910111'
EU_VATNumber that allows sending a VAT number associated with an European company. In order to accept its value, the user has to send the country code (belonging to an EU country) plus the VAT number.Format: Multiple Validations depending on country-
UK_CRNThe unique identifier on the register of the UK's Companies House.Format: [SC,OC,SO,NI,R,NC,RC,LP,SL,NL] {2,1}[0-9]{6,7} or [0-9]{8}Example: '12345678'
BE_KBOThe unique business identifier on the Belgium Kruispuntbank van Ondernemingen (KBO)Format: [0-9]{10}Example: '1234567890'
ES_CIFThis is the tax ID (CIF - Certificado de Identificacion Fiscal/Fiscal Identification Certificate) for all Spanish companies.Format: [A-Z]{1}[0-9]{8}Example: 'A12345678'
DE_HRNThe german HandelsRegister Number is a unique identifier used in Germany to identify limited companies.Format: [HRA]{6}[0-9] or [HRB]{6}[0-9]{1}[B]Example: 'HRA123456'
LEILegal entity identification as an alternate identification for a party. LEI is a code allocated to a party as described in ISO 17442 "Financial Services - Legal Entity Identifier (LEI)".Format: [0-9]{4}00[A-Z0-9]{12}[[A-Z]0-9]{2}Example: 'XYZEFGHIJ0ABCDEF011'
CBIDRequestCentralBankIdentificationNumber. Central bank identification number is requested. This is a unique identification number assigned by a central bank to identify an organisation.Format: (CB)(0-9)[9-12 digits]Example: 'CB123456789'
CHIDRequestClearingIdentificationNumber. Clearing identification number is requested. This is a unique identification number assigned by a clearing house to identify an organisationFormat: (A-Z)(2-4 letters)(0-9)(4-6 digits)Example: 'CHCLRG1234'
CINCRequestCertificateOfIncorporationNumber. Certificate of incorporation number is requested. This is a unique identification number assigned by a designated authority to a certificate of incorporation and used to identify an organisation.Format: (INC)(0-9)(7-10 digits)Example: 'INC1234567'
COIDRequestCountryIdentificationCode. Country identification code is requested. This is a country authority given organisation identification (e.g., corporate registration number).Format: (A-Z)(2 digits)(0-9)(8-10 digits)Example: 'US123456789'
CUSTRequestCustomerNumber. Customer number is requested. This is a number assigned by an issuer to identify a customer or a number assigned by a party to identify a creditor or debtor relationship.Format: (CUST)(0-9)(6-8 digits)Example: 'CUST789456'
DUNSRequestDataUniversalNumberingSystem. Data universal number is requested. This is a unique identification number provided by Dun & Bradstreet to identify an organisation.Format: (0-9)(9 digits)Example: '123456789'
EMPLRequestEmployeeIdentificationNumber. Employee Identification Number is requested.Format: (EMP)(0-9)[6-8 digits]Example: 'EMP123456'
GS1GRequestGS1GLNIdentifier. GS1GLN (Global location number) identifier is requested. This is a non-significant reference number used to identify legal entities, functional entities, or physical entities according to GS1 numbering scheme rules. The number is used to retrieve detailed information that is linked to it.Format: (0-9)(13-14 digits)Example: 'GLN1234567890123'
TXIDRequestTaxIdentificationNumber. Tax Identification Number is requested.Format: (TX)(0-9)(8-12 digits)Example: 'TX123456789'
BDIDRequestBusinessDomainIdentifier. Identifier of the business domain in which the organisation is active is requested.Format: (BUSDOM)(0-9)(5-10 digits)Example: 'BUSDOM12345'
BOIDRequestBusinessOtherIdentification. Other identification of the organisation is requested.--
Previous