ACH Payment API

Overview

The ACH Payment API has a range of endpoints available for you to process, retrieve, refund, void, or cancel ACH transactions. This API can also be used to retrieve and settle your ACH batches in the Helcim system.

In addition to the endpoints available within the ACH Payment API, we also have a number of Customer API endpoints that can be used to create, retrieve and update banking details for your customers within the Helcim system.

The following documentation will provide more information on how to integrate with the ACH Payment API, as well as outline any nuances that you should be aware of for specific endpoints.

📘

Beta test the ACH Payment API

The ACH Payment API is currently in closed Beta. In order to integrate with and test this API on your developer test account or Helcim account, then please connect with [email protected] to request access.

Recommended Integration Flow

Processing ACH transactions through the ACH Payment API requires existing customer and bank account details in the Helcim system to process against, as well as a PAD agreement approved by the customer. The following is our recommended flow for processing an ACH transaction for a new customer:

1. Create customer object in the Helcim system.
2. Create a Bank account or Request bank account information from a customer.
3. Set customer bank account as default.
4. Process an ACH withdraw transaction.

For returning customers, where you have an existing customer and bankAccount object in the Helcim system, you can skip steps 1 through 3 and proceed straight to processing an ACH withdraw transaction against their existing banking details.

📘

If you would like to simplify your integration and ACH processing, we recommend utilizing HelcimPay to process ACH payments.

ACH transactions processed through HelcimPay will create a new customer and bankAccount object in the Helcim system, if one is not passed in the initialize request. You can learn more about integrating with HelcimPay here.

ACH Payment API Endpoints

The ACH Payment API endpoints allow you to process ACH payments, collect ACH transactions, and manage your ACH batches. To test requests to these endpoints you can use our API Reference section for the ACH Payment API here.

Select endpoints for this API require a unique 25 character alphanumeric idempotency-key for each request sent. To learn more about idempotency keys, you can review our documentation here.

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 Cancel 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.

How to Retrieve or Settle ACH Batches

Every successful ACH transaction is included in an ACH batch. The ACH transaction response will contain batchId, statusBatch and dateClosed values.

• The batchId value is the unique id for the ACH batch the transaction is included in.
• The statusBatch value indicates whether the batch is open or closed.
  • 1 = open
  • 2 = closed
• The dateClosed value indicates when your ACH batch was closed. The ACH batch closure process is automatic and begins daily at 5PM in your local time zone.

You can use the Collects all ACH batches endpoint to retrieve additional information about your ACH batches, including transaction amounts and quantities. This endpoint will return a JSON object with an array of batches.

// Example response from the Collects all ACH batches endpoint
{
  "batches": [
    {
      "batchId": 47339,
      "merchantId": 208967,
      "statusBatch": 2,
      "amountWithdrawals": 5,
      "countWithdrawals": 1,
      "amountDeposits": 0,
      "countDeposits": 0,
      "amountReversed": 5,
      "countReversed": 1,
      "amountRefunded": 0,
      "countRefunded": 0,
      "dateOpened": "2023-11-21 10:09:58",
      "dateClosed": "2024-04-16 16:15:37"
    }
  ]
}

You can use the Settle an ACH batch endpoint to settle an ACH batch before it's automatic closure time, by passing the respective batchId and an idempotency-key.

Customer API Endpoints

The Customer API contains endpoints that allow you to create, retrieve and modify Bank account objects, request banking information from your customers, or retrieve and modify PAD agreements. To test requests to these endpoints you can use our API Reference section for the Customer API here.

How to Create a Customer Bank Account

You can create a new Bank account object in the Helcim system using the Create a bank account endpoint. A bankAccount object is associated with a single customer object, but can have one of more related PAD agreements of varying states.

• Canadian merchants will need to provide the bankAccountNumber, bankFinancialNumber, and bankTransitNumber for a valid Canadian bank account used by the customer.
• US merchants will need to provide the bankAccountNumber and bankRouting number for a valid United States bank account used by the customer.
• The values passed in this request need to match the customers bank records exactly. Discrepancies in these values may result in the customers bank rejecting any attempted ACH transactions.

Before Using This Endpoint

You will need to have an existing customer object that you would like to associate the bank account with, by passing the relevant customerId in the path parameter of your request. The Customer API can be used to create, retrieve, or modify a customer object to be used in this request.

🚧

We require a valid email stored in the billingAddress object for the customer.

This email address is used by the Helcim system to send a bank authorization email to the customer on successful bank account creation.

Their approval of this authorizes transactions using these banking details and creates a valid approved pre-authorized debit agreement for the banking information.

Failure to obtain an approved authorization may result in your ACH transactions being declined by the customers bank.

Understanding Create a Customer Bank Account Responses

When a successful request is made to create a bankAccount object, the Helcim system will respond with a JSON object containing the id value for the object and a success message indicating the object was created and an authorization email was sent.

Full bankAccount details can be retrieved by sending a request to the Get customer bank account endpoint with the customerId and bank account id returned in this response.

{
  "bankAccount": {
    "id": 45367
  },
  "message": "Successfully created new bank account with ID #45367. A bank authorization email was also emailed to [email protected]."
}

Attempting to create a bankAccount object for a customer that does not have a valid email address on file will result in an error response. An email should be added using the Update customer endpoint.

{
  "message": "Customer email address on file () is invalid."
}

How to Request Bank Account Information From a Customer

As an alternative to the Create a bank account endpoint, the Request bank account information from a customer endpoint can be used to send a bank authorization email from the Helcim system to the billing email listed in the customer object.

