Version: 1.0.6
Updated: 24.11.2023
Table of Content
Technical prerequisites on the customer side
Administrative prerequisites on the customer side
User login, environment and file transfer
SFTP Server directory structure
Files compression and encryption
Change log
| 2023-11-24 |
|
| 2023-11-13 |
|
| 2023-10-31 |
|
| 2023-07-19 |
|
| 2023-06-01 |
|
Introduction
This document describes the characteristics and usage of the (automated) file transfer (SFTP) between Holvi Payment Services (hereinafter called Holvi) and its customers / partners (hereinafter called customer).
SFTP, Secure Shell (SSH) File Transfer Protocol, is a network protocol used for secure transfer of data over the internet. The protocol supports the full security and authentication functionality of SSH. It's widely used to exchange data, including sensitive information between business partners in a variety of industries such as financial services, healthcare, retail, and advertising.
Please contact us at the email address developer@holvi.com if you want to connect your financial management software and ERP systems to Holvi via SFTP.
Prerequisites
The customer is assigned a unique user login, used to determine from and to which party files should be transferred.
For authorising access to the SFTP services, Holvi requires public key based authentication.
Schedules and availability
Files can be uploaded and downloaded 24 hours a day, seven days a week. The execution of uploaded files may not happen in real-time, so the processing and response schedules may vary depending on the service.
Holvi will have scheduled service breaks for the SFTP service. The file transfer service is not available during these periods. The breaks are scheduled to take place at night and over the weekend, when traffic is very limited. Such service breaks will be announced according to Holvi’s policy.
Testing
Holvi recommends testing the connection with Holvi’s system before it is used in production. Testing of the connection can be arranged with the customer upon request.
Roles and Responsibilities
The customer takes over the "active client" role and is responsible for all activities required for the file transfer (plus any administrative tasks).
The customer tasks include in particular:
- Automatic scheduling of the client processes
- Setting up a SSL session (including server authentication)
- (if successful): Moving to the download directory and file download
- (if successful): Moving to the upload directory and file upload
- Closing the session
- Analysis of the job history due to the return codes and / or parsing of the server output
- If necessary, initiation of a new transfers attempt and / or the error escalation process
Holvi is responsible for the server processes and in particular takes care of the following tasks:
- The automatic scheduling of server processes
- The provision of files for the collection by the customer
- The forwarding of the files transmitted from the customer
- All tasks concerning the user and system management as well as the data protection
Customer support
Holvi provides support for the SFTP service. Please don't hesitate to contact us at the email address developer@holvi.com.
Procedure
The customer uses a SFTP client and actively sends data files to the Holvi server (upload) or actively collects data files from the Holvi server (download).
Technical prerequisites on the customer side
- Access via TCP/IP (Internet)
- Fixed public IP address of the client system (proxy)
- OpenSSH (or compatible) client components (ssh-shell-client) and / or SFTP client supporting version 3 of the SFTP
- Authentication method: public key
The following limitations apply to every client:
- Filenames to be in UTF-8 encoding. Using different encoding can lead to unexpected results.
Administrative prerequisites on the customer side
- The fixed public IP address of the client system has to be communicated to Holvi
- Access will be granted by unblocking the customer provided address in the Holvi firewall (customer will be informed after completion of the task)
- If necessary, corresponding activation processes have to be carried out in the in-house-network of the customer
- The Holvi server hostname for the connection via the internet is sftp.holvi.com (Production environment), Port: 22.
- One or, if required, several login user names are assigned and communicated to the customer by Holvi.
- A user public key, for authentication to the SFTP server, in OpenSSH format has to be sent to Holvi.
Authentication
Access to the Holvi SFTP server requires public key based authentication.
The key pair (private and public key) can be created as follow:
- On the macOS, Linux, or Unix operating systems, you use the ssh-keygen command to create an SSH public key and SSH private key.
- Windows uses a slightly different SSH key pair format. The public key must be in the PUB format, and the private key must be in the PPK format. On Windows, you can use PuTTYgen to create an SSH key pair in the appropriate formats. You can also use PuTTYgen to convert a private key generated using ssh-keygen to a .ppk file.
The public key generated by the customer must be sent to Holvi. The public key can be for example transmitted to Holvi in the form of an email with attachment.
The private key should be stored following the best security practices on the client system, for example in a Hardware Security Module (HSM).
The following key algorithms are supported for use:
- For ED25519: ssh-ed25519
- For RSA:
- rsa-sha2-256
- rsa-sha2-512
- For ECDSA:
- ecdsa-sha2-nistp256
- ecdsa-sha2-nistp384
- ecdsa-sha2-nistp521
As a general rule, for maximum security, Holvi recommends generating as longer keys as possible.
User login, environment and file transfer
Customer’s user name
After a successful authentication to the Holvi server the customer gains access to the production environment with their login user.
The structure of the login user name is usually as follow:
- <client id><client number>
In general a single login user is assigned to the customer. In some cases several clients can be set up and the customer obtains multiple login user names for their access, only differing by the client numbers.
After a successful login the customer finds himself in the so called "jail" environment, where they can see and access only their own part of the server file system. The rest of the server file system outside the customer home directory is "hidden".
The user's home directory appears to him as /.
Note. User environments of different login user names containing the same <transaction code><customer id> part are (as with all other users) completely separated from each other.
SFTP Server directory structure
The following directory structure will be used for each user environment. The customer can create such folders themselves if needed on the SFTP server.
- /from_holvi
- /archive
- /to_holvi
- /archive
All the above directories are readable and writable by the customer’s user.
In case customer will not deliver payment instructions to Holvi, only from_holvi will be used.
Files download
All files exchanged with Holvi are UTF-8 encoded.
The /from_holvi directory is the directory that will contain the files that Holvi will make available for customer’s collection.
All files that are stored in the /from_holvi directory are named according to the agreed naming convention and can be collected by the customer.
By placing the file in the /from_holvi directory, under a file name agreed upon with the customer, the responsibility for the further processing is passed on to the customer.
The customer has to “mark” a file that they successfully collected from Holvi by either:
- moving it to the subdirectory /from_holvi/archive
- deleting it from the /from_holvi directory
The customer designs the data collection processes according to his own requirements.
Customer should also ensure that as part of their data collection process:
- a successfully collected file will not be downloaded again during a later data collection attempt
- a larger file will not be touched again in a subsequent “later” client process while the “previous” process is already downloading it. This may happen especially when the requests for hosted files are carried out more frequently than the time needed for a complete download (of a larger file)
Holvi recommends the following steps for the download process:
- Check if files were provided in the /from_holvi directory
- If yes, create a download list
- For each single file on the list:
- If successful, start the file download
- If successful, delete the file on the server or move it to the /archive directory
Files upload
All files exchanged with Holvi are UTF-8 encoded.
The /to_holvi directory is the "default target directory" in which the uploaded files must be placed by the customer.
Customer must follow the following two-steps upload procedure:
- The file is uploaded to the /to_holvi directory and named with the .tmp extension (e.g. file_name.xml.tmp). Such files are not yet processed by the Holvi system.
- Once successfully uploaded, the file is renamed to remove the .tmp file extension (e.g. file_name.xml).
Note. The above two-steps procedure is very critical, and must be implemented by the customer, in order to protect against the risk of processing partial uploads.
If a file named in accordance with the agreed convention appears in the /to_holvi directory, the file processing is initiated by Holvi.
With the customer’s successful submission of a file Holvi takes over the responsibility for its further processing.
Once an uploaded file is transferred to the Holvi payment system in order to be processed, Holvi will move it to the /to_holvi/archive directory.
File storage
Both uncollected files and already collected files can be retrieved for a certain period of time from the day they were created. The files uploaded by the customer are kept for a certain period of time from their upload date.
The specific retention period for each type of file (for example bank account statements or payment instructions) can be found in the related service descriptions separately provided by Holvi to the customer.
File naming convention
If possible, file names should comply with common standards and default specifications. Possible deviations are part of a mutual agreement between the customer and Holvi.
Download files
Account statements
For account statements generated by Holvi, the following file naming convention is followed:
- <iban>_<year>_<electronic_number>_<format_identifier>.<file extension>
Example:
- FI4950009420028730_2023_65_camt.053.001.02.xml
Payment status reports
For payment status reports generated by Holvi, the following file naming convention is followed:
- <msgId of the file>_<format_identifier>.<file extension>
Example:
- c42f805c1204370324ba96b02a58a978_pain.002.001.03.xml
Upload files
Payment instructions
The customer is not required to follow any specific file naming convention when uploading payment instruction files to Holvi.
The following file naming convention is however recommended:
- <iban>_<msg_id>_<format_identifier>.<file extension>
Example:
- FI4950009420028730_100123_pain.001.001.03.xml
Files compression and encryption
At the moment the data exchange does not include compression and encryption.
Security instructions
Certificates and their private keys are solely for their proper owners, who must safeguard against inappropriate use of the certificate.
Orders made using the customer’s certificate are always assumed to have been issued by the customer, therefore the certificate and the computer, along with the software in which the certificate is saved, must be properly and securely protected.