Secure Payments API – NACHA Transaction Batching

Secure Payments Transaction Batching

Keeping transactions organized, confirming that transactions are not double counted or missed, and having track-ability of each transaction is among the most pressing concerns for many lenders. To address these concerns, Secure Payments has developed a "Batch Process" which involves 4 basic steps. 

Transaction Batching Process

1. Create a Batch - The process will create a batch of all transactions for each NACHA payment processor that are in the "Pending" status and are not currently assigned to a batch. This will happen automatically each day at the specified cutoff time.
2. Assign a UUID - A universal unique identifier (UUID) or Batch ID will be assigned to each batch of transactions.
3. Transaction Status Update - The status of the transactions in the batch is changed from "pending" to "processing".
4. File Export - Depending on export file settings, create an output file for the batch in the selected format (CSV, NACHA) organized by batch ID. The option is also available to pull a batch through the API, which will return transaction information in a JSON format.

Create a Batch

Each batch of transactions is specific to a single Secure Payments, NACHA processor, meaning that even if an account is configured with multiple processors, batches will only contain transactions processed with a single NACHA processor. Secure Payments automatically creates a batch, each day, for the transactions for each NACHA processor that are in "pending" status and have not yet been added to a batch. This occurs at the specified cutoff time for that processor. Cutoff times are in UTC and are not updated to the user's time-zone, so you will need to set the correct UTC time.

Assign a UUID

The UUID assigned to a batch can be used to search for transactions in that batch (See the Secure Payments API - Get Batch List article, JSON Format - Secure Payments Transaction Search section). It is a unique identifier and is used in other calls to retrieve output files with batch transactions.

Transaction Status Update

Transactions are only included in a batch if they are in the "pending" status. When transactions are added to a batch, the status of those transactions changes from "pending" to "processing". Statuses may be further updated depending on the outcome of external processing.

File Export

The option is available to have Secure Payments automatically create a batch file containing the transactions assigned to the batch once the batch has been created. This file can be in either CSV or NACHA format. The file is created as a separate process after the batch process is related, so it won't hold up the batching in any way. For more information on downloading the file, see the Downloading the Batch File section.

Order of Operations

When the batching process occurs, things happen in the following order:

1. The batching process is initiated.
2. A check is done to see if there are any pending transactions for the NACHA processor. If there are no pending transactions, the process ends.
3. If there are pending transactions, a batch ID is generated and transactions are updated in the database. This includes recording the batch ID and updating the status of each transaction.
4. Elasticsearch (the service used to search transactions) is updated to reflect the database changes.
5. A check is done to make sure the number of transactions in the batch is the same in Elasticsearch and the database.
6. The NACHA batch generation event fires. This happens once for each 1000 transactions. This means that information about the process completion may be received multiple times. The payload associated with the event will have a header that contains the batch ID, so any programmed action should check the batch ID before action is taken.
7. The batch file is created, if the "Export type" setting is not set to "None".
8. The NACHA File Generation event fires.

How To

Create Batch

You can request that a batch be created in the Secure Payments user interface, or by sending a request to the following endpoint:

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

This will allow you to control when batches are created and how often. If the API is called to run the batch process, the daily batching won't occur that date but will be postponed until the next day. 

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

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

Batch Status

The batch process may include a large number of transactions, which can take some time. It is helpful to be able to query the status of the batch process to see whether it has finished. The endpoint to query the batch status is as follows:

GET https://securepayments.loanpro.io/api/nacha/batch-status/{uuid}

Make sure to replace {uuid} with the batch ID.

This endpoint will give a response that looks like the following:

{
  "uuid": "bd83d26a-93f1-46a8-8d6d-2927495f4a23",
  "created": "2019-11-06 18:04:12.0",
  "completed": "2019-11-06 18:04:22.0",
  "batch_status": "Completed",
  "transaction_count": 1
}

The batch status contains the following information:

• uuid - This is the unique ID of the batch.
• created - This is a timestamp of when the batch process was initiated.
• completed - This is a timestamp of when the batch process was completed.
• batch_status - This is the current status of the batch. The options include:
  • Processing - This means the batch process was started, but has not yet been completed.
  • Completed - This means the batch process has been completed.
  • Error - This means that there was an error, either with updating batch transactions.
• transaction_count - This is the number of transactions in the batch.

To see the batch status endpoint work, here are the steps to follow:

• Post a payment using a NACHA processor.
• Initiate the batch process.
• Look up the batch ID. (Optional)
• Request the batch status.

Post a Payment

This example will let you create a new payment using a NACHA processor:

Initiate the Batch Process

The following example will let you initiate the batch process for the NACHA processor used to process the payment in the example above:

Look Up the Batch ID (Optional)

You can look up the batch ID, if needed, to get the batch status. For our example, this should not be needed, since the batch ID should be returned quickly after the batch process is initiated. See this article for more information on looking up the batch ID.

Request the Batch Status

The example below will request the status of the batch created in the previous example, but you will need to change the {uuid} portion of the URL to the UUID received from the batch generation or search steps:

Downloading the Batch File

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 CSV or 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. 

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.

For more information on NACHA processing with LoanPro and Secure Payments see NACHA Process Start to Finish.

Transaction Issues

Sometimes there may be insufficient data for transactions that make it impossible to process them through NACHA. If information is missing, Secure Payments will detect it during the file-creation process. These transactions will be marked as failed in Secure Payments and in the output file. In order to see if there were failed transactions in a batch, it is best to query transactions once file-creation process has finished to look for transactions that are included in the batch and have a transaction status of failed. To do this, use the following query:

POST https://securepayments.loanpro.io/api/search/transaction?export=false

The payload should look something like this:

{ 
   "search":{ 
      "query":{ 
         "bool":{ 
            "must":[ 
               { 
                  "bool":{ 
                     "should":{ 
                        "query_string":{ 
                           "query":"*",
                           "fields":[ 
                              "customer_name",
                              "processor",
                              "metadata",
                              "status",
                              "batch",
                              "_id",
                              "id",
                              "amount"
                           ],
                           "default_operator":"AND"
                        }
                     }
                  }
               },
               { 
                  "match":{ 
                     "status":"FAILED"
                  }
               },
               { 
                  "match":{ 
                     "batch.keyword":"2405d10b-8433-4c18-b786-3895a850c0c7"
                  }
               }
            ]
         }
      },
      "aggregations":{ 
         "aggs":{ 
            "terms":{ 
               "field":"batch.keyword",
               "size":100
            }
         }
      },
      "size":10
   }
}

This should return only failed transactions from the batch. Make sure that the batch.keyword property matches the ID for the batch you are interested in.

The following example will let you try this: