This guide is intended for developers using the ACH Pro API
The ACH Pro API provides a full suite of endpoints for creating NACHA files, managing recipients, handling returns and notices of correction and much more.
You can view all of our API endpoints here, and we also have a Postman collection to help you get started using the API.
Prerequisites
An Ultimate + API plan in ACH Pro
Authentication
The API uses access tokens to authenticate requests. You exchange a long lived API key and secret for a short lived access token.
Step 1. Create an API Key
Log in to ACH Pro, click your name in the top left and click Settings.
Scroll to the bottom of the Account Settings page and click New API Key. You can then enter a name and click Create.
Be sure to copy your API secret since it won’t be available after this point!
Step 2. Retrieve an Access Token
Rather than sending your long lived API key and secret in every request, you exchange them for a short lived access token (expires in 60 minutes) and include the token in a header with each request: Authorization: Bearer {access_token}.
Retrieve an access token by sending an HTTP POST to https://api.ach-pro.com/v1/token with the JSON body below.
{
"key": "yourApiKey",
"secret": "yourApiSecret"
}
The response body will contain an access token, refresh token and unix timestamps in milliseconds for their expirations.
{
"access_token": "fn208fh2983fhoqfln2okjfn2b984fhb29iubfno2b09f8h",
"refresh_token": "g20g32nrgvfs0v8i23jbfowdjfbvw98ufb2kjfbofuvo203",
"access_expires": 1670776627005,
"refresh_expires": 1670809080000
}
Because this token only lasts 60 minutes, you should develop a process for caching and retrieving fresh access tokens when needed, either by sending your key and secret or using a refresh token.
NOTE: ACH Pro system maintenance and releases will invalidate existing tokens so you should retrieve a new token if you receive a 401 response from the other endpoints.
Step 3. Make Requests
Now that you have an access token, you can make a request.
If you’re following along using our Postman collection, successfully calling the Access Token endpoint will save the token for use in other requests.
If you’re not using Postman, add the following header to all of your requests:
Authorization: Bearer {access_token}
For the purposes of this tutorial, send an HTTP GET to https://api.ach-pro.com/v1/profile to confirm your access token is working. You will receive a 200 if your token is valid. If you receive a 401 make sure your token is valid and added to the appropriate header. More information about the Current Profile endpoint.
Step 4. (Optional but recommended) Refresh your Access Token
Note that in step 2, a refresh token was returned alongside the access token. Unlike access tokens that only last 60 minutes, refresh tokens last 12 hours, and provide you with a means of retrieving new access tokens without needing to send your API key and secret.
This step is optional. You can simply call /token from step 2 again using your key and secret if you prefer.
To refresh a token, send an HTTP POST to https://api.ach-pro.com/v1/token/refresh with the JSON body below.
{
"refresh_token": "yourRefreshToken"
}
The response body will contain the same fields as a /token call.
{
"access_token": "fn208fh2983fhoqfln2okjfn2b984fhb29iubfnolkjsdlkh",
"refresh_token": "g20g32nrgvfs0v8i23jbfowdjfbvw98ufb2kjfbofuvo203",
"access_expires": 1670778974005,
"refresh_expires": 1670809080000
}
Take note that access_token and access_expires have new values, while their refresh counterparts remain unchanged. Refresh tokens do not refresh themselves.
When a refresh token expires, you must call the /token endpoint from step 2 using your key and secret.
Success! You've created an API key and made an authenticated API request