NACHA Process Start to Finish

General

The NACHA process can be difficult to understand. The basic process is shown in the diagram below.

Here are the steps in the NACHA process:

  1. New NACHA transaction created
  2. Secure Payments (formerly PCI Wallet) 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 the File to the Bank
  5. Re-Present Failed Payments If Allowed/It Is Your Policy
  6. Reverse Payments That Failed

The purpose of this article is to explain and illustrate each of these steps as they occur in LoanPro and Secure Payments. The diagram below illustrates the Secure Payments payment process and possible outcomes. 

Note: 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 the  NACHA Setup article. When NACHA files are generated, any special character names will be scrubbed out, this includes processor names. Accepted character are 0-9 a-z A-Z - & , .

New NACHA Transaction Created

As shown in the Secure Payments payment lifecycle diagram, payments originate from LoanPro Software from many channels which can include direct entered payments, autopays, payments posted via the Customer Portal, or API. Secure Payments support both Debit & Credit type transactions meaning pulling funds from your customer's bank account and pushing funds to their 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. 

A common question that Customers have is the timing of when the payment transaction is created. In order to have the transaction show up in a file to send to the bank, thus providing the instructions to the bank to pull or push funds with the Customer's bank account the transaction must first exist. For more details on the payment application date, read this article

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

  1. Payment Channels:  Customer PortalAutoPayAgent LoggedAPI
  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, which includes the amount, payment profile token, processor, authorization type, and Secure Payments Transaction ID.
  4. Payment will be put in “pending” status in Secure Payments.
  5. Payments will remain in "pending" status until the batch process runs.
  6. When the batch process runs it may output a file format which includes: JSON, CSV, NACHA format. 

Note: You may select the output file type for each specific NACHA processor inside of your Secure Payments account in Processors > Bank Account/ACH (USA) > NACHA BATCH SUBMISSION > Add/Edit.

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

The options for export type are None, NACHA, and CSV. If "None" is selected, then no export file will be generated or available for download. This option is mainly utilized by companies who would still like transactions to be assigned a batch ID, but also need transaction information 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.

The following example has been included to illustrate how a new transaction with a NACHA processor is processed, using the API. There are examples later in the article that show how to run a batch process which will assign a batch ID to each transaction in a processor depending on the existence of at least one transaction. Be sure to click  in the example below, if you want to try the other examples.

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

Secure Payments Transaction Batching Process & File Output

Keeping track of transactions in an organized manner, confirming that transactions are not double counted or missed, and having trackability of each transaction is among the most pressing concerns for many lenders. To address these areas of concern Secure Payments has developed a "Batch Process" which fundamentally does 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, includes the transaction in the desired output file format (JSON, CSV, NACHA) organized by batch ID.

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

Secure Payments automatically creates a batch for the transactions for each  NACHA processor at the cutoff time specified for that 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, or by sending a 

POST request to Secure Payments https://pciwallet.simnang.com/api/nacha 

API endpoint (Explained in the section "Secure Payments Transaction Batching Process & File Output" below). If a client wishes to run more than one batch process per processor each day then they may call the API to instruct Secure Payments to kick off the batching process. 

Note: When this endpoint is called, NACHA 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, after a batch has been created, then a transaction is added after the batch process, it will be included in the next batch process. Also, note that only transactions that are in the "Pending" status are included, this means that if a transaction was voided prior to batching, it will be omitted from the batching process.

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

When you POST a 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 for which the batch is being created 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. In order to make the example work, you will need to enter a UUID in the UUID field before clicking SEND. It is best to copy and paste the UUID received in the previous step. You can also use the one above, but it may be expired. 

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

If you receive a response from the Secure Payments callback about the file generation, it will look something like this:

"{\"user_id\":798,\"batch_uuid\":\"7934f6ba-011b-48e8-8f03-200ec52e542f\",\"transactions\":[{\"id\":1984806,\"metadata\":\"{\\\"tenantId\\\":\\\"5200243\\\",\\\"accountId\\\":\\\"LOAN597f93726b19f\\\",\\\"paymentId\\\":\\\"4443\\\"}\"}]}"

This is a JSON string and can be converted to JSON and parsed for easier use.

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

At this stage, the customer will do the work 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. It is your responsibility to create the file and ensure it is formatted correctly.

File Output Option - NACHA-Formatted File

In the last section, the option to download a NACHA file based on a single batch was demonstrated. It is 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 get transaction data in order to create a NACHA file.

Download NACHA File

To download a NACHA file, you will need the UUID (batch ID) as shown above. The example above illustrates how to download a NACHA-formatted file from PCI Wallet. 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.

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. Pulling transactions through the API is the preferred method for most large clients. This can be done using the /search/transaction endpoint. 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. Note that the "size" parameter is set to 10. This is for pagination and will result in a default of 10 transactions in the results.

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

Note: If you are 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).

Search LoanPro Transactions

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

Search for payments using the Payments Report endpoint. The article here will cover searching for payments using the LoanPro API.

You may also do a direct database SQL Query to acquire this date from your LoanPro database account. 

Creating a NACHA File Outside PCI Wallet

If you plan to create a NACHA file outside of Secure Payments, you can 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. If you plan to use a third-party application, work with that company to understand their application and how to add transactions to a NACHA-formatted file.

Submitting Your File to the Bank

Many banks use the standardized NACHA format. Others do not. You will need to discuss with your bank their desired file format. 

Transmission Method - Depending on your bank, you may be able to submit a file to a secure server using SFTP (secure file transfer protocol). 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.

Re-Present Failed Payments If Allowed/It Is Your Policy

Re-presentment is an additional attempt to process a failed payment. Usually, the number of times a payment can be re-presented is governed by law. Re-presentment of payments is something you will be required to track on your own.

Reverse Payments That Failed

There is an article that is dedicated to this process here. This 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, which may be desired.

Upload & Validate Returns File

Sometimes, NACHA transactions will fail. This is most often because a bank account has 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 can be formatted then uploaded to change the status of the transactions it contains to "Failed" in Secure Payments. The file should be in comma-separated values (CSV) format.

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 be to Amazon's simple storage service (S3) within the Simnang account. The URL 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 endpoint: https://pciwallet.simnang.com/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

The example below demonstrates how to generate a URL:

Upload A File

Once you have generated the upload URL, you will need to upload the file containing information for the reversed payments. The file you upload needs the headers "id", "newStatus", "nachaCode", and "comments". The rows beneath should contain transaction IDs for transactions from Secure Payments, the new status being assigned to the transaction, and codes for why each transaction failed. The "comments" field is optional for each transaction. If you are creating a plain text file, it should look like this:

id,newStatus,nachaCode,comments

1642834,FAILED,R01,Insufficient Funds

If you are creating the file in a spreadsheet program, it should look like this:

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.

The example below demonstrates the upload. In order for the example to work, you must upload a correctly formatted file. You can create a file you want to use, or you can use this one.

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 using the ID. The ID is contained in the response from the upload and validation. The response should look something like this:

{
"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"
}
]
}

To import the file, use the

/nacha/status-update/{import-id}

The import-id is the ID assigned to the uploaded file by Secure Payments. These IDs can be found by sending a GET request to the

/api/import/all

endpoint. The example below demonstrates this.

The response from the endpoint will look something like this:

[
{
"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"
}
]

Use an ID from this array of files in order to complete the import using the

nacha/status-update/{import-id}

endpoint. Replace the {import-id} piece of the URL with one of the IDs from the response. The final URL will look something like this:

nacha/status-update/2025.

The example below demonstrates how to do this. Remember to replace the {import-id} piece of the URL with a valid file ID.

Note: For more information on how to update transaction statuses through the API, see Secure Payments API Update Transaction Status.

LoanPro Transaction Updates

LoanPro transactions can be automatically updated by Secure Payments. This will require that Secure Payments has the correct callback URLs for its events, specifically the Transaction Status Update event. When the update is sent to LoanPro, the message will be handled based on the R-Code. The Automatic Payment Reversal and NACHA Returns articles will help you configure LoanPro to correctly handle returned transactions.


How did we do?


Powered by HelpDocs (opens in a new tab)