Account 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, PSPs can minimize errors and discrepancies in the data transmission process.
Document History
| Version | Date | Description |
|---|---|---|
| 1.0.0 | 15 Jan 2025 | Original Digital Version. Aligned with PDF V1.1 |
| 1.1.0 | 17 Jan 2025 | Added minor fix. Added 'commercialNames' to the 'organisationAccountHolder' section. |
| 1.2.0 | 10 Feb 2025 | Updated 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.1 | 20 Feb 2025 | Updated the ISO standard for the legalName-language field from ISO639 to ISO639-1, updated unstructuredRemittanceInformation from String to Array of Strings. |
| 2.0.0 | 20 Mar 2025 | Format changes, refer to the detailed changes here. |
| 2.1.0 | 15 May 2025 | Updated accountHolderType to Mandatory and removed usage rules. Usage rules removed for personalAccountHolders and organisationAccountHolder. Updated file naming conventions: added countrycode to the filename. |
| 2.1.1 | 20 May 2025 | Updated usage rules for accountName. status is now mandatory. |
| 2.1.2 | 16 Jun 2025 | Updated description of EMPL from "employee" to "employer" under schemeNameCode. |
File Naming
The following file naming conventions should be used:
Naming convention before the encryption:
<pspname>_<countrycode>_accounts_<unixepoch>.ndjson
Naming convention after the encryption:
<pspname>_<countrycode>_accounts_<unixepoch>.pgp
- Replace
pspnamewith your institution's name as provided by SurePay. - Replace
countrycodewith the two digit country code based on ISO 3166-1 alpha-2. - For the Unix time explanation, see Wikipedia.
- For example,
SurePaypsp_nl_accounts_1731685567.pgpor
SurePaypsp_nl_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 home directory 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 found within the 'Person' and 'Organisation' objects, respectively. It’s important to mention that a file can only contain records from either Natural Persons or Organisations — not both. Character sets in the files should always be encoded using UTF-8.
ibanStringMandatoryaccountNameStringConditionalaccountHolderTypeEnumConditionalbankAccountTypeEnumConditionalstatusEnumMandatorystartDateStringConditionalunstructuredRemittanceInformationArray of StringsConditionalpersonalAccountHoldersArray of ObjectsConditionalorganisationAccountHolderObjectConditional
ndJSON Line (Record)
{"iban": "NL88SRPY9056000789","accountName": "J.R. van der Werff", "status": "ACTIVE", "personalAccountHolders": [{"allFirstNames": "John Richard", "surname": "van der Werff"}]}
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's receipt and provide feedback on the validation.
A file can be fully rejected when:
- The file content is not valid [Format]. (e.g., NDJSON or PAIN.001)
- The filename is not in the format described in this document.
- The extension is not as expected (.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.
The feedback email will confirm that the file was received and parsed correctly. In case of errors, it will provide information explaining why the file was rejected. If the file was imported correctly but individual records were rejected, the rejected records will be listed separately, along with the reasons for rejection. This list has a maximum of 20 records. If the total number of invalid records exceeds this number, a grand total will be shown along with the first 20 rejected records.
List of Enumeration values
companyId
The following table contains a list of enumeration values:
| Enumeration value | Description | Format | Example |
|---|---|---|---|
| NL_KVK | Identifying number for a registration in the Netherlands Business Register. | Format: [0-9]{8} | Example: '12345678' |
| NL_KVK_BRANCH | Identifying number of a branch, providing information about the specific branch. | Format: [0-9]{12} | Example: '123456789101' |
| FR_SIREN | The unique French business identification number assigned by INSEE, the French National Institute for Statistics and Economic Studies. | Format: [0-9]{9} | Example: '123456789' |
| FR_SIRET | Number providing information about the business location in France. The registration number contains an extra 5 digits (added to the end of the SIREN number to form the full SIRET number). | Format: [0-9]{14} | Example: '12345678900001' |
| EU_VAT | Number used for sending a VAT number associated with a European company. To accept its value, the user must send the country code (from an EU country) plus the VAT number. | Format: Varies by country; typically [A-Z]{2}[0-9]{8,12} | Example: 'FR12345678901' |
| UK_CRN | The unique identifier in the register of the UK's Companies House. | Format: (SC|OC|SO|NI|R|NC|RC|LP|SL|NL){1,2}[0-9]{6,7} or [0-9]{8} | Example: 'SC123456' or '12345678' |
| BE_KBO | The unique business identifier in the Belgium Kruispuntbank van Ondernemingen (KBO). | Format: [0-9]{10} | Example: '1234567890' |
| ES_CIF | The tax ID (CIF - Certificado de Identificación Fiscal) for Spanish companies. | Format: [A-Z]{1}[0-9]{8} | Example: 'A12345678' |
| DE_HRN | The German Handelsregister Number, a unique identifier for limited companies in Germany. | Format: (HRA)[0-9]{6} or (HRB)[0-9]{6} or (HRB)[0-9]{6}(B){1} | Example: 'HRA123456' or 'HRB123456' or 'HRB123456B' |
| LEI | Legal Entity Identifier, an alternate identification for a party. The LEI is a 20-character, alphanumeric code based on the ISO 17442 standard. | Format: [A-Z0-9]{18}[0-9]{2} | Example: 'XYZEFGHIJ0ABCDEF011' |
| BANK | Bank Party Identification request. A unique and unambiguous assignment made by a specific bank or financial institution to identify a relationship between the bank and its client. | Format: [CountryCode][BankCode][BranchCode] | Example: 'US123BANK001' |
| CBID | Central Bank Identification Number request. A unique identification number assigned by a central bank to identify an organisation. | Format: (CB)[0-9]{9,12} | Example: 'CB123456789' |
| CHID | Clearing Identification Number request. A unique identification number assigned by a clearing house to identify an organisation. | Format: [A-Z]{2,4}[0-9]{4,6} | Example: 'CHCLRG1234' |
| CINC | Certificate of Incorporation Number request. A unique identification number assigned by a designated authority to a certificate of incorporation, used to identify an organisation. | Format: (INC)[0-9]{7,10} | Example: 'INC1234567' |
| COID | Country Identification Code request. An identification code assigned by the country authority to identify an organisation (e.g., corporate registration number). | Format: [A-Z]{2}[0-9]{8,10} | Example: 'US123456789' |
| CUST | Customer Number request. A number assigned by an issuer to identify a customer or by a party to identify a creditor or debtor relationship. | Format: (CUST)[0-9]{6,8} | Example: 'CUST789456' |
| DUNS | Data Universal Numbering System request. A unique identification number provided by Dun & Bradstreet to identify an organisation. | Format: [0-9]{9} | Example: '123456789' |
| EMPL | Employer Identification Number request. Number assigned by a registration authority to an employer. | Format: (EMP)[0-9]{6,8} | Example: 'EMP123456' |
| GS1G | GS1 GLN (Global Location Number) Identifier request. A non-significant reference number used to identify legal, functional, or physical entities according to GS1 numbering scheme rules. | Format: [0-9]{13,14} | Example: 'GLN1234567890123' |
| TXID | Tax Identification Number request. | Format: (TX)[0-9]{8,12} | Example: 'TX123456789' |
| BDID | Business Domain Identifier request. An identifier representing the business domain in which the organisation operates. | Format: (BUSDOM)[0-9]{5,10} | Example: 'BUSDOM12345' |
| BOID | Business Other Identification request. Other identification for the organisation. | Format: Not specified | Example: Not Applicable |