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. |
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 - Replace
countrycodewith the two digita 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 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 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.
- 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".
- Format:
- Name
accountName- Type
- String
- Tag(s)
- Conditional
- Description
The name under which the account is registered at the PSP. In case the name of the account holder is longer than the permitted characters, this has to be shortened until it reaches the maximum number of allowed characters. The
accountNamecan be created based on the following combinations:- For Natural Persons, the account name can be a combination of:
allFirstNames+surnameorinitials+surname. - For Organisations, the account name can be taken from the following field:
legalName. - Format: Max. 140 Characters.
- Usage Rule:
- If the account is active, then Mandatory.
- For Natural Persons, the account name can be a combination of:
- Name
accountHolderType- Type
- Enum
- Tag(s)
- Mandatory
- Description
This designates if the account is a personal account or an account owned by an organisation.
- Possible Values:
- NP: Natural Person
- ORG: Organisation
- Possible Values:
- Name
bankAccountType- Type
- Enum
- Tag(s)
- Conditional
- Description
The type of bank account.
-
Possible Values:
- PAYMENTS: A payments account, also known as a checking account.
- SAVINGS: A savings account.
- MORTGAGE: A mortgage account.
- TRUST: Also known as 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: Also known as brokerage account or pension account. An account used for investing.
- OTHER: Other products.
- UNKNOWN: Unknown account type.
-
Usage Rule: Mandatory when the customer has enabled the FRI add-on.
-
- Name
status- Type
- Enum
- Tag(s)
- Mandatory
- Description
The status of the account.
- Possible Values:
- ACTIVE: Account is a valid account and supported for checks.
- INACTIVE: An account has been marked as 'closed' permanently or temporarily unable to receive payments.
- Possible Values:
- Name
startDate- Type
- String
- Tag(s)
- Conditional
- Description
The date when the account was opened and registered by the PSP. Reflects the real start date of the account.
- Usage Rule: 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
- Usage Rule: only mandatory in case the account is a collection account.
- Name
personalAccountHolders- Type
- Array of Objects
- Tag(s)
- Conditional
- Description
- Name
organisationAccountHolder- Type
- Object
- Tag(s)
- Conditional
- Description
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 format is not as expected. (e.g., NDJSON)
- 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.
- Fields are populated with an invalid value.
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 1,000 records. If the total number of invalid records exceeds this number, a grand total will be shown along with the first 1,000 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 | Employee Identification Number request. | 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 |