NACHA Process Start to Finish

Introduction

The NACHA process can be difficult to understand, but we're here to help. In this article, we'll explain the process from start to finish, and we'll fill you in on the details you need to know. We'll also explain how to use LoanPro's products to complete the process yourself. If you'd prefer to use the API to complete NACHA processes, we'll explain that, too.

The basic NACHA process is shown in the diagram below.

The NACHA Process

The process can be broken into a few main steps. Here's an overview of the steps of the NACHA process:

  1. New NACHA Transaction is Created
  2. Secure Payments Transaction Batching Process & File Output
  3. Customer Combines Batch File Data with Data from Any Other Sources & Converts Data to Bank's Preferred Format
  4. Submit Files to the Bank
  5. Re-Present Failed Payments if Allowed/It Is Your Policy
  6. Reverse Payments That Failed

We'll explain these steps in greater detail. Before that, let's talk about how Secure Payments handles the NACHA process. As our PCI-compliant product that handles payment processing, Secure Payments is an integral part to the NACHA process. The diagram below illustrates the Secure Payments payment process and possible outcomes. 

Before you can process NACHA payments, you will need to have NACHA processors created within your account. For information on setting up NACHA processors, see our NACHA Setup article. When NACHA files are generated, any special character names will be scrubbed out, and that includes processor names. The only accepted characters are 0-9 a-z A-Z - & , .

1. New NACHA Transaction Created

As you saw in the Secure Payments payment lifecycle diagram above, payments originate from LoanPro's Loan Management System (LMS). The payments are made via many different channels, including direct entered payments, AutoPays, payments posted via the Customer Portal, or the API. Secure Payments supports both debit and credit transactions as a means of pulling and pushing funds to your customer's bank account.

When a NACHA processor payment is logged, the transaction has a transaction status of "Pending" inside Secure Payments. All transactions begin in this status. 

You may be wondering about the timing of when the payment transaction is created. For the transaction to show up in a file to send to the bank, providing the instructions to the bank to pull or push funds to the customer's bank account the transaction must first exist. For more details on the payment application date, read our Payment Date Application article. 

Since payments are first logged in LoanPro before NACHA batches are created, the following things are important to keep in mind:

  1. Payments are made through the various payment channels: Customer Portal, AutoPay, Agent Logged, API
  2. Typically, these payments will apply the next business day, so they are logged into the system on the business day prior to their application date.
  3. The payment profile stored in Secure Payments will be associated with a payment in LoanPro, including the amount, payment profile token, processor, authorization type, and Secure Payments transaction ID.
  4. The payments will be given a “pending” status in Secure Payments.
  5. The payments will remain in a "pending" status until the batch process runs.
  6. When the batch process runs, it may output a file in either a JSON, CSV, or NACHA format. This is an important thing to note.
To select the output file type for each specific NACHA processor inside of your Secure Payments account, navigate to Processors > Bank Account/ACH (USA) > NACHA BATCH SUBMISSION > Add/Edit.

The output file type is specified by the "Export type" field.

Like we listed above, the options for export type are None, NACHA, and CSV. If "None" is selected, no export file will be generated or available for download. This option is mainly utilized by users who would like transactions to be assigned a batch ID, but also need transaction information to remain in a format other than the two options offered by default. Transaction data is usually obtained by querying transactions through the API to create a JSON file. In which case, the standard export file is not necessary.

API Examples

For an interactive example that illustrates how a new transaction with a NACHA processor is processed via the API, take a look at our ReadMe page.

The example below shows how to create an automatic payment using the LoanPro API.

2. Secure Payments Transaction Batching Process & File Output

When it comes to payments, accuracy is a necessity. Organizing transactions, confirming transactions are not double-counted or missed, and tracking transactions are the most pressing concerns for many lenders. To address these areas of concern, Secure Payments has developed a "Batch Process" that, fundamentally, completes 3 steps: 

  1. Assign a UUID or Batch ID to the transaction.
  2. Update the transaction status from "pending" to "processing" status.
  3. Depending on export file settings, include the transaction in the desired output file format (JSON, CSV, NACHA) organized by batch ID.

