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, PSP's can minimize errors and discrepancies in the data transmission process.

Version 1.0Version 2.0 (NEW)

Document History

VersionDateDescription
1.0.015 Jan 2025Original Digital Version. Aligned with PDF V1.1
1.1.017 Jan 2025Added minor fix. Added 'commercialNames' to the 'organisationAccountHolder' section.
1.2.010 Feb 2025Updated mandatory, condition & optional values for 'startDate', 'bankAccountType', 'surname', 'birthName', 'language'. Reordered fields, added new field: 'nomatchSuggestionAllowed' - under organisationAccountHolder, Error Handling section added, updated lei format
1.2.120 Feb 2025Updated the ISO standard for the legalName-language field from ISO639 to ISO639-1, updated unstructuredRemittanceInformation from String to Array of Strings.

File Naming

  • Name convention before the encryption: (pspname)accounts(unixepoch).ndjson
  • Name convention after the encription: (pspname)accounts(unixepoch).pgp
    • Replace ‘pspname’ with your institution's name
    • For the Unix time explanation, see wikipedia
    • 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.
  • Refer to GitHub for the NDJSON specifications.

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-Z0-9]{1,30}$
    • Example: "NL88SRPY9056000789", "BE12345678901234".
  • 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
    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)
    Conditional
    Description

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

    • 'Mandatory' when the customer has enabled the FRI add-on.
    • Format: 'YYYY-MM-DD'
  • Name
    unstructuredRemittanceInformation
    Type
    Array of Strings
    Tag(s)
    Conditional
    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.

    • Format: 140 characters
    • only mandatory in case the account is a collection account.
  • Name
    accountHolderType
    Type
    Enum
    Tag(s)
    Mandatory
    Description

    This designates if the account is a personal account or an account owned by an organisation. The values are:

    • NP - Natural Person
      Mandatory if personalAccountHolders is present.
    • ORG - Organisation
      Mandatory if organisationAccountHolder is present.
  • Name
    bankAccountType
    Type
    Enum
    Tag(s)
    Conditional
    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.
    • 'Mandatory' when the customer has enabled the FRI add-on.
  • Name
    personalAccountHolders
    Type
    Array of Objects
    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","accountHolderType”:”NP”,"personalAccountHolders":[{"initials":"J.R.","allFirstNames":"John Richard","surname":"de Jong - van der Werff"}]}

ndJSON Line (Record)

Natural Person
{"iban":"NL88SRPY9056000789","accountName":"J.R. van der Werff","accountHolderType”:”NP”,”status":"ACTIVE", ”startDate”:”2019-08-24”, “bankAccountType”:”PAYMENTS”, “personalAccountHolders”:[{“allFirstNames:”John Richard”,”initials”:”J”.R.,”surname”:”Werff”,”surnamePrefix”:”van der”}]}

ndJSON Line (Record)

Multiple Natural Persons
{"iban":"BE57SRPYB0906840880","accountName":"J.R. van der Werff & J. de Jong","accountHolderType”:”NP”,”status":"ACTIVE”,”startDate”:”2019-08-25”,”bankAccountType”:”PAYMENTS”,”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.","accountHolderType":"ORG”,”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.","accountHolderType":"ORG”,”status””:”ACTIVE”,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"}}}

Error handling

For every file received, the solution will provide a feedback email sent to one or more addresses set by the PSP. This email will acknowledge the file received and provide feedback on the validation. A file can fully rejected when:

  • The format is not as expected ndjson
  • The filename is not in the format as described in this document
  • The extension is not as expected either .pgp or .ndjson
  • The file could not be decrypted
  • The signature of the file could not be verified

A file will be accepted, and parsed, but individual records can be rejected when:

  • Mandatory fields are missing
  • Fields are not populated according to the specifications
  • Fields are populated with an invalid value

The feedback email will state the file was received and parsed correctly. In case of errors it will provide the information why the file was rejected. In case the file was imported correctly, but individual records are rejected, the records will be named separately in a list including the reason. This list has a maximum of 1000 records. If the total number of invalidated records exceeds this number, a grand total is shown a long with the first 1000 rejected records.

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: ^[A-Z0-9]{18}[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