Overview

ACH Auth Rules allow customers to control and customize the ACH payments that hit their Financial Accounts. Rules can be created for ACH Debit Receipts (pull payments) or ACH Credit Receipts (push payments), and created using any combination of the following:

Name of the company that originated the payment
Company ID of the originator
Amount of the ACH payment
SEC code of the ACH payment
Time of when the ACH payment is received
Memo passed through on the ACH payment

Multiple of the above attributes can be defined combined in a single rule. Rules can be set to apply to the customer's entire program, or select accounts within a program.

ACH Auth Rules Details

Some aspects to keep in mind when creating your ACH Auth Rules

Rules must be created as RETURN Auth Rules, or APPROVE Auth Rules, by explicitly setting the action.type.
1. RETURN Auth Rules must include a Return code. Customers must be approved by Lithic implementation for any return code they look to use.
All ACH Debit Receipts are returned by default to prevent unexpected debiting of funds. Customers should use ACH Auth Rules to "turn on" ACH Debit Receipts.
1. ACH Debit Receipts can be turned on for the entire program by using a program level rule, or selectively turned on for certain accounts/use cases by applying specific rule logic. See sample flow below.
Multiple rules can be activated by a single ACH payment, leading to the following situations:
1. If rules of type RETURN and APPROVE are both activated, Lithic will choose the strictest action and Return the payment.
2. If 2 RETURN rules are both activated with different Return codes, Lithic will apply the return code of the rule that was created most recently

Sample Flows

We'll go through 2 different sample API flows API flow for a customer looking to use ACH Auth Rules to receive and control ACH Debit Receipts for a digital banking + bill payment use case.

Flow 1: Selectively Approve ACH Debit Receipts

In the first flow, we'll keep ACH Debit Receipts turned off, and selectively approve specific billers per account.

Flow 1 Step 1 - Create rule for a specific biller using an account level rule

As ACH Debit Receipts are turned off by default, we'll need to create logic to allow an account to receive an ACH debit from a specific biller. In this case, the account token is 29c98870-1e7e-489c-b4c8-40d1cab0b6c3 and the originator ID is 5330903621

curl --request POST \
     --url https://sandbox.lithic.com/v2/auth_rules \
     --header 'Authorization: YOUR_API_KEY' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
       --data '
{
  "account_tokens": [
    "29c98870-1e7e-489c-b4c8-40d1cab0b6c3"
  ],
  "type": "CONDITIONAL_ACTION",
  "parameters": {
    "action": {
      "type": "APPROVE"
    },
    "conditions": [
      {
        "attribute": "COMPANY_ID",
        "operation": "IS_ONE_OF",
        "value": [
          "5330903621"
        ]
      }
    ]
  },
  "event_stream": "ACH_DEBIT_RECEIPT"
}
'

We'll get the following response:

{
  "token": "120b126f-9ad9-4c7f-a305-91fc30a4c210",
  "state": "INACTIVE",
  "program_level": false,
  "card_tokens": [],
  "excluded_card_tokens": [],
  "account_tokens": [
    "29c98870-1e7e-489c-b4c8-40d1cab0b6c3"
  ],
  "business_account_tokens": [],
  "type": "CONDITIONAL_ACTION",
  "current_version": null,
  "draft_version": {
    "version": 1,
    "parameters": {
      "action": {
        "type": "APPROVE"
      },
      "conditions": [
        {
          "attribute": "COMPANY_ID",
          "operation": "IS_ONE_OF",
          "value": [
            "5330903621"
          ]
        }
      ]
    }
  },
  "name": null,
  "event_stream": "ACH_DEBIT_RECEIPT",
  "lithic_managed": false
}

Note that the rule is created in a state of INACTIVE.

Flow 1 Step 2 - Rule Promotion

To activate it, we'll call the promote endpoint using the rule's token 120b126f-9ad9-4c7f-a305-91fc30a4c210

curl --request POST \
     --url https://sandbox.lithic.com/v2/auth_rules/120b126f-9ad9-4c7f-a305-91fc30a4c210/promote \
     --header 'Authorization: YOUR_API_KEY' \
     --header 'accept: application/json'

After calling the endpoint, we now see the rule has been made active, and payments will start returning if they come through from this COMPANY_ID

{
  "token": "120b126f-9ad9-4c7f-a305-91fc30a4c210",
  "state": "ACTIVE",
  "program_level": false,
  "card_tokens": [],
  "excluded_card_tokens": [],
  "account_tokens": [
    "29c98870-1e7e-489c-b4c8-40d1cab0b6c3"
  ],
  "business_account_tokens": [],
  "type": "CONDITIONAL_ACTION",
  "current_version": {
    "version": 1,
    "parameters": {
      "action": {
        "type": "APPROVE"
      },
      "conditions": [
        {
          "attribute": "COMPANY_ID",
          "operation": "IS_ONE_OF",
          "value": [
            "5330903621"
          ]
        }
      ]
    }
  },
  "draft_version": null,
  "name": null,
  "event_stream": "ACH_DEBIT_RECEIPT",
  "lithic_managed": false
}

