This guide is intended for developers using the ACH Pro API

Overview

ACH Pro allows you to upload NACHA files created in the platform directly to your bank’s SFTP server. Every bank you create in ACH Pro can have its own SFTP configuration.

This guide will walk you through creating an ODFI, configuring its SFTP settings and uploading a NACHA file using the API. We won’t cover the creation of the NACHA file in this guide, refer to creating an ACH file if you need guidance for that process.

Walkthrough

The instructions below cover every step need to upload a NACHA file to your bank’s SFTP server.

1. Create an ODFI

Every ACH file needs to be configured for origination by a specific bank (aka ODFI). In addition, we need an ODFI to exist before we can create an SFTP configuration for it. To review the full type definition, see the ODFI reference.

Create ODFI - POST /odfis (API docs - Postman Collection):

{ 
  "name": "Bank of America", 
  "routingNumber": "026009593", 
  "fileLineEndings": "UNIX" 
}

Response:

{ 
  "odfiId": "04C39B4FA21E45A78E091E959B47CDCF", 
  "profileId": "02318E20F6E34A7EAF8D2EC1E32DD181", 
  "name": "Bank of America", 
  "routingNumber": "026009593", 
  "immediateOrigin": null, 
  "immediateOriginName": null, 
  "immediateDestination": null, 
  "immediateDestinationName": null, 
  "fileLineEndings": "UNIX" 
}

2. Create an SFTP Configuration

Now that we’ve created an ODFI, we can create an SFTP configuration for it. An ODFI can have only one SFTP configuration.

ACH Pro supports SSH key authentication and username/password authentication. If you use SSH keys, the API will create a key-pair and provide you with the public key. You must provide the public key to your bank’s SFTP administrator to associate with your user.

SFTP Configuration fields:

Field	Description
authType*	(Required) Either `KEY_PAIR` (SSH key authentication) or `PASSWORD` (username/password authentication).
username*	(Required) SFTP username
password	(Required if authType = PASSWORD) SFTP password
host*	(Required) SFTP server URL
port*	(Required) SFTP server port, typically port 22
directoryPath	(Optional) Specific directory on server for file upload. Use an empty string to upload to the user’s home directory.

Create SFTP Config - POST /odfis/{odfiId}/sftpConfig (API docs - Postman Collection):

{ 
  "authType": "KEY_PAIR", 
  "username": "user1",
  "host": "sftp.mybank.com", 
  "port": "22", 
  "directoryPath": "" 
}

Response:

{ 
  "sftpConfigId": "5FAEE58A46E6465A947EDC7D99697770", 
  "profileId": "02318E20F6E34A7EAF8D2EC1E32DD181", 
  "odfiId": "04C39B4FA21E45A78E091E959B47CDCF", 
  "authType": "KEY_PAIR", 
  "username": "user1", 
  "publicKey": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAACAQCw2jRK++3ia2ylzZxbSmME0LkzOjuXu6UvILv+zi1L0GDrOp3wjFBDjCFNtkqRerwHWJ9/AURTVruCTDUtWoxOaNcEwru2KI+00+xnZFHudFfliywzOkMks/11wAtS0pS8XhzsFa2AIeDdOt0jaUpCVmm9zi/30Dbxju+Dp1dYZlGc51rfgk+gdaIClcFrkpSkIvkXtcjCi0Ax2Ddu9O5k8d5ZWtRF+M5Ap+FROrPeiS0JBsaGzZVcc/L+qM4/SDKKDTDU0sPlxjw+te8Z+cBHGTGV1E59gSRlnMFri/JaWUOa2hbfcqAf7zymW0iY2/8hoS41AEoZRdCaUQC2AaHyxCo36SWVUVeOC+H8qqAbzH/o27bVilU8G6kJmYR94ISk2BgZLT3kcTSELIb4p/qX+x/MfQb55mwcoIj4kbbboTYBS0pc/r1AN/BkzwTVRwQa49JXJVaSu+Y7wh36hG7QNayNtLxFfAYVA4bHnah+4z8NHJSKC8524a2jtDhxnsjiQZsWz8spGZO63jUa4+xE0G6EQFF9psJmKOSwu+USCpkhNMGuaWrOU5yICVj+VEPuaXTWUvDHKIDNTWzaRSbwZDg0rfhesigmvFT1obm7pztcWWyzfAhdF9dvFLqsOjNK7c1w65AOARFm/amPjrOVI2+coyKpoK1L0lDpTfYJvw==", 
  "dateCredentialsUpdated": "2024-03-04 03:01:20", 
  "host": "sftp.mybank.com", 
  "port": "22", 
  "directoryPath": "", 
  "dateUpdated": "2024-03-04 03:01:20", 
  "dateCreated": "2024-03-04 03:01:20" 
}