All batches are completed by a Secure Payments processor; if an account is configured with multiple processors, there will be one batch per processor to both capture all of the transactions in the "pending" bucket and process them. This will result in one output file for each batch ID. 

Secure Payments automatically creates a batch of transactions for each NACHA processor. This process takes place each day at the specified cutoff time in UTC. You can request a batch to be created in the Secure Payments user interface like shown below.

Or, you can create a batch by sending a POST request to the Secure Payments endpoint:

POST https://securepayments.loanpro.io/api/nacha 

If you'd like to run more than one batch process per processor each day, you can send a request to the API to instruct Secure Payments to kick off the batching process. 

When this endpoint is called, batches for NACHA processors that have "Pending" status transactions will be created immediately. All transactions for the processor from the current day that have not been included in another batch will be included. If a transaction is added after a batch has been created, it will be included in the next batch process.

Also, note that only transactions that are in the "Pending" status are included; if a transaction was voided prior to batching, it will be omitted from the batching process.

When you send a POST request to generate a NACHA batch, Secure Payments will respond when the NACHA batch is completed. The response will look something like this:

{
"response": "Batch created successfully",
"uuid":"59899f74-b3b4-4b67-8376-55fcd70e2708"
}

The UUID is the ID of the batch that was created. If the Export Type of the processor that is creating the batch is set to CSV or NACHA, you can use this ID to download a NACHA-formatted file for the batch. The example below demonstrates this.

If the UUID you have generated belongs to a processor with an Export Type of "None", the example below will not work because no download file is available for that batch.
API Examples

Below is a link to an interactive example of how to generate a NACHA batch through the Secure Payments API.

Download NACHA or CSV File

Once a NACHA or CSV file is generated and completed, you can download it.

You an also download files via the API. To do so, send a GET request to the following URL:

GET https://securepayments.loanpro.io/api/nacha/report/{UUID}

The {UUID} portion of the endpoint should be replaced with a universal unique ID from a batch of NACHA transactions.

It is important to note that this endpoint returns a blob. In order to download the blob, you should convert it to a file first. This will include adding a responsetype of blob to the request, and choosing to download it. The fileSaver function can be used like shown below:

