# Pagero SFTP solutions ## Introduction SFTP, which stands for [SSH File Transfer Protocol](https://en.m.wikipedia.org/wiki/SSH_File_Transfer_Protocol), is a secure method for transferring files over a network. It is commonly used to securely exchange files between a client and a server, ensuring confidentiality and integrity during transmission. Unlike traditional FTP ([File Transfer Protocol](https://en.m.wikipedia.org/wiki/File_Transfer_Protocol)), which lacks encryption, SFTP encrypts both commands and data, providing a higher level of security. This encryption makes SFTP an ideal choice for organizations needing to transfer sensitive data, such as financial records, customer information, or proprietary documents, over the internet or internal networks. --- ## What we offer We offer customers the possibility to both send files to and receive/fetch files from our Pagero File Exchange Server (PFEX) via SFTP. Our PFEX server allows your company to reliably and securely transfer data to and from Pagero Online making your company one step closer to fully utilize the reach of the Pagero Network. Our SFTP via PFEX solution assumes a lot of sensible defaults, e.g. a [default directory structure](#default-directory-structure) and a [default filename schema](#filenames) to name a few. These are described in more detail below. Should you require more customization and/or additional functionality while still using SFTP; we naturally offer more bespoke solutions as well. We strongly recommend that you adjust your integration to our Pagero-run SFTP via PFEX solution as this will shorten your setup and configuration time, minimize resource allocation and help make you compliant from day one. --- ## What's included? We offer two different SFTP packages; Advanced and Enterprise. Below is an overview of what's included in each of the two. {.compact} Feature | Advanced | Enterprise --- | :---: | :---: [Default directory structure](#default-directory-structure) | :white_check_mark: | :white_check_mark: [Default filename schema](#filenames) | :white_check_mark: | :white_check_mark: [Basic authentication (username + password)](#authentication-method) | :white_check_mark: | :white_check_mark: Default attachment handling | :white_check_mark: | :white_check_mark: [Public key authentication](#authentication-method) | :white_check_mark: | :white_check_mark: Customized directory structure | | :white_check_mark: Customized filename schema | | :white_check_mark: Customized attachment handling | | :white_check_mark: Customized envelope- and/or batching handling | | :white_check_mark: Technical receipts/acknowledgements | | :white_check_mark: !!! **NOTE:** If you want to upgrade from Advanced to Enterprise, just reach out to your salesperson or our [Support](../../get-support.md) who will assist you further. !!! --- ## Prerequisites Prior to being able to use our SFTP via PFEX offering, you need to have purchased and activated our advanced connectivity service. Your internal integration/middleware solution also needs to support the sending and/or fetching of files through an SFTP client. When we create your SFTP account on our PFEX server, our system generates a username and password which will be sent to you via email. Use these credentials together with the [Connectivity Details](#connectivity-details) described below for connecting to the the server. --- ## Connectivity details The following parameters are static and will not change. Use these for connecting to our PFEX server. {.compact} Parameter | Value --- | --- Host/URL | [pfex.pageroonline.com](sftp://pfex.pageroonline.com:22) Port | 22 User | Sent to your company integration user at the time of account creation. Password | Sent to your company integration user at the time of account creation. !!! **NOTE:** [pfex.pageroonline.com](sftp://pfex.pageroonline.com:22) is **only** reachable via SFTP, not e.g. HTTP. Visiting the URL via e.g. a web browser will not work. !!! --- ## Default directory structure ### Single company When we create an SFTP account for you on our PFEX server, our system generates a default directory structure on the virtual file system automatically. The directory structure is built up using document types as the basis of the structure. It, quite explicitly, shows how to utilize direction, to/from Pagero, document type and send mode. ||| Directory structure (condensed for readability) ``` 3f8741ce-fc1b-48f6-82e5-6c91946fefa7 (authCompanyId) toPagero (direction) applicationResponse (document type) cert (send mode) prod temp test catalogue dispatchAdvice documentPushback documentStatus invoice invoiceReport order orderAgreement orderCancellation orderChange orderResponse payment receipt report paymentReminder receipt receiptAdvice taxData taxDataReport taxDataReportResponse transport deliveryForecast transportInstructionResponse transportInstruction transportStatus utilityStatement fromPagero applicationResponse prod temp test catalogue dispatchAdvice ... ``` ||| Explanation - **authCompanyId:** A unique ID generated for you company account in Pagero Online. This is the "home" of your SFTP user. This will either be positive integer value (e.g. `1234567890`) or a UUID (e.g. `123e4567-e89b-12d3-a456-42661417400`). In company group scenarios, each sub-company gets their own "home" by default. - **toPagero/fromPagero:** Describes the direction of the document flow. - **applicationResponse:** Describes the document type in question. - **temp:** Short for "temporary", can optionally be used as an intermediate destination while writing files. When the write has finished, files are expected to be moved to either of the three send mode directories described in the next step below. This sub-directory is created in all document type directories. - **cert/test/prod:** The three different send modes we support. For more information, please see [send modes](#send-modes). These three sub-directories are created in all document type directories. ||| !!!warning **NOTE:** This directory structure **cannot** be changed or adjusted. !!! !!! **NOTE:** While you can access and write files to all of these directories, you may not have the appropriate processing service for all document types in Pagero Online. In such cases, the document will stop once it reaches Pagero Online and an error response will be returned to you via email. !!! ### Company groups In company group scenarios, the default directory structure looks almost identical, but each company have their own unique root. ||| Directory structure (condensed for readability) ``` 3f8741ce-fc1b-48f6-82e5-6c91946fefa7 (authCompanyId) toPagero (direction) applicationResponse (document type) cert (send mode) prod temp test catalogue dispatchAdvice ... fromPagero applicationResponse prod temp test catalogue dispatchAdvice ... 9f857d0c-d947-4cc8-9e0b-626490a07a07 (authCompanyId) toPagero ... fromPagero ... 66970b45-a757-4cdc-9edd-56c193095ad0 (authCompanyId) toPagero ... fromPagero ... ff8cbef0-9f87-4bd1-bef9-5542f031de2d (authCompanyId) toPagero ... fromPagero ... ... ``` ||| Explanation - **authCompanyId:** A unique ID generated for you company account in Pagero Online. This is the "home" of your SFTP user. This will either be positive integer value (e.g. `1234567890`) or a UUID (e.g. `123e4567-e89b-12d3-a456-42661417400`). In company group scenarios, each sub-company gets their own "home" by default. - **toPagero/fromPagero:** Describes the direction of the document flow. - **applicationResponse:** Describes the document type in question. - **temp:** Short for "temporary", can optionally be used as an intermediate destination while writing files. When the write has finished, files are expected to be moved to either of the three send mode directories described in the next step below. This sub-directory is created in all document type directories. - **cert/test/prod:** The three different send modes we support. For more information, please see [send modes](#send-modes). These three sub-directories are created in all document type directories. ||| --- ## Send modes For more information about different send modes, please see the send modes section. [!ref Send modes](../../additional-functionality/send-modes) --- ## Supported file extensions The following file extensions are supported: - `.xml` - `.txt` - `.json` - `.csv` - `.x12` - `.edi` - `.zip` --- ## Filenames ### Files to Pagero In this direction, you are free to name the files whatever you want, as long as the [file extension is supported](#supported-file-extensions). ### Files from Pagero In this direction, the following default filename schema is used: - Main document: `1234567890.xml` (naturally, other file extensions are supported as well depending on format) - PDF Presentation: `1234567890.pdf` - Miscellaneous attachments: `1234567890_1.xslx`, `1234567890_2.doc`, `1234567890_3.jpg` etc. --- ## Attachment handling This section shows available options for sending and receiving attachments with Pagero SFTP solutions. For more information about attachments, please see the attachment section. [!ref Attachments](../../additional-functionality/attachments/) ### Embedded in the format Transfer of the attachment can also be done by embedding the attachment in the business document if the document format you send supports it. There are several ways to embed an attachment but the most common one is to encode the attachment using [Base64](https://en.m.wikipedia.org/wiki/Base64) and add to the business document according to format specification. [!ref Embedded attachments](../../additional-functionality/attachments/#embedded) --- ## Temporary file handling Our intellegent PFEX solution will not pick up files for processing BEFORE the client terminates the SFTP connection. You can write straight to the `(cert|test|prod)` directories without risking incomplete files getting picked up if you use a temporary filename and then rename once you have finished writing the file. The following temporary file extensions are ignored and not picked up for further processing: - `.tmp` - `_tmp` - `.temp` - `_temp` - `.part` - `.filepart` - `.inprocess` We do still create a `temp` directory by default for those wishing to use a more traditional approach, i.e. write files to `temp` and once the file write finishes; move the file to `(cert|test|prod)`. --- ## File & document storage Files written to our server in accordance with the connectivity details listed on this page will be picked up instantaneously and forwarded to Pagero Online for further processing. Files written to our server but not picked up will be automatically deleted after 30 days. Pagero Online stores documents for 90 days, after which documents get deleted automatically. We do offers e-archiving-services, which – if used – saves documents in accordance and compliance with local regulation. --- ## Security ### Authentication method Our PFEX server supports two methods of authentication. - [Basic authentication](https://en.m.wikipedia.org/wiki/Basic_access_authentication) (username and password) - [Public key authentication](https://en.m.wikipedia.org/wiki/Public_key_infrastructure) (RSA key is used) Basic authentication is most commonly used due to its administrative simplicity however we recommend the use of public key authentication since it will strengthen the security. ### Encryption The encryption used on our PFEX server is SSHv2. Two steps are involved: 1. A handshake where the server presents RSA-key as identification of being a recognized and correct server. The key should be at least 2048 bits long. 2. Server and client negotiate an algorithm and a key size to be used to encrypt the data. Our PFEX server supports many variants here, see full list below. Which one used is determined during the handshake between client and server. The strongest possible algorithm that is supported on both the server and client is chosen. ### Supported algorithms Here is a full snapshot of all algorithms supported on our PFEX server. #### Key Exchange (KEX) algorithms - `curve25519-sha256` - `curve25519-sha256@libssh.org` - `curve448-sha512` - `ecdh-sha2-nistp521` - `ecdh-sha2-nistp384` - `ecdh-sha2-nistp256` - `diffie-hellman-group-exchange-sha256` - `diffie-hellman-group18-sha512` - `diffie-hellman-group17-sha512` - `diffie-hellman-group16-sha512` - `diffie-hellman-group15-sha512` - `diffie-hellman-group14-sha256` - `ext-info-s` - `kex-strict-s-v00@openssh.com` #### Server host key algorithms - `rsa-sha2-512` - `rsa-sha2-256` - `ssh-rsa` #### Encryption algorithms - `chacha20-poly1305@openssh.com` - `aes128-ctr` - `aes192-ctr` - `aes256-ctr` - `aes128-gcm@openssh.com` - `aes256-gcm@openssh.com` - `aes128-cbc` - `aes192-cbc` - `aes256-cbc` #### Message Authentication Code (MAC) algorithms - `hmac-sha2-256-etm@openssh.com` - `hmac-sha2-512-etm@openssh.com` - `hmac-sha1-etm@openssh.com` - `hmac-sha2-256` - `hmac-sha2-512` - `hmac-sha1` #### Compression algorithms - `none` - `zlib` - `zlib@openssh.com` #### Raw NMAP scan result ``` nmap -p22 -Pn -sV --script ssh2-enum-algos pfex.pageroonline.com Starting Nmap 7.94SVN ( https://nmap.org ) at 2024-02-23 13:21 CET Nmap scan report for pfex.pageroonline.com (91.238.51.55) Host is up (0.016s latency). PORT STATE SERVICE VERSION 22/tcp open ssh (protocol 2.0) | ssh2-enum-algos: | kex_algorithms: (14) | curve25519-sha256 | curve25519-sha256@libssh.org | curve448-sha512 | ecdh-sha2-nistp521 | ecdh-sha2-nistp384 | ecdh-sha2-nistp256 | diffie-hellman-group-exchange-sha256 | diffie-hellman-group18-sha512 | diffie-hellman-group17-sha512 | diffie-hellman-group16-sha512 | diffie-hellman-group15-sha512 | diffie-hellman-group14-sha256 | ext-info-s | kex-strict-s-v00@openssh.com | server_host_key_algorithms: (3) | rsa-sha2-512 | rsa-sha2-256 | ssh-rsa | encryption_algorithms: (9) | chacha20-poly1305@openssh.com | aes128-ctr | aes192-ctr | aes256-ctr | aes128-gcm@openssh.com | aes256-gcm@openssh.com | aes128-cbc | aes192-cbc | aes256-cbc | mac_algorithms: (6) | hmac-sha2-256-etm@openssh.com | hmac-sha2-512-etm@openssh.com | hmac-sha1-etm@openssh.com | hmac-sha2-256 | hmac-sha2-512 | hmac-sha1 | compression_algorithms: (3) | none | zlib |_ zlib@openssh.com | fingerprint-strings: | NULL: |_ SSH-2.0-APACHE-SSHD-2.12.1 ``` !!! **NOTE:** This list is actively maintained by us, and things may get added/removed at our discretion. !!!