This article explains how YayPay is configured to connect to your FTP server which will automate the import of the 6 CSV files within the zip file, and reduce or stop the need to perform manual imports. (Note: the FTP server does not need to be a dedicated or a new one). Read on further if you have to whitelist YayPay. 

Your FTP Server will hold the zip file, containing the 6 CSV files, as well as your Invoice Template/PDF files that YayPay will attempt to sync each time it connects with your FTP Server/Host. This frequency is about every 60-90 minutes apart.

1. What does YayPay bring over from your FTP Server?

There are 2 categories of data and files that YayPay will look to sync over from your FTP Server:  

• The named Zip file containing your AR data records is represented in the 6 CSV files - i.e. customer.csv, contact.csv, invoice.csv, invoiceLines.csv, transaction.csv, transactionAllocations.csv
• Your Invoice Template in a PDF file format – this is also synced to YayPay after the CSV import is completed (Refer to this Article link for more information) 
  • The purpose of bringing your Invoice Template/PDF over is to show your Customers the same Invoice template that you issue / bill them, which they can view through YayPay (e.g. when they click on the Invoice #)
  • The same invoice Template/PDF can also be incorporated as a file attachment when you configure the Workflows / Email Reminders in YayPay

2. What is the process of YayPay pulling the info from the FTP Server?

On your FTP Server (find instructions below), it is good practice to set up a main folder (set it up in Settings > Integrations > FTP section > Polling directory field) which contains:

• a folder with all zip files
• a zip file with PDFs (set it up in Settings > Integrations > FTP section > File name restriction field), 
• a folder "processed"
• a folder with logs 

The screenshot below represents the example folder names, your folders have different names 

Figure 1. Setting up a pulling directory for the correct integration process. 

When you drop the files on the appropriate folders and connect YayPay to FTP Server(find instructions below), click sync, and the info is pulled to YayPay.

1. The first thing to process is the zip file which is contained in the mail folder

2. When the info is processed, the system checks the pdf folder and looks for file names matching invoiceId of each line in CSV zip file to attach PDF files to the records

3. The processed zips and pdfs are moved to the folder "processed" (if the correspondent setting is on, read section 3 for details) 

• If a PDF from the pdf folder does not match any invoiceid in the CSV file, it remains in the pdf folder 
• If the pdf folder contains a file with the same name as a pdf file that is being moved, the newer file overrides the old one and is saved to the folder.

3. How to Configure YayPay with your FTP Server?

This section describes the information required to configure YayPay to connect to your FTP server. This setting will be repeated in each instance of YayPay (if you have multiple instances).

An FTP client software like FileZilla will be useful also to test the connection to your FTP Server, prior to configuring YayPay.

Go to Settings > Integrations page and look for the FTP section.

The required setup data includes (provide this to your YayPay the representative who can help you configure):

• Protocol - Select the protocol for the file transfer (FTP or SFTP being the most common)
  • FTP - Standard File Transfer Protocol
  • SFTP - Secure File Transfer Protocol (uses SSH to establish a secure connection)
  • FTPS - File Transfer Protocol Secure (uses SSL/TLS to establish a secure connection)
• Host – This is the host/server name of your FTP Server setup by your internal IT
  (e.g. ftp.yourftpservername.com, sftp.yourftpservername.com)
• Port – the default one is 21. Available are: 25, 465, 587, 143, 993, 21, 22, 990, 989. Other ports might not work due to security protocols. 
• Polling directory- This is the folder where your zip file will be placed (e.g. put "/" for root level or "/Subfolder_name/" if there is a subfolder where the zip file will be kept in the FTP Server
  • Use Subfolders on your FTP Server to segregate the data extracted and prepared for your different Business Subsidiaries. This structure will help to ensure the right zip file will be imported into the appropriate YayPay instance
  • Name your Subfolders after your Subsidiary Name for easy reference so that there is no risk of the wrong zip file being imported into the wrong instance of YayPay 
• File name restriction – Regardless of how you name your zip file on your FTP server, copy and paste this exact string into YayPay, i.e. File name should contain the format: .zip or .ZIP 

The user has three options to login to the SFTP server:

1) The user enters the Login(User in YP) and Password.

2) The user enters the Private key, the Public key, and the Passphrase. (only SFTP)

3) The user enters the Private key and Public key. (only SFTP) 

• User - This is the FTP username that Yaypay will use to connect to your FTP Server
• Password/Passphrase - This is the FTP password that Yaypay will use to connect to your FTP Server (If you use User login use Password. If you use public and private keys, there is an option to create a Passphrase at your discretion, check the instruction how to create a Private key below) 
• Public key (only for SFTP) - IMPORTANT: when you create a Private key (instructions link below) there is a default Public key created along and it shouldn't be used, there is an extra action required to get an appropriate public key - a server public key (check a Note below)
• Private key (only for SFTP) - Instruction on how to create a Private key

ssh-keygen -t rsa "yourhost.example.com"

Container type: 

• Archive: used to load archives in zip format, file name restriction might require specification like (.*\.([zZ][iI][pP])$) or *.*
• Directory: used to load CSV files without the necessity to archive them into a zip file, the files need loading into a separate directory sitting in the root of the folder with data to integrate, the directory will then be moved to a /processed folder on FTP, so with this method, the directory containing CSV files need to be created each time with the new name (the already used names are not allowed); filename restriction applies: the value in configuration should be the same as the name of the directory CSV files are placed to. This method works for FTP integration only, with no manual upload.

Missed invoices action:

By default, it is set to "Skip" - on the condition if already uploaded invoices are missed in the next files, YayPay doesn't apply any changes to them. 

