ACH Auth Rules allow you to control which ACH payments are received by your Financial Accounts. You can create rules for ACH Debit Receipts (pull payments) or ACH Credit Receipts (push payments), with conditions based on: - Company name of the originator - Company ID of the originator - Transaction amount - SEC code - Timestamp of when the payment is received - Memo field You can combine multiple conditions in a single rule. Rules can apply to your entire program or to specific accounts. # Key Concepts **Default behavior:** All ACH Debit Receipts are returned by default. You must create `APPROVE` rules to accept them. This prevents unauthorized debits from debiting funds from your accounts. **Rule actions:** Every rule must specify an action type. Use `APPROVE` to accept matching payments, or `RETURN` to reject them. RETURN rules require a NACHA return code- your program must be approved for any return codes you plan to use. **Draft and promote workflow:** Rules are created in an `INACTIVE` state. You must call the promote endpoint to activate them. This allows you to review rule configurations before they affect live transactions on your program. **Rule precedence:** A single ACH payment can trigger multiple rules. If both `APPROVE` and `RETURN` rules match, Lithic applies the stricter action and returns the payment. # Sample Flows The examples below show two approaches for handling ACH Debit Receipts in a digital banking or bill payment use case. ## Flow 1: Selectively Approve ACH Debit Receipts This approach maintains the default program behavior of returning ACH Debit Receipts and approves specific billers per account. ### Step 1: Create an account-level approval rule Since ACH Debit Receipts are returned by default, you'll need to create a rule to allow a specific biller to debit a specific account. This example approves debits from originator ID `5330903621` for account `29c98870-1e7e-489c-b4c8-40d1cab0b6c3`: ```curl curl --request POST \ --url https://sandbox.lithic.com/v2/auth_rules \ --header 'Authorization: YOUR_API_KEY' \ --header 'Content-Type: application/json' \ --data '{\n "name": "Approve Electric Company debits",\n "account_tokens": ["29c98870-1e7e-489c-b4c8-40d1cab0b6c3"],\n "type": "CONDITIONAL_ACTION",\n "parameters": {\n "action": {\n "type": "APPROVE"\n },\n "conditions": [\n {\n "attribute": "COMPANY_ID",\n "operation": "IS_ONE_OF",\n "value": ["5330903621"]\n }\n ]\n },\n "event_stream": "ACH_DEBIT_RECEIPT"\n }' ``` The response includes the rule token and shows the rule in `INACTIVE` state with the configuration in `draft_version`: ```json {\n "token": "120b126f-9ad9-4c7f-a305-91fc30a4c210",\n "state": "INACTIVE",\n "program_level": false,\n "account_tokens": ["29c98870-1e7e-489c-b4c8-40d1cab0b6c3"],\n "type": "CONDITIONAL_ACTION",\n "current_version": null,\n "draft_version": {\n "version": 1,\n "parameters": {\n "action": {\n "type": "APPROVE"\n },\n "conditions": [\n {\n "attribute": "COMPANY_ID",\n "operation": "IS_ONE_OF",\n "value": ["5330903621"]\n }\n ]\n }\n },\n "name": "Approve Electric Company debits",\n "event_stream": "ACH_DEBIT_RECEIPT"\n} ``` ### Step 2: Promote the rule Activate the rule by calling the promote endpoint with the rule token `120b126f-9ad9-4c7f-a305-91fc30a4c210`: ```curl curl --request POST \ --url https://sandbox.lithic.com/v2/auth_rules/120b126f-9ad9-4c7f-a305-91fc30a4c210/promote \ --header 'Authorization: YOUR_API_KEY' ``` The rule is now `ACTIVE`. The configuration moves from `draft_version` to `current_version`, and incoming payments from this originator will be approved for the specified account. ## Flow 2: Approve All Debits, Then Selectively Return This approach approves all ACH Debit Receipts at the program level, then creates stop payments as needed. ### Step 1: Create a program-level approval rule Create a rule with empty conditions to approve all ACH Debit Receipts across the program: ```curl curl --request POST \ --url https://sandbox.lithic.com/v2/auth_rules \ --header 'Authorization: YOUR_API_KEY' \ --header 'Content-Type: application/json' \ --data '{\n "name": "Approve all ACH Debit Receipts",\n "program_level": true,\n "type": "CONDITIONAL_ACTION",\n "parameters": {\n "action": {\n "type": "APPROVE"\n },\n "conditions": []\n },\n "event_stream": "ACH_DEBIT_RECEIPT"\n }' ``` ACH Auth Rules perform their configured action when all rule conditions are satisfied. By configuring a rule with no rule conditions, all ACH Debits will inherently satisfy all conditions. ### Step 2: Promote the program-level rule Activate the rule using its token `249599db-48fc-4a79-8304-bdad6260f4b9`: ```curl curl --request POST \ --url https://sandbox.lithic.com/v2/auth_rules/249599db-48fc-4a79-8304-bdad6260f4b9/promote \ --header 'Authorization: YOUR_API_KEY' ``` All Debit Receipts will now be approved program-wide. ### Step 3: Create a stop payment When an end-user requests to stop payments from a specific originator, create an account-level RETURN rule. This example blocks originator `4830903615` for account `29c98870-1e7e-489c-b4c8-40d1cab0b6c3`, using return code `R07` to indicate the user has revoked authorization: ```curl curl --request POST \ --url https://sandbox.lithic.com/v2/auth_rules \ --header 'Authorization: YOUR_API_KEY' \ --header 'Content-Type: application/json' \ --data '{\n "name": "Stop payment - Gym membership",\n "account_tokens": ["29c98870-1e7e-489c-b4c8-40d1cab0b6c3"],\n "type": "CONDITIONAL_ACTION",\n "parameters": {\n "action": {\n "type": "RETURN",\n "code": "R07"\n },\n "conditions": [\n {\n "attribute": "COMPANY_ID",\n "operation": "IS_ONE_OF",\n "value": ["4830903615"]\n }\n ]\n },\n "event_stream": "ACH_DEBIT_RECEIPT"\n }' ``` ### Step 4: Promote the stop payment rule Activate the rule using its token `76a015a9-6e46-491e-b0a2-90581ab7cf4a`: ```curl curl --request POST \ --url https://sandbox.lithic.com/v2/auth_rules/76a015a9-6e46-491e-b0a2-90581ab7cf4a/promote \ --header 'Authorization: YOUR_API_KEY' ``` The account-level RETURN rule now overrides the program-level APPROVE rule for this specific originator. Payments from other billers continue to be approved.