This guide is intended for developers using the ACH Pro API
Prerequisites
An Ultimate + API plan in ACH Pro
Familiarity with the ACH Pro API (See Getting Started with the API for an introduction)
Overview
Two endpoints are needed to create a NACHA file in ACH Pro:
1) create an ACH file object and,
2) download a NACHA file.
The ACH file object is a JSON representation of a NACHA file with a few extra fields we use in ACH Pro. You can use objects that already exist in ACH Pro such as recipients or accounts by passing their respective IDs, or you can use one-off representations of objects without IDs (we call this “from scratch”).
For example, we could use an existing recipient like so:
"recipient": {
"recipientId": "02318E20F6E34A7EAF8D2EC1E32DD181"
}Or we could use one from scratch:
"recipient": {
"name": "Some Person",
"recipientType": "CONSUMER",
"uniqueIdentifier": "somepersonsid"
}After an ACH file has been created, you can then download a NACHA file and provide it to your bank for origination. The rest of this guide walks through an example scenario covering all the required steps.
Walkthrough
We’ll try to simulate the most common scenario for ACH file creation, which involves using pre-existing ACH Pro objects. You can do the same thing using objects from scratch (see Data Types for more info).
ODFI
Every ACH file needs to be configured for origination by a specific bank (aka ODFI). You can configure multiple ODFIs in ACH Pro but only one will be used per ACH file.
Let’s start by creating one. We’ll use the odfiId from the response later. To review the full type definition, see ODFI .
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"
}
Company
Now that we have an ODFI, we need to create an originating company, also known as an originator. Unless you’re originating ACH transactions on behalf of other companies (not a typical scenario), the originator will be your company.
Let’s create a new company to use as the originator in our file. You can optionally create accounts for the company by including them in the request body. To review the full type definition, see the Recipient reference.
Create company - POST /recipients (API Docs - Postman Collection):
{
"recipientType": "COMPANY",
"name": "My Originator",
"companyIdentification": "811234567",
"accounts": []
}
Response:
{
"recipientId": "0B5FEFF88AA64E7FB31176C7F6A883F1",
"profileId": "02318E20F6E34A7EAF8D2EC1E32DD181",
"recipientType": "COMPANY",
"name": "My Originator",
"companyIdentification": "811234567",
"uniqueIdentifier": null,
"accounts": [],
"notificationEmails": [],
"isValidAuthorizationCompany": false
}
Recipient and Account
Every ACH transaction includes the recipient’s name, account details and an amount. In ACH Pro, you can create a recipient with zero or more accounts.
Create recipient - POST /recipients (API Docs - Postman Collection):
{
"recipientType": "BUSINESS",
"name": "XYZ Company",
"uniqueIdentifier": "0001XYZ",
"accounts": [
{
"accountNumber": "101010101",
"routingNumber": "026009593",
"accountType": "CHECKING"
}
]
}
Response:
{
"recipientId": "0BD34A045AF54E648CDBA5F0D31E6017",
"profileId": "02318E20F6E34A7EAF8D2EC1E32DD181",
"recipientType": "BUSINESS",
"name": "XYZ Company",
"uniqueIdentifier": "0001XYZ",
"notificationEmails": [],
"isValidAuthorizationCompany": false,
"accounts": [
{
"accountId": "0F16E5710C2444D5894D2CF781E93D73",
"profileId": "02318E20F6E34A7EAF8D2EC1E32DD181",
"accountNumber": "101010101",
"routingNumber": "026009593",
"accountType": "CHECKING",
"nickname": null
}
]
}
Create ACH File
Now that we have all the prerequisite objects created in ACH Pro, we can create our ACH file.
This is a very simple ACH file with a single batch containing a single credit entry. If you want more information about the shape of the ACH file, see the ACH File reference.
Create ACH File - POST /files (API Docs - Postman Collection):
{
"name": "My ACH File",
"odfi": {
"odfiId": "04C39B4FA21E45A78E091E959B47CDCF"
},
"batches": [
{
"isBalanced": false,
"effectiveDate": "2024-02-26",
"secCode": "PPD",
"companyEntryDescription": "PAYROLL",
"companyRecipient": {
"recipientId": "0B5FEFF88AA64E7FB31176C7F6A883F1"
},
"entries": [
{
"amount": 1512.35,
"recipient": {
"recipientId": "0BD34A045AF54E648CDBA5F0D31E6017"
},
"account": {
"accountId": "0F16E5710C2444D5894D2CF781E93D73"
},
"entryType": "CREDIT"
}
],
"companyDiscretionaryData": null,
"companyDescriptiveDate": null
}
]
}
Response:
{
"historicalFileId": "159458ECED6A4796B3027E4370AEFB5B",
"name": "My ACH File",
"odfi": {
"odfiId": "04C39B4FA21E45A78E091E959B47CDCF",
"profileId": "02318E20F6E34A7EAF8D2EC1E32DD181",
"name": "Bank of America",
"routingNumber": "026009593",
"immediateOrigin": null,
"immediateOriginName": null,
"immediateDestination": null,
"immediateDestinationName": null,
"fileLineEndings": "UNIX"
},
"batches": [
{
"isBalanced": false,
"effectiveDate": "2024-02-26",
"secCode": "PPD",
"companyEntryDescription": "PAYROLL",
"profileId": "02318E20F6E34A7EAF8D2EC1E32DD181",
"companyDiscretionaryData": null,
"companyDescriptiveDate": null,
"companyRecipient": {
"recipientId": "",
"profileId": "02318E20F6E34A7EAF8D2EC1E32DD181",
"recipientType": "COMPANY",
"name": "My Originator",
"companyIdentification": "123456789"
},
"entries": [
{
"amount": 1512.35,
"recipient": {
"recipientId": "0BD34A045AF54E648CDBA5F0D31E6017",
"profileId": "02318E20F6E34A7EAF8D2EC1E32DD181",
"recipientType": "COMPANY",
"name": "XYZ Company",
"companyIdentifier": "123456789"
},
"account": {
"accountId": "0F16E5710C2444D5894D2CF781E93D73",
"recipientId": "0BD34A045AF54E648CDBA5F0D31E6017",
"profileId": "02318E20F6E34A7EAF8D2EC1E32DD181",
"accountNumber": "505050505",
"routingNumber": "026009593",
"accountType": "CHECKING"
},
"entryType": "CREDIT",
"profileId": "02318E20F6E34A7EAF8D2EC1E32DD181"
}
],
"totalCredits": 1512.35,
"totalCreditCount": 1,
"totalDebits": 0,
"totalDebitCount": 0,
"totalEntries": 1
}
],
"profileId": "02318E20F6E34A7EAF8D2EC1E32DD181",
"totalCredits": 1512.35,
"totalCreditCount": 1,
"totalDebits": 0,
"totalDebitCount": 0,
"totalEntries": 1
}
Download NACHA File
Now that you have created an ACH file, you can retrieve the NACHA version.
You can optionally retrieve the prenote version of a file (all amounts zero) by sending asPrenote: true in the request body. For this walkthrough, we’ll retrieve the normal version which includes the amounts we entered in the file.
Get NACHA text - POST /files/{fileId}/download (API Docs - Postman Collection):
{ "asPrenote": false }
Response:
{ "fileName": "My ACH file", "data": "101..." }
Success! You've created an ACH file with the API and downloaded a NACHA file