ACH Processing

The OpenTransact API is able to connect to financial instutions that enable ACH processing, sometimes referred to as ACH Origination. This guide will walk you through integrating with the OpenTransact API for the purposes of connectiong to one of the integrated partners that supports processing ACH payments.

Integration Basics

• 1: Create a Profile
• 2: Add an Address to the Profile
• 3: Add an Account to the Profile
• 4: Ensure the account becomes active
• 5: Create a transaction
• 6: Monitor the Activity Stream for updates
• 7: Monitor the Activity Stream for Returns and NOCs

1: Create a Profile for the Entity you want to transact with

Whenever you want to transact with a Person or Organization, you will need to create a Profile for them within the OpenTransact API.

See the API Docs for Create Profile for more information on the required attributes and options for this request.

# cURL is most likely already installed on your machine
curl --request POST \
  --url https://api.opentransact.com/v1/profiles \
  --header 'Authorization: Basic {AUTH_TOKEN}' \
  --header 'Content-Type: application/vnd.api+json' \
  --data '{
	"data": {
		"type": "profiles",
		"attributes": {
			"owner": {
				"type": "people",
				"first-name": "First",
				"last-name": "User"
			},
			"metadata": {
			}
		},
		"relationships": {
			"application": {
				"data": {
					"id": "{APPLICATION_ID}",
					"type": "applications"
				}
			}
		}
	}
}'

2: Add an Address to the Profile (optional for ACH)

Once the profile is created you may want to add an address to the profile. Addresses are not required by default for ACH processing, but may be required by verification services, or the risk management requirements for your processing partner. Take the ID from the profile you created in the previous step and use it in the request below where you see {PROFILE_ID}.

See the API Docs for Create Address for more information on the required attributes and options for this request.

# cURL is most likely already installed on your machine
curl --request POST \
  --url https://api.opentransact.com/v1/addresses \
  --header 'Authorization: Basic {AUTH_TOKEN}' \
  --header 'Content-Type: application/vnd.api+json' \
  --data '{
            "data": {
              "type": "addresses",
              "attributes": {
                "street1": "111 PEACHTREE PLACE",
                "locality": "Atlanta",
                "region": "GA",
                "country": "US",
                "zipcode": "30345"
              },
              "relationships": {
                "owner": {
                  "data": {
                    "type": "profiles",
                    "id": "{PROFILE_ID}"
                  }
                }
              }
            }
          }

3: Add an Account to the Profile

The final bit of information required to make ACH transactions is adding an Account to the Profile. For ACH transactions youll need to send parameters for an Account of type BankAccount.

See the API Docs for Create Account for more information on the required attributes and options for this request.

Optionally, integrate our Javascript SDK, and Create a Client Token to let your users directly submit Account information to the OpenTransact API without sensitive data hitting your servers.

# Create an Account using cURL
curl --request POST \
  --url https://api.opentransact.com/v1/accounts \
  --header 'Authorization: Basic {AUTH_TOKEN}' \
  --header 'Content-Type: application/vnd.api+json' \
  --data '{
	"data": {
		"type": "accounts",
		"attributes": {
			"nickname": "Personal Checking Account",
			"details": {
				"type": "bank-accounts",
				"account-number": "300000991",
				"routing-number": "021000021",
				"account-holder-type": "personal",
				"account-category": "checking"
			}
		},
		"relationships": {
			"owner": {
				"data": {
					"type": "profiles",
					"id": "{PROFILE_ID}"
				}
			}
		}
	}
}'

4: Ensure the Account becomes active.

If your Application on OpenTransact is configured with a rule for activating Accounts, it will be run after the Account is created. This may involve checking a third party service or database to ensure the Account is valid. Once complete, the Account will be updated and either be in the active or invalid state. You can only create transactions with an Account in the active state.

Fetch the Account to check the status. See the API Docs for Show Account for more information.

# Fetch the Account to check the status
curl --request GET \
  --url https://api.opentransact.com/v1/accounts/{ACCOUNT_ID} \
  --header 'Authorization: Basic {AUTH_TOKEN}' \
  --header 'Content-Type: application/vnd.api+json'

5: Create a Transaction.

Once you have an active Account of type BankAccount on your profile you can now create ACH transactions with that Account. If you are sending money to the recipient you will want to set the transaction-type attribute to credit. If you want to receive funds from the account, you will set it to debit.

Use the Account ID and Profile ID from the previous steps where you see {ACCOUNT_ID} and {PROFILE_ID} in the request below.

