PAD agreements

The PAD agreement object

A pad object is created and stored against a customers bank object, as an indication that the banking details have been verified and payments using these details have been authorized by the customer. A PAD agreement can be created and authorized through a range of payment tools, such as HelcimPay.js, the ACH Payment API, or within the Customer section of your Helcim account.

A PAD agreement stores a number of core payment details for the customers bank authorization, including:

• Details on which bank account and customer the PAD agreement is for.
• A range of date values indicating when the PAD agreement was created, accepted, revoked, updated, and when the earliest debit from the bank account can occur.
• The status of the PAD agreement, indicating whether it i spending, has been accepted, or has been revoked.

// Example PAD agreement object
{
  "pad": {
    "id": 66051,
    "accepted": 1,
    "bankAccountId": 53443,
    "customerId": 22745923,
    "dateAccepted": "2024-07-04 11:16:44",
    "dateCreated": "2024-07-04 11:16:44",
    "dateEarliestDebit": "2024-07-04 11:16:44",
    "dateRevoked": "0000-00-00 00:00:00",
    "dateUpdated": "2024-07-04 11:16:44",
    "ipAddress": "",
    "merchantId": 208967,
    "merchantAuthorized": 0,
    "type": 1,
    "status": 1
  }
}

Creating a PAD agreement for a customer

A PAD agreement is created automatically by the Helcim system when a customer provides their bank account details for processing. How the PAD agreement is created will determine how the customer can approve the AD agreement.

📘

Processing ACH Bank Payments

A PAD agreement is required in order to successfully process ACH bank payments.

ACH payments will remain in a pending status and not progress through settlement if processed against bank account details that have not been authorized by an approved PAD agreement.

Sending a PAD agreement to a customer

A PAD agreement will be sent to a customer, or can be approved by a customer, through the following methods.

• Using the Create bank account endpoint will trigger an email to the associated customer, if a valid billing address email exists in the customer object.
• Using the Request bank account information from a customer endpoint will trigger an email to the relevant customer to enter their banking information and approve a PAD agreement at the same time.
• Integrating with HelcimPay.js to capture banking information, using a "verify" payment type with a payment method of "ach", will allow the customer to enter their banking information and approve a PAD agreement at the same time.

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.

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