Skip to content

SFTP File Uploads

ACH payment requests received through SFTP file transfers are validated, formatted in accordance with NACHA guidelines, and delivered electronically in NACHA formatted batch files to the ODFI (Originating Depository Financial Institution) via SFTP. The files are then sent electronically to the RDFI (Receiving Depository Financial Institution), where the debits and credits are applied to the recipient's account.

File Name

The file name should be of the format "YYYY_MM_DD_#.csv", where "#" is an alphanumeric character (either a digit or a capital letter) that is unique for the specified file date. The file name should match the regex /^\d{4}_\d{2}_\d{2}_[0-9A-Z]{1}\.csv$/. If a file submission is rejected with defects, you may resubmit the file with the same file name after correcting the specified defects. The corrected file will overwrite the file with the same name containing defects. If a file with the same name as a previously accepted file is submitted to the SFTP drop folder, it will be rejected (it will not overwrite any file that has already successfully been processed).

Examples

2023_07_28_1.csv, 2023_07_28_2.csv, ..., 2023_07_28_A.csv

File Direction

This file is sent to PayGears from the client.

File Format

The file should be a comma delimited CSV file. There must be at least 16 fields present (fields 0-15 as designated in the table below). Even if optional fields are left blank, the comma delimiters must still be included. Any fields that exist beyond the first 16 (0-15) will be included as addenda. Do not include quotation marks for strings in the csv file and do not include delimiters (commas) as part of a field entry.

Properties CSV Column # Description Schema Required? Example Values
effectiveEntryDate 0 The effective entry date in YYMMDD format string yes 230626
companyName 1 The company name or client code as it appears in the client ACH attributes string yes ABCINC
standardEntryClassCode 2 The Standard Entry Class (SEC) Code indicating the nature of the transaction and applicable conditions for each (see Standard Entry Class Codes). string yes ARC, BOC, CIE, CCD, CTX, POP, PPD, RCK, TEL, or WEB
companyEntryDescription 3 A description of this transaction, such as PAYROLL, PAYMENT, REDEPCHECK (necessary when standardEntryClassCode is RCK), or AUTOENROLL, max length: 10 characters string Required for SEC types ARC, BOC, CIE, CCD, CTX, PPD, RCK, TEL, and WEB PAYMENT
companyDiscretionaryData 4 Optional codes included by the ACH originating company, max length: 20 characters string no, can be empty PayGears ACH
individualName 5 The name of the ACH payment recipient, max length: 22 characters when SEC is PPD, TEL, WEB, PPD, RCK, ARC, BOC, or POP (and for returns), max length: 16 characters when SEC is CTX, max length: 15 characters when SEC is CIE string yes John Smith
routingNumber 6 The routing number of the recipient, length: 9 numeric characters string yes 123456789
DFIAccountNumber 7 The alphanumeric account number of the recipient, max length: 17 characters string yes 1234567890abcdefg
accountType 8 The type of account for the recipient string yes Checking or Savings
transactionType 9 The type of transaction string yes Credit or Debit
amount 10 The requested ACH payment amount. If the amount is 0, then the preNote property must have a value of true. number >= 0, must match regex /^\d+(?:.\d{0,2})?$/ yes 16.08
checkSerialNumber 11 Serial number of the digital check (checkSerialNumber is only allowed/required for ARC, BOC, RCK, and POP Standard Entry Class types), max length: 15 characters when SEC is ARC, BOC, or RCK, max length: 9 characters when SEC is POP string Required for SEC types ARC, BOC, POP, and RCK 123456789012345
terminalCity 12 First four characters of the terminal city, max length: 4 characters string Required for SEC type POP Colu
terminalState 13 Two character state code string Required for SEC type POP SC
identificationNumber 14 Optional additional identifier (identificationNumber is only allowed for CTX, CCD, PPD, TEL, WEB, and CIE Standard Entry Class types), max length: 22 characters when SEC is CIE, max length: 15 characters when SEC is CTX, CCD, PPD, TEL, or WEB string Required for SEC type CIE ACHTrans123
preNote 15 True if prenotification should be utilized to verify account details before debiting/crediting the recipient's account, amount must be 0.00 if preNote is true, nullable boolean no, can be empty true or leave empty
addenda05 16-10015 An array of strings with payment related information, max items: 9999 1-9999 string fields separated by commas Not allowed for SEC types "ARC", "BOC", "CTX", "TEL", "RCK", and "POP". Optional for SEC types "CIE", "CCD", "PPD", and "WEB" UAT penny test

Example File

File Name: 2023_07_31_1.csv

