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 validemail
in thebillingAddress
object. - The payment will retain a
statusAuth
value of pending and astatusClearing
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.
Updated 4 months ago