ACH bank payments

How to process ACH payments

You can use the Process an ACH withdraw endpoint to process a new ACH payment against the bank account details for an existing customer in the Helcim system.

🚧

The Helcim system requires an approved merchant bank account to be linked for deposits in order to process ACH transactions through our system.

This restriction applies to both production accounts and developer test accounts. For more information on how to link a deposit account to your Helcim account, please review our support documentation here.

Failure to link a deposit bank account will result in the Process an ACH withdraw endpoint returning an error. All ACH payments should be voided after testing, however developer test accounts are set to hold all funding and ACH payments will not go through settlement.

If you do not have an existing customer and bank account to process against, the Helcim system will not create one through this endpoint. In these situations, we recommend using the Create customer endpoint to create your customer object, then using either the Create a bank account or the Request bank account information endpoints in order to create a Bank object for that customer.

Understanding ACH transaction responses

The following is an example of the JSON transaction object returned for an ACH transaction.

{
  "transaction": {
    "id": 109361,
    "merchantId": 208967,
    "orderId": 37281729,
    "dateCreated": "2024-04-17 12:03:11",
    "statusAuth": 5,
    "statusClearing": 0,
    "userId": 0,
    "batchId": 0,
    "bankAccountId": 41992,
    "bankAccountL4L4": 23190563,
    "transactionType": 1,
    "amount": 10,
    "currency": 1,
    "approvalCode": "",
    "test": 0,
    "acquirerTransactionId": "",
    "responseMessage": "",
    "payFacTransactionId": 0,
    "originalTransactionId": 0,
    "statusBatch": 1,
    "dateClosed": "0000-00-00 00:00:00"
  }
}

📘

Receiving an ACH transaction response does not indicate that the subsequent payment was successful.

This response only indicates that the request was received successfully and an ACH transaction was created in the Helcim system.

The outcome of an ACH transaction is finalized during the settlement process with the customers bank and may change statuses throughout this process. The statusAuth and statusClearing properties can be used to determine the current status of an ACH transaction and whether it has completed settlement.

The id value returned in the response can be stored in your system and used to pull the transaction through the Retrieve a single ACH transaction endpoint to check on the current status or outcome of an ACH transaction.

Which currency should you process ACH payments with?

The Helcim system does not allow cross border ACH payments. The customer for the originating ACH transaction should reside in the same country as you. The currency passed as the currencyId value in your requests, should match the core currency of your Helcim account.

Canadian based merchants should pass 1 for CAD and US based merchants should pass 2 for USD. Attempting to process on the incorrect currency will return an error response Invalid payload: bank account country is invalid.

How to retrieve ACH transactions

After processing a new successful ACH payment for a customer, through the Process an ACH withdraw endpoint, a transaction response object will be returned to the point of the original request.

You can use the Collect all ACH transactions endpoint or the Retrieve a single ACH transaction endpoint with a valid ACH transaction id, in order to pull ACH Transaction details from the Helcim system at a later time.

How to refund, void, or vancel ACH transactions

Deciding whether to refund, void, or cancel an ACH transaction should be based on the current status of the payment and the ACH batch that it is included in. The statusBatch and statusAuth values are properties of an ACH transaction object.

An ACH transaction that has a statusAuth value of 2 or 4, was declined or has already been cancelled, meaning that it cannot be refunded, voided, or cancelled.

Refund

• If statusBatch = 2 and statusAuth = 1, then you should refund the transaction through the Refund an ACH transaction endpoint.

This endpoint will refund an approved ACH transaction that is in a closed ACH batch. It will create a new ACH Refund transaction object, that will go through settlement with the customers bank to refund an amount to the customer.

An ACH refund can be for an amount equal to or less than the original transaction amount and will be returned to the bank account used to process the original transaction.

Void

• If statusBatch = 1 and statusAuth = 1, then you should void the transaction through the Void an ACH transaction endpoint.

This endpoint will void an approved ACH transaction that is still in an open ACH batch. It will reverse the original transaction and amount and stops the transaction from going through settlement with the customers bank. This is recommended where possible, as you will avoid processing fees for the transaction by doing this.

Cancel

• If statusBatch = 1 and statusAuth = 5, then you should cancel the transaction through the Cancel a pending ACH transaction endpoint.

This endpoint will cancel a pending ACH transaction that is still in an open ACH batch. It will reverse the original transaction and amount and stops the transaction from going through settlement with the customers bank. This is recommended where possible, as you will avoid processing fees for the transaction by doing this.