APIs for ACH debit transactions

The ACH Debit API enable you to create, retrieve, cancel and reconcile ACH debit transactions.

Prerequisites:

• An active NACH Profile for the sponsor bank to which you want to submit the ACH Debit transaction. You can create NACH Profiles by contacting Support.

• A mandate in LotusPay. This can be an internal mandate (i.e. one that you originally created in LotusPay), or an imported external mandate (i.e. one that you originally created elsewhere and later imported into LotusPay).

Step 1. For each amount that you want to request on each mandate, you create ach_debit via a POST request using the POST ACH Debit Create API with the required arguments. LotusPay returns an ach_debit object. status is initially pending, and response_sequence_number is initially empty. You should store the id. The charge_date can be any date up to one year in advance. If charge_dateis not an NACH business day, LotusPay will automatically roll it forward to the next business day (except if its the last day of the month, in which case LotusPay will automatically roll it back to the previous business day). You can include any custom identifiers as key-value pairs in metadata. The cut-off time for creating transactions on an NACH business day varies by sponsor bank. You can cancel pending transactions up to this cut-off time using the POST ACH Debit Cancel API. If a mandate is cancelled for any reason, all of its pendingach_debit transactions are automatically and immediately cancelled too. LotusPay system will give a 'duplicate entry' error if you try to create an ACH debit with identical merchant, mandate, charge date, status, amount and creditor reference.

Step 2. Upon the date specified in charge_date, in the morning LotusPay submits each pending ach_debit provided that its mandate's status is active. The ach_debit's status transitions to submitted.

Step 3. Your sponsor bank reviews the transactions. If your sponsor bank conducts any validations, they may deny to submit certain transactions. For example, if the sponsor bank is validating frequency, and they have already observed one successful transaction in a mandate's frequency period, they may deny subsequent transaction requests on the same mandate in the same period. NPCI encourages banks to run such validations. Such transactions will be automatically marked as cancelled (usually in the evening, but sometimes earlier), and you can see the reason in the dashboard. All valid transactions are submitted to the NACH system. NB: LotusPay does not validate frequency.

Step 4. The NACH system processes each transaction with the destination bank of the respective mandate, and returns a status to your sponsor bank.

Step 5. In the evening, LotusPay updates each transaction. status transitions to confirmedor rejected or returned or extended, and response_sequence_number is populated with the transaction sequence number assigned by NPCI. LotusPay instantly informs you of the status by sending event POST requests to your webhook URL of type ach_debit.confirmed or ach_debit.rejected or ach_debit.returned or ach_debit.extended (containing the full ach_debit payload). You should update the status, response_sequence_number, response_code and response_description in your system. Click here to learn more about transaction failures and codes/descriptions. If required, rejected or returned transactions can be retried on the next business day. If you are not integrating the webhook, you can use the GET ACH Debit API to retrieve the details, or you can view details and export reports in the dashboard. Any objects with status of extended will usually reach a final status of confirmed or returned within one or two business days.

Step 6. LotusPay creates an ach_debit_collection for the aggregate amount of all confirmed transactions for a charge_date with each sponsor bank. This is the amount that the sponsor bank will pay into your bank account on the same day. You should check your bank statement to ensure that you receive this exact amount. You can use the GET ACH Debit Collection List API to detect new objects, and then use the GET ACH Debit Collection API to see the details of each new object. You can run custom search filters and export CSV reports from the dashboard ACH Debit list page e.g. all transactions for date_charge today. You can also export a CSV report from an individual ACH Debit Collection's page to see all the confirmed transactions in that particular ach_debit_collection.

Another useful endpoint is the GET ACH Debit List API. You can use this endpoint with a filter to see all the transactions for a particular customer or mandate.