See the API Docs for Create Transaction for more information on the required attributes and options for this request.

# Create a Transaction using cURL
curl --request POST \
  --url https://api.opentransact.com/v1/transactions \
  --header 'Authorization: Basic {AUTH_TOKEN}' \
  --header 'Content-Type: application/vnd.api+json' \
  --data '{
	"data": {
		"type": "transactions",
		"attributes": {
			"transaction-type": "debit",
			"amount": 12,
			"precision": 2,
			"currency": "USD",
			"memo": "First Transaction"
		},
		"relationships": {
			"account": {
				"data": {
					"id": "{ACCOUNT_ID}",
					"type": "accounts"
				}
			},
			"profile": {
				"data": {
					"id": "{PROFILE_ID}",
					"type": "profiles"
				}
			}
		}
	}
}'

6: Monitor the Activity Stream for updates to the transaction status.

Based on the payment provider you have chosen to connect or the bank where you are processing ACH transactions, the Transactions you create will be submitted for processing. When successful, they will move into the processed state and when unsuccesful, they will move into the processing_failed state.

See the API Docs for List Activities for more information.

# Fetch the Account to check the status
curl --request GET \
  --url 'https://api.opentransact.com/v1/activities?filter%5Bapplication-id%5D={APPLICATION_ID}' \
  --header 'Authorization: Basic {AUTH_TOKEN}'

7: Monitor the Activity Stream for Returns and NOCs.

Using the same or similar API call to Step 6, monitor the Activity stream for ACH Returns and ACH Notifications of Change. ACH transactions are never truly final. While the state of the Transaction will move to processed, this just means that the bank has received it and will process it. The transaction can still fail for a multitude of reasons, which you can read about in the list of ACH Return Codes. Additionally, when there are minor errors in the data submitted, banks may process the transaction if able, and then respond with a Notificaiton of Change (NOC), which will contain info for correcting the minor errors. For this reason you must continuously monitor the Activity stream for AchReturn and AchNotificationOfChange objects related to the Transactions you have processed. When an AchReturn occurs, the Transaction will in essence have been reversed by the bank/processor, when a NOC occurs, you must alter the information you have on file to correct the error. If you are vaulting account data in OpenTransact, rules can be configured to automatically resolve NOC errors.

See the API Docs for List Activities for more information.

Testing in Sandbox

ACH Test scenarios:

Successful Account Number

All transactions that don’t match one of the failure criteria below will trigger the system to return a successful result.

Bad Routing Number

Confirm that your application can handle a user entering a bad routing number. You can mitigate this issue by using our Banks endpoint to confirm user entry prior to creating an account.

Non USD transaction

All transactions on the ACH network are denominated in the US dollar. Confirm your application’s behavior either prevents non-USD payments entirely from being entered as debits or credits against bank accounts, or handle the specific error when it may occur.

Incorrect Precision

ACH transaction amounts must be denominated in dollar and cents only, so only a precision of 2 is supported for transactions you wish to process on the ACH network. Confirm the application’s behavior either prevents entry of transactions with a precision other than 2 or handles the error appropriately where it occurs.

Return Generating Account Numbers

ACH Transactions may be returned in the future due to a variety of reasons. You can simulate ACH returns via the MockACHGateway by entering transactions against accounts with the following info:

Routing Number: 021000021 Account Number: any valid account number starting with 4000 and ending in the 2 digit return code you wish to trigger.

Ex: 021000021 400087802 will generate a R02 Account Closed return.

Returns will be generated after the processing of a matching transaction.

Notification of Change Generating Account Numbers

ACH Transactions may trigger what is called a notification of change due to a variety of reasons. You can simulate ACH notification of change by entering transactions against accounts with the following info:

Routing Number: 021000021 Account Number: any valid account number starting with 5000 and ending in the 2 digit NOC code you wish to trigger.

Ex: 021000021 500087802 will generate a C02 Incorrect transit/routing number notification of change.

Notification of Changes will be generated after the processing of a matching transaction.

Application Test Checklist

Before deploying an integrated application to production, it's crucial to thoroughly test and prepare for various ACH processing scenarios. Comprehensive testing ensures that applications can handle real-world situations effectively and securely. While the checklist below outlines specific test cases, it's important to consider a wide range of scenarios that may occur during ACH transactions. By rigorously testing these scenarios, the reliability of integrated applicatios can be enhanced, user experience can be improved, and compliance can be maintained according to ACH network requirements. Let's review some key areas to focus on:

ACH Return Codes