If set to "Mark as paid", then the invoices (which are absent in the next CSV uploading but exist in YayPay) change their status to Paid.  

For the option “Action after file processing”, choose one of the following:

• Nothing – Do nothing about the zip archive file
• Rename – Rename the zip archive file after it has been imported
• Move – Move the zip file to another folder in the FTP Server after the zip file has been imported - a ‘/processed’ folder will be created on the FTP Server where the zip file will move into (this is the recommended option so that there is visibility for you that the zip file has been processed)
• Delete – Delete the zip archive file after it has been imported

Click Save to save all your settings configured. 

If you choose the "Move" option, ensure that the FTP user credentials configured for YayPay has the proper permissions to access folders on your FTP server, e.g.:

Before you proceed and click on the Sync button located in the top-right corner of the page, it is recommend to test the connection and settings by clicking on the Diagnostic Sync button. For details, see the Tip below.

Return to the panel and press SYNC to start the import process (i.e. YayPay will process the 6 CSV files contained within the zip file on your FTP Server/Host). Other statuses will appear as follows when the Import is completed:

Once the connection is established, YayPay remains connected to your FTP Host until you press the "Disconnect" button. From then on, YayPay will also poll the FTP Server multiple times a day to look for new zip files that you may have placed on the server, etc.

If you also have your Invoice Template/PDF files on the FTP Server (read on in the next section), they will also be imported after the zip file.

4. Frequency of Imports and Updates to YayPay after the FTP connection is established

Once YayPay is connected to your FTP server, the application remains connected until you disconnect. There is a background process that runs every 60 min or thereabouts and polls to see if there are new zip files and/or Invoice PDF files placed in the folders on your FTP Server. Previous files placed on the FTP Server and imported can be moved to another folder by configuring that option in YayPay.

If you have a schedule to place the zip file & Invoice PDF files once in the early morning, and once in the evening, both zip files will be uploaded automatically and then moved to the /processed folder on your FTP Server for example

5. Setup and placement of Invoice template/PDF files on client’s FTP Server

Follow these steps to prepare and sync your Invoice Template/PDF files from your FTP Server:

• Create a new folder in your FTP Server/Host called ‘pdf’ and place your Invoice Templates/PDF files in this folder. See the illustration below:

• The filename for each Invoice Template/PDF file should be the same as the value used in the invoiceId column, to represent the invoice # or invoice record in the invoice.csv file 
  • The invoiceId and invoiceNumber columns in the invoice.csv file can be of the same value or different. You will have to choose one approach and remain consistent in the invoice.csv file:

For example, the Invoice Template/PDF file name for invoiceNumber 101260663 represented in the invoice.csv file, should be 101260663.pdf IMPORTANT: for PDF file name please use the value from invoiceId column, values from other columns are not recognized by the system in this case. 

The sync of the Invoice Template/PDF files will happen after the import of the zip file containing the 6 CSV files from your FTP Server.

Operationally, this process will tie back to your invoicing operations, i.e.

• When new invoices are created in your ERP, the same invoice records should be prepared and represented in the invoice.csv file so that YayPay is updated eventually
• And the corresponding named Invoice Templates/PDF files should also be placed in the pdf folder of the FTP Server (this does not have to be done at the same time as the above point, but preferably on the same day to avoid spilling over into the next day)
• If there are further changes to the original invoice record which was previously imported into YayPay, both the updated invoice record and the "updated" Invoice template/PDF file should also be prepared and placed on the FTP Server. The next import will update what is in YayPay

6. Allowed YayPay IP Address to connect to the FTP Server

For security reasons, we highly recommend that you block all attempts trying to connect to the FTP server, and only allow the hosts that you recognize:

• Your servers that should have access to FTP, for example, to push the ZIP/PDF files.
• Employees that should have access to FTP.
• YayPay servers listed in the table below:
  
  

  YayPay Environment	IP Address	Additional Notes
  US Production	52.70.204.146, 34.195.225.244	v2 is 34.195.225.244
  EU Production	54.170.157.209
  Developer	34.228.204.221	US Prodlike/Apienv

7. FTP Logs to show overall count of records imported 

Go to the Settings > Integrations page and look for the FTP section. Click on LOGS to download a log file to Excel

8. Email Notification for FTP Connectivity issues

If there is a connectivity issue to your FTP Server, a system-generated alert is sent to the email address configured in the main AR Email field, which is located under Settings > Business page.  

The email notification is sent out after 3 consecutive errors/retries.

9. Bandwidth of the CSV Connector

Production Environment:

1. The CSV connector can process up to 10,000 records in up to 5 minutes.
2. The CSV connector can process up to 100,000 records in up to 50 minutes.

Development Environment:

1. The CSV connector can process up to 10,000 records in up to 5 minutes.
2. The CSV connector can process up to 100,000 records in up to 5-6 hours.

Summary

Overall, once YayPay is connected to your FTP server, this is the location where YayPay imports your AR data as well as your Invoice Templates (PDF files) summarized below:

Practical Points

Q: What does it mean if you receive a "Permission denied" error message shown in the Error Log?

While the username/password credential established for YayPay was successful in the login attempt to access your FTP Server, and also read the zip file to import the AR data, the process could not resolve other related actions like moving the zip file to the /processed folder (if this was configured in YayPay in your instance) and creating the log file in the /logs folder of your FTP Server.

Review the Permissions setup for the YayPay username and ensure it has Read & Write on your FTP Server for all folders and subfolders that the credential should have access to (Note: Execute permission is not required).