const contentDisposition = response?.headers[
"content-disposition"
]?.match(/filename=["<]([^"]+)[">]/);

if (contentDisposition?.length === 2) {
fileSaver(
data, //returned by Secure Payments
contentDisposition[1],
response.headers["content-type"]          
);
}

Using the fileSaver() function is not required, but you will need to convert the data type to a file in some way.

3. Customer Combines Batch File Data with Data from Any Other Sources & Converts Data to Bank's Preferred Format

At this stage, you will need to complete the process of creating a file that is formatted as required by the processing bank. This file can use transaction data from Secure Payments and data from any other sources. Make sure everything is correct, as it's your responsibility to create the file and ensure it's formatted correctly.

In the last section, the option to download a NACHA file based on a single batch was demonstrated. It's important to note that the format used in a NACHA file is not proprietary to Secure Payments. NACHA files can be created through your own programming, or using a third-party software application, like Treasury Software. Let's take a look at some ways in which you can pull transaction data to create a NACHA file.

Download NACHA File

To download a NACHA file, you will need the UUID (batch ID) similar to like we explained above. If you don't have the UUIDs for the batches for which you are generating files, you call pull the IDs from Secure Payments. The example below demonstrates how to do this.

While the request linked above is interactive on our ReadMe page, we recommend you try this with your own REST or HTTP client.

If you plan on using this method, make sure to select "None" for the NACHA processor "Export Type" (as noted earlier in the "New NACHA Transaction Created" section above).

You can pull transaction data from Secure Payments using the API or the user interface. The transaction search is useful because it lets you filter transactions by date, status, batch, and type. If you have a large number of transactions, this could really help you submit a more specific list of transactions. Using the API is the preferred method for users with large numbers of transactions.

This can be achieved by sending a POST request to the following endpoint:

 POST https://securepayments.loanpro.io/api/search/nacha_export

The payload will look something like this:

{  
"search":{
"query":{
"bool":{
"must":[
{
"bool":{
"should":{
"query_string":{
"query":"*", //keyword query
"fields":[
"_id",
"id",
"amount",
"customer_name",
"processor",
"metadata",
"batch"
],
"default_operator":"AND"
}
}
}
},
{
"match":{
"batch.keyword":"59899f74-b3b4-4b67-8376-55fcd70e2708" //Batch ID
}
}
]
}
},
"aggregations":{
"aggs":{
"terms":{
"field":"batch.keyword",
"size":100
}
}
},
"size":10
}
}

The search uses an Elasticsearch query object. Pay attention to that size parameter with a set value of 10. This is for pagination purposes, and it will result in a default of 10 transactions in the results.

Only 10,000 transactions can be returned per query. To understand how to get all transactions in a batch see the Secure Payments Pagination of API Transactions

The example below illustrates how to search for Secure Payments transactions.

Search LoanPro Transactions

If you desire, you can use LoanPro as the data source instead of Secure Payments to supply the transactions to format into the bank desired format. This will use the Secure Payments batching process and continue to assign a batch ID and manage the transaction status. When that occurs, a callback event from Secure Payments to your LoanPro account can occur (if configured), thereby updating the details of that payment transaction. 

You can search for payments by using the Payments Report endpoint. We won't go into the details here, but our API – Payment Report article will cover everything you'll need to search payments through the LoanPro API.

Lastly, you can also use a direct database SQL Query to acquire the same data from your LoanPro database account. 

Creating a NACHA File Outside Secure Payments

If you plan to create a NACHA file outside of Secure Payments, you can either choose to do the programming yourself or use a third-party application. If you do the programming yourself, check out the guidelines on NACHA formatting.

4. Submitting Your File to the Bank

Many banks use the standardized NACHA format, but not all do. You will need to discuss this with your bank to determine their desired file format. 

As far as transmission methods go, you may be able to submit a file to a secure server using SFTP (secure file transfer protocol). But this option is not always provided by banks. LoanPro and Secure Payments don't have any direct connections with any banks, so you will need to establish the relationship and accommodate the bank's requirements for receiving NACHA files.

5. Re-Present Failed Payments, If Applicable

Sometimes, NACHA transactions will fail. Re-presentment is an additional attempt to process a failed payment. The most common cause of failure stems from a bank account with insufficient funds to complete a transfer. When this happens, the bank will issue a file that shows the returned transactions and includes a return code (R-Code). This file from your bank can then be formatted and uploaded (as a CSV file) to change the status of the transactions it contains to "Failed" in Secure Payments.

Usually, the number of times a payment can be re-presented is governed by law; and re-presentment of payments is something you will be required to track on your own. It is also entirely your choice if you'd like to re-present failed payments at all. There may be several factors that affect this decision, such as your relationship with your bank.

Get a URL

The first step in the process of uploading the returns file is to get the URL where the file will be uploaded. The URL will originate from Amazon's simple storage service (S3), and it will contain parameters that authorize the upload. The URL will expire a few minutes from the time it is generated, so only generate the URL if you are planning to use it immediately.

The URL can be generated by sending a POST request to the following endpoint:

POST https://securepayments.loanpro.io/api/transactions/status-update-validate

The URL it returns will look something like this:

https://s3.amazonaws.com/easypay-import/prod/input/798/2019-07-15/import-source-transactions-1563210003608%28454787bb-9bf5-4e03-90bf-7807567bb4a5%29transactions_validate.csv?X-Amz-Security-Token=AgoJb3JpZ2luX2VjELH%2F%2F%2F%2F%2F%2F%2F%2F%2F%2FwEaCXVzLWVhc3QtMSJHMEUCIQC%2FvW7A2QQcp8bEj8fiddNO9YUs34RVwv%2FW%2F%2FGGHcoQugIgU3dIOmfrqPGgODcGwXzr2EGXjCcfkR57P%2B3g7jxYLb4q2gMIGRACGgwyMjMyNDQxMTgwNDciDO4MI06dm8ksnpsctCq3A%2FBqyEwGXcGgoKXOvUmHH1Ph8HN3cH2%2B%2B4oVUlX1TFqXKL%2FfSWm8vrqomfO%2Bqs1%2Bb%2FdiJ3WJYlRbg0Em2%2BgQGcKql5tZW1t8iwakII6ZwTaCLDKerAS2DLCfHC%2FWZ%2FTK7zylqv%2FTru8SF4ltc9Z9ruLOKSMsdWCqbCJ1bzkGgrrDaB1b4Dz%2F2tOQTR95PuxmQZcScB4BGCTDK2gZ0dcQIqplViHPTFlW1arzohiv8IdmgMsn982BIj2NB4qFSbz8YIktCbHvQZKO%2BNtH9PZh77DQbakuD9QWTLllUpQXOO1YUNptZq904KTD4NMVyvJl%2F%2F8UqwoQb1muqfCg9vTjtXbDmrXfZvLuY37bdBExHX0pPC%2BcrA%2F0MkeHH93a9AvN6uLk8vcltwjBvAiwjBFvhaPLZ%2F3NiAV5KIZCwNmAtiJDLrWTHckuVUwMIL1ZGYv0Q1l8qL1hiNvtPuOkqqI8MlSGNOMQxPwzskh2n8AvzuNbOshyifILdDh0poMaIFLmkLzz4Fm7NCSSPeVRJexn1wXe7EAtD5FsymsuokS1C7QtWcMywDF%2BeiBUzs67kPuLjYQxM%2BPkO0swt86y6QU6tAFuavuBxCBjSbozvdS%2F2QmGgg4IBcRG4jmKDdN9siYyVS%2Fy56ak2buQT753mWRt71uU1YjhyWGfor4xs4Q9btmcqN%2B9xm9a5l4BCaoR%2FsAdLM0vMRFOZWsXH4lAt8MCCBj5NpdN7lSk6KfbKqGavgQiXCylDY9243xRyiqlFbnjZN0Kdu6kPSJZQMQrwVvUqcCKyurq0AWy2wkfJMoLO35OuwAUfmABZJiIHr%2BdraLkwqCjv5E%3D&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20190715T170003Z&X-Amz-SignedHeaders=host&X-Amz-Expires=900&X-Amz-Credential=ASIATH6TC5AP6SGA4XIX%2F20190715%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Signature=352ab0952fe3e004a86ba46269e03e29be398a657ce661f44e7c9dbc16c9c10a

Upload A File

Once you have generated the upload URL, you will need to upload the file containing the information for the reversed payments. The file you upload needs to include the following headers:

  • id - the transaction IDs for transactions from Secure Payments
  • newStatus - new status being assigned to the transaction
  • nachaCode - the code that described why the transaction failed previously
  • comments - optional field where comments can be made

If you are creating a plain text file, it should look like the following example:

id,newStatus,nachaCode,comments
1642834,FAILED,R01,Insufficient Funds

If you are creating the file in a spreadsheet program, your file will be formatted like shown below:

A

B

C

D

1

id

newStatus

nachaCode

comments

2

1642834

FAILED

R01

Insufficient Funds

Once the file is successfully uploaded to the newly-generated upload URL, the file will be validated automatically. You can create a file you want to use, or you can download our template below.

Once the validation is complete, an email will be sent to the communication email from your Secure Payments profile that contains the results of the validation.

Import Returns

Once the returns file is uploaded and validated, you can import it into your Secure Payments account. To import the file, you will need the import ID, which is found in the response from the upload and validation. Here's an example of what a response should look like. Pay attention to the id parameter.

{
"report": "https://s3.amazonaws.com/easypay-import/prod/output/798/2019-02-05/transaction-update-verify-1549397629255.csv?X-Amz-Security-Token=FQoGZXIvYXdzEMX%2F%2F%2F%2F%2F%2F%2F%2F%2F%2FwEaDDkRdODMaNzxwq3dxCK3A%2FH37RbcdMXAeAIwp8exUcLAMFf3FHy22%2BL7vIyQ48RdQPNQh6c12VXbfmdMLLGvm5r112icnlwo69dehiK4XO6GKnqeVnF0Bdlo0PjX7XeP0%2BqiTW7zw%2BwFMbI2c%2BrHxU3Wp2rrTHFuroiUrfJsTZkAPAzHGYhBR%2F2rBB%2BCCFWWh%2FBBu%2Fb7HnP%2FgVI2stRo3bFPyofNNbSoB7wOM%2BSc%2FkWhn1D0SzKQAZSmJAkIT%2BnvpIUJXv8hj8l1pqx89Qvt9ny2pGZUmIzGxJZbQs7UkZFGpRZIpGUzGsV0Or%2B64AyrxAS3IrOi%2BQRvpBzPstGEk8ToMW%2BsE%2FH4u7%2Fp2nWFeflNfaCjuh57nK%2FSAwAWDR9rNQe0rDex5OAZnbdz28aifdd1s5CKjww92jUylf%2BV4jEHGg39KoK%2FK7K5z97xUfQDI7khklGvhhpCmeqLaF9QM1PlZV1tZcOVBt3jkOAiVz2XggGiAOv5NeUb3v3bRIhR4iP4z8MvaVexM%2F7JBKtaDc2G%2FYfSIra2jo394NG6SMvf%2FNAow1TkxUzNu18E8vcVn0l0VmibCXXip4om0nQgNVpQfUzai2co%2Fszn4gU%3D&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20190205T201349Z&X-Amz-SignedHeaders=host&X-Amz-Expires=900&X-Amz-Credential=ASIATH6TC5APTNBA32SZ%2F20190205%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Signature=4f11d263c7cae5c4f444f9573188a066e989cd8feafaeb3a6bc6ae982e1f9764",
"result": [
{
"id": "1642834",
"token": "Validation",
"message": "ok"
}
]
}

You can also find import IDs by sending a GET request to the following URL:

GET https://securepayments.loanpro.io/api/import/all

To import the file, send a GET request to the following URL:

GET https://securepayments.loanpro.io/api/nacha/status-update/{import-id}

The response from the endpoint will look something like the following:

[
{
"id": 2023,
"import_key": "",
"verify_key": "transaction-update-verify-1549385931896.csv",
"source_key": "",
"imported": false,
"verified": true,
"created": "2019-02-05 16:58:51",
"updated": "2019-02-05 16:58:51"
},
{
"id": 2024,
"import_key": "",
"verify_key": "transaction-update-verify-1549389951338.csv",
"source_key": "",
"imported": false,
"verified": true,
"created": "2019-02-05 18:05:51",
"updated": "2019-02-05 18:05:51"
},
{
"id": 2025,
"import_key": "",
"verify_key": "transaction-update-verify-1549397629255.csv",
"source_key": "",
"imported": false,
"verified": true,
"created": "2019-02-05 20:13:49",
"updated": "2019-02-05 20:13:49"
}
]

To complete the import, use an ID from this array of files in a POST request to the following endpoint:

POST https://securepayments.loanpro.io/api/transactions/status-update/{import-id}

Just remember to replace the {import-id} piece of the URL with one of the IDs from the response.

6. Reverse Payments That Failed

Finally, you will need to reverse the payments that failed. Reversing payments can be made via a simple PUT request, and our Secure Payments API – Update Transaction Status article explains how to do it. The article talks about the topic of changing the transaction status for all transactions and isn't NACHA specific, but it gives instruction on changing statuses through an API endpoint.

For an interactive example of how this kind of request works, take a look at the following link:

LoanPro Transaction Updates

LoanPro transactions can be updated automatically via Secure Payments. This requires that Secure Payments has the correct callback URLs for its events and specifically the Transaction Status Update event. When the update is sent to LoanPro, the message will be handled based on the R-Code. If you need a reference for a specific R-Code, take a look at our Automatic Payment Reversal and NACHA Returns articles. These articles will also help you configure LoanPro to correctly handle returned transactions.


How did we do?


Powered by HelpDocs (opens in a new tab)