3. Test SFTP Connection

We can now test our SFTP configuration to make sure everything is configured correctly. Check success in the response to determine if the test was successful.

Test SFTP Config - POST /odfis/{odfiId}/sftpConfig/testConnection (API docs - Postman Collection):

Empty Body

Response:

{ 
  "sftpLogId": "313E5DF0FA134A66A8A185513A2F5266", 
  "profileId": "3CBD2ACD5D8044A88308CCF4A3C15FBF", 
  "odfiId": "1B531104DC764506965EA979D0C5E50F", 
  "historicalFileId": null, 
  "authType": "KEY_PAIR", 
  "fileType": "CONNECTION_TEST", 
  "username": "user1", 
  "host": "sftp.mybank.com", 
  "port": "22", 
  "directoryPath": "", 
  "responseTime": 3280, 
  "response": "Successfully connected to remote server", 
  "success": true, 
  "dateCreated": "2024-03-04 03:49:54" 
}

4. Upload NACHA file to SFTP Server

We can now upload an NACHA file to the SFTP server. To do so we must have an existing ACH file, if you’re curious about how to create an ACH file see creating an ACH file. fileType in the request body can be either NACHA or NACHA_PRENOTE (all amounts zero).

Upload NACHA to SFTP - POST /files/{fileId}/pushToSftp (API docs - Postman Collection):

{ 
  "fileType": "NACHA" 
}

Response:

{ 
  "sftpLogId": "9A5017036D07449CA7A4D2C9D195A242", 
  "profileId": "3CBD2ACD5D8044A88308CCF4A3C15FBF", 
  "odfiId": "1B531104DC764506965EA979D0C5E50F", 
  "fileId": "2922501E31DD4AD498D9B28DD7A32285", 
  "authType": "KEY_PAIR", 
  "fileType": "NACHA", 
  "username": "user1", 
  "host": "sftp.mybank.com", 
  "port": "22", 
  "directoryPath": "", 
  "responseTime": 3878, 
  "response": "Successfully uploaded file '20240304031529503_payroll.ach' to remote server", 
  "success": true, 
  "dateCreated": "2024-03-04 03:15:29" 
}

5. View SFTP Logs

All SFTP requests are saved for debugging purposes and can be queried by date.

Get SFTP Logs - GET /odfi/{odfiId}/sftpLogs (API docs - Postman Collection):

Response:

[ 
  { 
    "sftpLogId": "04E32EF2BD724D8888541F58EF9AA9A6", 
    "profileId": "3CBD2ACD5D8044A88308CCF4A3C15FBF", 
    "odfiId": "1B531104DC764506965EA979D0C5E50F", 
    "fileId": "2922501E31DD4AD498D9B28DD7A32285", 
    "authType": "KEY_PAIR", 
    "fileType": "NACHA", 
    "username": "user1", 
    "host": "sftp.mybank.com", 
    "port": "22", 
    "directoryPath": "", 
    "responseTime": 3697, 
    "response": "Failed to upload file to remote server", 
    "success": false, 
    "dateCreated": "2024-03-03 22:45:50" 
  }, 
  { 
    "sftpLogId": "313E5DF0FA134A66A8A185513A2F5266",
    "profileId": "3CBD2ACD5D8044A88308CCF4A3C15FBF", 
    "odfiId": "1B531104DC764506965EA979D0C5E50F", 
    "fileId": null, 
    "authType": "KEY_PAIR", 
    "fileType": "CONNECTION_TEST", 
    "username": "user1", 
    "host": "sftp.mybank.com", 
    "port": "22", 
    "directoryPath": "", 
    "responseTime": 3280, 
    "response": "Successfully connected to remote server", 
    "success": true, 
    "dateCreated": "2024-03-04 03:49:54" 
  }
]

Success! You uploaded an ACH file to your bank's SFTP server

Create an ACH file using Excel

Create an ACH file using QuickBooks

Create an ACH file using the API