Withdraw an ACH payment

The Process Withdraw Transaction endpoint can be used to create a new ACH bank payment through the Helcim system. This endpoint will accept a combination of header and body parameters and return a response indicating the outcome of the transaction.

👍

Join our Beta for the ACH Payment API

Helcim is currently Beta testing our ACH Payment API that will replace the Process Withdraw Transaction endpoint and contain a more comprehensive range of API functionality to support your ACH payments.

If you would like to test this new API, then please connect with us at [email protected] to request Beta access.

Payment requests

The Process Withdraw Transaction endpoint will allow you to process a one time ACH bank payment.

The Withdraw API Reference outlines the required and optional body parameters needed for your request. The minimum required information in the body of your request must include a valid ipAddress where the payment is processed, the currency of the payment, the amount of the payment, in addition to a bankData object that contains either bank account details or a bankToken for previously tokenized banking details.

Review Process Withdraw Transaction API Reference

// Example ACH payment using valid bankToken
const options = {
  method: 'POST',
  headers: {
    accept: 'application/json',
    'idempotency-key': 't0sz0q3xwkfuiz6044bb3lxvh',
    'content-type': 'application/json',
    'api-token': 'YOUR_API_TOKEN'
  },
  body: JSON.stringify({
    bankData: {bankToken: '3f747d045aab557481cd1f'},
    ipAddress: '192.168.1.1',
    currency: 'CAD',
    amount: 100.99
  })
};

fetch('https://api.helcim.com/v2/payment/withdraw', options)
  .then(response => response.json())
  .then(response => console.log(response))
  .catch(err => console.error(err));

Potential payment responses

The Process Purchase Transaction endpoint will respond to all requests with either:

• An ach-transaction object with a type of "withdrawal", indicating the outcome of the payment.
• An error response indicating the reason for the error.

Potential payment outcomes

An ACH bank payment in the Helcim system can contain a range of statusAuth and statusClearing values to indicate the current status and outcome of the payment.

Approved payments

• Approved payment for valid authorized banking details.
• The payment will retain a statusClearing value of opened until the payment has gone through settlement with the customers bank.

{
  "transactionId": 117188,
  "batchId": 63530,
  "dateCreated": "2024-05-21 12:05:19",
  "statusAuth": "APPROVED",
  "statusClearing": "OPENED",
  "type": "WITHDRAWAL",
  "amount": 100.99,
  "currency": "CAD",
  "approvalCode": "570431120519",
  "bankAccountNumber": 23190563,
  "bankToken": "9cea3250ef156f976706d0",
  "invoiceNumber": "INV1290",
  "customerCode": "CST1008"
}

Pending payments

• Pending payment for unauthorized banking details.
• If a payment is attempted for banking details that are not authorized in the Helcim system, the payment will have a statusAuth of pending.
• The Helcim system will trigger an email to authorize the banking and the payment, so customer objects associated with these payments should contain a valid email in the billingAddress object.
• The payment will retain a statusAuth value of pending and a statusClearing value of opened until the banking is verified. The payment will not go through settlement with the customers bank.

{
  "transactionId": 117187,
  "batchId": 10,
  "dateCreated": "2024-05-21 12:03:08",
  "statusAuth": "PENDING",
  "statusClearing": "OPENED",
  "type": "WITHDRAWAL",
  "amount": 100.99,
  "currency": "CAD",
  "approvalCode": "",
  "bankAccountNumber": 12345678,
  "bankToken": "3f747d045aab557481cd1f",
  "invoiceNumber": "INV1289",
  "customerCode": "CST1033"
}

Declined payments

• The final outcome of an ACH bank payment is determined during the settlement process with the customers bank.
• An initial statusAuth of approved could be updated to declined based on this process, meaning that the payment was not successful and the payment would be shown as declined in the Payments section of your Helcim account.
• Reasons for a decline can vary from bank to bank for each unique payment. These typically include common responses such as insufficient funds, or incorrect banking details.

📘

Important Notes:

In order to process a Withdraw Transaction through the Helcim API:

• The merchant must ensure that the customer has accepted a preauthorized debit agreement and that those are stored and accessible for any disputes. Attempting to process a Withdraw Transaction without an approved and valid PAD agreement, will result in the customers bank rejecting the payment.