ACH Auth Rules can be updated, deactivated, and managed just like Auth Rules for card events. See Auth Rules to learn more

Now we'll go through a second implementation for this use case.

Flow 2: Approve all Debit Receipts, and then selectively Return

Instead of selectively approving each biller, for this flow we'll approve all ACH Debit Receipts to start. And then create Stop Payments as needed

Flow 2 Step 1 - Create a program level rule to approve all ACH Debit Receipts

As ACH Debit Receipts are turned off by default, we'll need to create logic to allow all accounts in the program to receive ACH Debit Receipts. We'll do this with a program level rule, including an empty set of conditions to indicate it should apply to all ACH Debit Receipts:

curl --request POST \
     --url https://sandbox.lithic.com/v2/auth_rules \
     --header 'Authorization: YOUR_API_KEY' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "program_level": true,
  "type": "CONDITIONAL_ACTION",
  "parameters": {
    "action": {
      "type": "APPROVE"
    },
    "conditions": []
  },
  "event_stream": "ACH_DEBIT_RECEIPT"
}
'

We'll get the following response, again with the rule as INACTIVE

{
  "token": "249599db-48fc-4a79-8304-bdad6260f4b9",
  "state": "INACTIVE",
  "program_level": true,
  "card_tokens": [],
  "excluded_card_tokens": [],
  "account_tokens": [],
  "business_account_tokens": [],
  "type": "CONDITIONAL_ACTION",
  "current_version": null,
  "draft_version": {
    "version": 1,
    "parameters": {
      "action": {
        "type": "APPROVE"
      },
      "conditions": []
    }
  },
  "name": null,
  "event_stream": "ACH_DEBIT_RECEIPT",
  "lithic_managed": false
}

Flow 2 Step 2 - Promote the program level rule to activate it

Like in flow 1, we'll need to activate the rule by calling the Promote endpoint

curl --request POST \
     --url https://sandbox.lithic.com/v2/auth_rules/249599db-48fc-4a79-8304-bdad6260f4b9/promote \
     --header 'Authorization: YOUR_API_KEY' \
     --header 'accept: application/json'

Now the rule is ACTIVE, and all Debit Receipts will be approved to pull money out of customer accounts.

Flow 2 Step 3 - Create an Account Level Stop Payment

With all Debit Receipts being approved currently, we may then receive a Stop Payment request from an end user, indicating they no longer want to receive ACH Debits from a specific biller. We can use the same endpoint to create an Account Level Auth Rule, which will automatically return payments when they come in.

We'll use the same account token of29c98870-1e7e-489c-b4c8-40d1cab0b6c3 and an originator ID of 4830903615. This time, we must include a Lithic approved Return Code. We'll use R07, which indicates that the end user has revoked their authorization for this biller to debit their account

curl --request POST \
     --url https://sandbox.lithic.com/v2/auth_rules \
     --header 'Authorization: YOUR_API_KEY' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "account_tokens": [
    "29c98870-1e7e-489c-b4c8-40d1cab0b6c3"
  ],
  "type": "CONDITIONAL_ACTION",
  "parameters": {
    "action": {
      "type": "RETURN",
      "code": "R07"
    },
    "conditions": [
      {
        "attribute": "COMPANY_ID",
        "operation": "IS_ONE_OF",
        "value": [
          "4830903615"
        ]
      }
    ]
  },
  "event_stream": "ACH_DEBIT_RECEIPT"
}
'

We'll get the following response, with the rule as INACTIVE

{
  "token": "76a015a9-6e46-491e-b0a2-90581ab7cf4a",
  "state": "INACTIVE",
  "program_level": false,
  "card_tokens": [],
  "excluded_card_tokens": [],
  "account_tokens": [
    "29c98870-1e7e-489c-b4c8-40d1cab0b6c3"
  ],
  "business_account_tokens": [],
  "type": "CONDITIONAL_ACTION",
  "current_version": null,
  "draft_version": {
    "version": 1,
    "parameters": {
      "action": {
        "code": "R07",
        "type": "RETURN"
      },
      "conditions": [
        {
          "attribute": "COMPANY_ID",
          "operation": "IS_ONE_OF",
          "value": [
            "4830903615"
          ]
        }
      ]
    }
  },
  "name": null,
  "event_stream": "ACH_DEBIT_RECEIPT",
  "lithic_managed": false
}

Flow 2 Step 4 - Promote the program level rule to activate it

We'll activate the Account level rule by calling the Promote endpoint

```curl
curl --request POST \
     --url https://sandbox.lithic.com/v2/auth_rules/76a015a9-6e46-491e-b0a2-90581ab7cf4a/promote \
     --header 'Authorization: YOUR_API_KEY' \
     --header 'accept: application/json'
```

Now we've effectively blocked a single originator for the account, while still allowing other ACH Debit Receipts to be approved for the rest of the program.