The endpoint will respond with a success message, or an error if no email address is included in the customer object.

{
  "message": "A bank authorization email was emailed to [email protected]."
}

Adding New Banking Information

Where a customer object does not have existing bank account information, the authorization email will prompt the customer enter their banking information and approve a PAD agreement.

Saving the banking information will create a new bankAccount object and PAD agreement for the customer in question.

Because bankAccount objects created through this action are completed by the customer, you will not have a bank account id value returned to you. We recommend using the Get customer bank accounts endpoint to retrieve their banking information once you receive the email confirmation that the bank authorization was approved.

❗️

This process uses HelcimPay to tokenize the bank details. Does it return a response to the window object that could be captured via an event listener?

Adding Additional Banking Information

Allow your customers to update or add additional banking information to a customer object, in the event their banking details have changed. Through the authorization email, the customer can select the dropdown and then click the Add new bank option to enter and authorize new banking details.

Adding new banking information through this method will not set the new bankAccount object as the default for processing. This can be completed by calling the Set customer bank account as default endpoint and passing the relevant customerId and bankAccountId values.

Verifying Existing Banking Information

This endpoint can be used to verify existing banking information in the following circumstances.

• The customer in question has an existing bankAccount object on file with either no PAD agreement, a PAD agreement that has not been approved, or a PAD agreement that has been revoked.
• The customer did not receive the original bank authorization email triggered by the Create a bank account endpoint.

Verifying existing banking information through this process will create a new PAD agreement and authorize their banking information for processing payments.

How to Retrieve Customer Bank Accounts

The Customer API contains two endpoints that will allow you to retrieve bankAccount objects for a relevant customer in the Helcim system.

• Where the customerId and bankAccountId are known, you can call the Get customer bank account endpoint to retrieve the details of a specific bankAccount object associated to that customer.
• Where a customer may have multiple bank accounts or the bankAccountId is not known, you can call the Get customer bank accounts endpoint to retrieve an array of bankAccount objects associated to that customer.

These endpoints will return the bankAccount object, or an array of objects, with the information outlined in the example below.

{
  "id": 41992,
  "customerId": 19411033,
  "dateCreated": "2024-03-14 16:51:38",
  "dateUpdated": "0000-00-00 00:00:00",
  "dateLastUsed": "0000-00-00 00:00:00",
  "dateVerified": "0000-00-00 00:00:00",
  "bankToken": "3f747d045aab557481cd1f",
  "accountType": "CHECKING",
  "accountCorporate": "PERSONAL",
  "verified": 0,
  "ready": 0,
  "bankIdNumber": "123",
  "transitNumber": "12345",
  "routingNumber": "",
  "bankAccountNumberL4": "6789",
  "address": {
    "name": "Test Customer",
    "street1": "123 Test Street",
    "street2": "",
    "city": "Calgary",
    "province": "AB",
    "country": "CAN",
    "postalCode": "H0H 0H0",
    "phone": "",
    "email": ""
  }
}

How to Set a Customer Bank Account as the Default

Creating a new bankAccount object in the Helcim system does not automatically set that object as the default for processing. A default bank account is the account that would be shown as a priority, or processed on automatically, through other Helcim payment tools such as Pay Now Invoices or Subscriptions.

If you allow a customer to indicate they would like a bank account to be set as default in your system, then you can call the Set customer bank account as default endpoint to complete that corresponding action in the Helcim system.

How to Retrieve or Update Customer PAD Agreements

Through the Customer API you can retrieve or update a PAD agreement for bankAccount objects in the Helcim system. A single bank account could have one or more PAD agreements associated with it.

An approved PAD agreement is required in order to process ACH transactions against a customers bank account. If a PAD agreement does not exist for a bankAccount object, refer to the section on how to request bank account information from a customer to verify existing banking information in the Helcim system.

• The Get all PADS for a customer endpoint will return an array of all PAD agreements for all bankAccount objects associated with that customer object.
• The Get a PAD by its ID endpoint will return a single PAD agreement object for a specific customer and bank account.
• The Update a PAD by its ID endpoint can be used to update a PAD agreement for a specific bankAccount object to authorize processing on that account.

Understanding PAD Agreement Responses

The retrieve and update PAD agreement endpoints will respond with an object array of pad objects, or a single pad agreement object.

Each PAD agreement has an accepted property that indicates whether this specific agreement, for this specific bankAccountId, was authorized by the customer.

Each PAD agreement has a status property that indicates whether the this specific agreement, for a this specific bankAccountId, is currently active or inactive.

• A PAD agreement that has been accepted by the customer will be active and have an accepted value of 1 and a status value of 1.
• A PAD agreement that has not been accepted by the customer will be inactive and have an accepted value of 0 and a status value of 2.
• A PAD agreement that was accepted, but was then later revoked or cancelled, will be inactive and have an accepted value of 1 and a status value of 2.

    {
      "id": 53735,
      "accepted": 0,
      "bankAccountId": 41992,
      "customerId": 19411033,
      "dateAccepted": "0000-00-00 00:00:00",
      "dateCreated": "2024-03-14 16:51:40",
      "dateEarliestDebit": "0000-00-00 00:00:00",
      "dateRevoked": "0000-00-00 00:00:00",
      "dateUpdated": "2024-03-14 16:57:19",
      "ipAddress": "",
      "merchantId": 208967,
      "merchantAuthorized": 0,
      "type": 2,
      "status": 2
    }

📘

In order to process ACH transactions against a bank account successfully, there must be an accepted PAD agreement with an active status.