230731,CSVTEST,PPD,PENNY TEST,PayGears ACH,John Doe,031101279,123456789012,Checking,Credit,1.07,,,,,,UAT penny test1
230731,CSVTEST,PPD,PENNYTEST2,PayGears ACH,Susan Doe,031101279,123456789012,Checking,Debit,1.07,,,,,,UAT penny test2
230731,CSVTEST,PPD,PENNYTEST3,PayGears ACH,Jake Doe,031101279,123456789012,Savings,Credit,1.07,,,,,,An,addenda05,with,multiple,items,should,appear,as,multiple fields, separated, by commas, after the first 16, fields
230731,CSVTEST,BOC,PAYMENT,,John Doe,031101279,123456789012,Savings,Debit,1.07,000007,,,,,
230731,CSVTEST,CIE,PAYMENT,Trading,John Doe,031101279,123456789012,Checking,Credit,1.07,,,,1,,UAT test
230731,CSVTEST,CCD,PAYMENT,,John Doe,031101279,123456789012,Savings,Debit,1.07,,,,,,UAT test
230731,CSVTEST,CTX,PAYMENT,Trading,John Doe,031101279,123456789012,Checking,Credit,1.07,,,,1,,
230731,CSVTEST,POP,PAYMENT,,John Doe,031101279,123456789012,Checking,Debit,1.07,000010,term,SC,,,

Connecting to SFTP

Generating Public/Private USER SSH-RSA key-pairs

To integrate with our ACH batch payments solution using SFTP batch file transfers, you will need to generate a USER SSH-RSA key pair and provide us with the public key portion. We will use the public key to grant you access to your client folder on our SFTP server.

In order to generate the SSH-RSA key pair, you may use the CLI command ssh-keygen.

When you run ssh-keygen, you will be prompted to enter the file in which to save your public/private key pair. Enter the desired path and file name. Make sure that you choose a secure location to store your keys.

You will then be prompted (and then reprompted) for an optional passphrase. Press enter both times to leave empty or enter the same passphrase both times. Using a passphrase provides additional security for your private key once it is generated.

You will receive a confirmation that your identification (private key) has been saved in the file name that you specified. Make sure that your private key is not shared with anyone. The private key is what identifies you as the client and will allow you to access the SFTP folder to drop/pick up files. If your private key is ever compromised, notify us immediately so that we can temporarily shut down access to the SFTP server. You should then generate a new SSH-RSA key pair, provide us with the new public key, and use the new private key to re-establish your access to the SFTP server once we have updated the public key for your client folder.

A confirmation that your public key has been saved will also be provided. The public key is saved using the same file name but with a .pub file type. You will also be given a key fingerprint and randomart image.

c:\>ssh-keygen
Generating public/private rsa key pair.
Enter file in which to save the key(C:/.ssh/id_rsa): C:\The\path\for\secrets\fileName
Enter passphrase (empty for no passphrase):
Enter same passphrase again:
Your identification has been saved in C:\The\path\for\secrets\fileName
Your public key has been saved in C:\The\path\for\secrets\fileName.pub
The key fingerprint is: SHA256:123456789asdsdf/dfghjkzxcvbnqwe123456789/ab user@place
The key's randomart image is:
+---[RSA 3072]----+
|                 |
|                 |
|                 |
|                 |
|                 |
|                 |
|                 |
|                 |
|                 |
+----[SHA256]-----+

The public key is what you will need to share with PayGears, while the private key should be used to set up the SFTP server connection on your (the client's) end.

Connecting to the SFTP server

Once you have generated the SSH-RSA key pair and provided us with the public key, we will

  • create a folder specific to your (the client's) platform on our SFTP server,
  • create a user name associated with the public key that you provided in order to grant access to the newly created client folder, and
  • provide you with the host name and user name in order for you to set up a connection to your client folder on our SFTP server.

To test your ability to access your client folder on our SFTP server, an example using WinSCP is provided below.

  • In WinSCP, create a new login connection.
  • Choose "SFTP" as the "File protocol" and enter the "Host name" and the "User name" provided by PayGears.
  • Then choose "Advanced" options and navigate to the "Authentication" tab.
  • In the "Private key file" input field, choose the location of the private key that you generated. The default file type accepted is .ppk. If you have not already converted your private key to a .ppk file type, then choose "All Files" as the file type so that your private key file will be found.
  • Once you select and open the private key file, you will be prompted to convert the OpenSSH private key to PuTTY format (.ppk). Choose "OK".
  • Select "OK" again to confirm your advanced settings and then "Save" the login information that you entered.
  • Finally, attempt to log in using the connection.

If you are able to successfully create a connection session to the SFTP server and see the contents of your client folder (it may be empty at this point) then you have successfully established access.