SFTP Report Service

The SFTP report service is used for downloading settlement reports in several formats.

This service allows for retrieval of settlement files with SFTP.

SFTP is secure file transfer using SSH (Secure Shell), a cryptographic network protocol for operating network services securely over an unsecured network. SFTP can be used manually (interactively), or automatically/programmatically by using SFTP as part of an integration.

See the Settlements overview for more high-level information.

Reports

Each sales unit (i.e., Merchant Serial Number (MSN)) has its own set of settlement reports. It is not possible to aggregate reports from multiple sales units into one report.

There will never be more than one new file per sales unit each day (but there may be none).

Please note: There will be no settlement reports for dates without completed payments and a positive balance. In these cases, neither the settlement files nor the directories that should have contained settlement files will exist.

Settlements are created every day while the balance is positive. See Settlements overview: Availability for more details.

SFTP Service

For an overview of SFTP, see SFTP File Transfer Protocol - get SFTP client & server.

More information about SFTP and the underlying technology: SSH File Transfer Protocol.

Security

For the Vipps MobilePay SFTP service, the public SSH key must be added by logging in with BankID on portal.vipps.no. We don't sign the reports in any way.

SFTP users

All merchants can set up SFTP on portal.vipps.no. A public SSH key must be provided.

SFTP users are created, associated with a public SSH key, and given access to the reports of all the merchant's sales units (i.e., MSNs).

It is possible to use the same public SSH key for multiple merchants, and for multiple MSNs.

Generate a public SSH key

We support RSA (minimum 2048-bit), EdDSA and Ed25519 keys in OpenSSH format. We reject DSA keys.

A key is typically created with this command (replace user@example.com with your real email address):

ssh-keygen -t ed25519 -C "user@example.com"

For help creating SSH keys, see GitHub: Generating a new SSH key.

To give a partner (e.g., accounting partner or ERP partner) access to your reports, you may need an SSH key from your partner. See Partner access.

A public SSH key is normally stored in the user's home directory: ~/.ssh/id_ed25519.pub:

Example:

ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIOu1WvDcTWwZumZZwTvfqUKMA4ouG3mniNsvpNWorm5m user@example.com

Add the SSH key on the Merchant portal

1. Log in with BankID to portal.vipps.no and select the Utvikler section. If you only have Vippsnummer, you will find a link to SFTP setup under Rapporter og tall (i.e., Reports and numbers).
2. Click the tab SFTP Access to add users for SFTP access.
3. Add the public key(s) for the user(s) to give access. After this, you should see the newly created user.

This is what it looks like on portal.vipps.no:

Please note:

• We can't add the SSH key for you.
• We can't test the SSH key for you.
• If you do not have BankID, or you do not have the required permissions to add the SSH key, you will need the administrator to do it for you, or to update your permissions on portal.vipps.no.
• The administrator can create additional users on portal.vipps.no.
• If you don't know who the administrator is, you can check Brønnøysundregistrene and see who has the right to sign for the company.

Partner access

A merchant can give a partner, like an accounting partner or ERP partner, access to the SFTP service, so the settlement reports can be automatically imported.

Partners may provide their merchants with a public SSH key that the merchants can use to give the partner access their settlements.

A merchant may have multiple MSNs, and give several partners access to one or more of them independently.

This is the recommended way:

1. The partner provides a public SSH key to the merchant.
2. The merchant adds the SSH key on portal.vipps.no
3. The partner retrieves the settlement reports with SFTP

Please note: This public SSH key does not have to be secret. To be able to retrieve the reports it is also necessary to have the private SSH key. We recommend that partners use the same SSH key for all their merchants.

How to use the SFTP server

The SFTP server should be straight-forward to use. It works like a normal SFTP service.

Important information

Important: Please read this to avoid misunderstandings:

• The reports are generated on-demand. There are no real files on the server, and all data is generated dynamically.
• When you get a file, or mget multiple files, the server will automatically create the requested file(s).
• Some SFTP clients check the file size with a ls command first. Since the files do not exist until the get or mget command is sent, the file size reported by the server is zero bytes. The SFTP service can't provide correct size information, since there is no real file. It is therefore not possible to check the size of a file with ls. If this causes problems for your SFTP client, the solution is to use a different client.
• Some SFTP clients do not "see" the directories and require the full path of the directories to be explicitly provided.
• Reports under /settlements/inbox can be deleted by using the rm command in SFTP or the "delete" function in your SFTP interface. The files are not really deleted, but actually hidden by moving them to /settlements/archive, in order to keep track of already processed reports.
• Reports under /settlements/archive can't be removed.

Connecting to the SFTP server

This is a standard SFTP service, and the address of the SFTP server is sftp.vipps.no.

When connecting to the SFTP server, you must supply the username you created. In the image above, this is "hakon".

We recommend SFTP File Transfer Protocol - get SFTP client & server for an overview.

Please note: We may change the IP addresses of sftp.vipps.no. To ensure that you are whitelisting the correct IP addresses please use the hostname and DNS, and automatically update your firewall rules if there are DNS changes.

Directory structure

This is the directory structure (where [alternative1|alternative2] indicates two alternatives):

/settlements/[inbox|archive]/[file extension]/[orgno]/[merchant-serial-number]/[merchant-serial-number]-[settlement-number].[file extension]

The orgno is the company's organization number, nine digits. The merchant-serial-number (also called MSN) is the unique five or six-digit ID for the sales unit.

In the examples on this page, the orgno is 998724341, and the merchant-serial-number is 16655.

Example files, with full path:

/settlements/inbox/xml/998724341/16655/16655-2000001.xml
/settlements/inbox/pdf/998724341/16655/16655-2000001.pdf
/settlements/archive/csv/998724341/16655/16655-2000001.csv

Please note: When a file in /settlements/inbox is retrieved, it is automatically moved to /settlements/archive. See also: Important information.

Example SFTP session

Below is an example of an SFTP session using the command-line, with line breaks added for readability.

In this example, the organization number is 998724341 and the MSN is 16655.

Connect to the SFTP service:

$ sftp sftp.vipps.no
Connected to sftp.vipps.no.

Directory listing of the root and settlements directories:

sftp> ls
settlements  

sftp> ls settlements
settlements/archive   
settlements/inbox     

Directory listing of the inbox/, inbox/xml/, inbox/xml/998724341/ and inbox/xml/998724341/16655 directories:

sftp> ls settlements/inbox
settlements/inbox/csv        
settlements/inbox/pdf        
settlements/inbox/xlsx       
settlements/inbox/xml        
settlements/inbox/xml.zip    

sftp> ls settlements/inbox/xml
settlements/inbox/xml/998724341   

sftp> ls settlements/inbox/xml/998724341
settlements/inbox/xml/998724341/16655    

sftp> ls settlements/inbox/xml/998724341/16655
settlements/inbox/xml/998724341/16655/16655-2000001.xml             
settlements/inbox/xml/998724341/16655/16655-2000002.xml            
settlements/inbox/xml/998724341/16655/16655-2000003.xml             
settlements/inbox/xml/998724341/16655/16655-2000004.xml             

Using mget to get all the files in the settlements/inbox/xml/998724341/16655 directory:

sftp> mget settlements/inbox/xml/998724341/16655/*
Fetching /settlements/inbox/xml/998724341/16655/16655-2000001.xml to 16655-2000001.xml
Fetching /settlements/inbox/xml/998724341/16655/16655-2000002.xml to 16655-2000002.xml
Fetching /settlements/inbox/xml/998724341/16655/16655-2000003.xml to 16655-2000003.xml
Fetching /settlements/inbox/xml/998724341/16655/16655-2000004.xml to 16655-2000004.xml

Directory listing in the local directory (using the ! prefix for the ls command), showing the retrieved files, and the quit command to end the SFTP session:

sftp> !ls -1
16655-2000001.xml
16655-2000002.xml
16655-2000003.xml
16655-2000004.xml
sftp> quit

All the above is basic SFTP use and should be straight-forward. If you use a SFTP client, please refer to its user documentation.