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 connectFi 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.