​
Overview

The GrailPay ACH API offers several endpoints to help you manage bank account records linked to people and businesses. These tools allow you to retrieve account details, check balances, set defaults, delete unused accounts, and more. Each endpoint supports a distinct action and is designed to support common banking workflows such as updates, validations, account transitions, and reconciliation. This guide outlines each management action, what it does, and when to use it.

​
Aggregator Types

When working with bank accounts, you may encounter different aggregator_type values. These indicate how the bank account was added and can affect available features. There are currently three supported types and they are used throughout many of the bank account management endpoints:
  • plaid: Indicates the account was added via the GrailPay API using Plaid as the data aggregator.
  • manual: Indicates the account was added via the GrailPay API using manual entry of account and routing numbers.
  • bank_link: Indicates the account was added via the GrailPay Bank Link SDK.

​
Fetch Account Transaction History

For accounts linked through the GrailPay Bank Link SDK, you can retrieve transaction history directly from the user’s connected bank. This provides visibility into external activity such as deposits, withdrawals, and card payments — useful for risk assessment, reconciliation, and fraud monitoring. This endpoint returns a list of recent transactions for a specific linked bank account using its account_uuid and the aggregator type. It supports date range filtering and pagination to help you tailor the results to your needs.
This functionality is only available for accounts connected through our Bank Link SDK.

​
Delete Bank Account

You can delete a bank account associated with a person or business by referencing the aggregator_type used and the account_uuid. This is typically used to remove old or unused bank accounts that should no longer be involved in transactions.
Deletion is permanent and should be used only after ensuring the account is no longer in use.
For full schema details, refer to

​
Fetch Bank Account

This endpoint allows you to retrieve detailed information about a specific bank account using the account_uuid. It’s helpful for auditing, troubleshooting, or displaying bank account metadata within your application. For full schema details, refer to

​
Fetch Account Balance

Use this endpoint to retrieve the current balance of a linked bank account. This is especially useful for validating available funds prior to initiating a transaction or for displaying account balances in your product UI.
Keep in mind that this balance check is only available to accounts connected through our Bank Link Widget. If attempted on an account added through the API ( manual_account ), we will respond with an error with a status code of 403.
For full schema details, refer to

​
List All Bank Accounts

This endpoint returns a list of all bank accounts associated with a specific user, whether that user is a person or business. It supports pagination and is useful for building dashboards or reconciling linked accounts. For full schema details, refer to

​
Fetch User by Bank Account

If you only have the account_uuid but need to identify the associated user, this endpoint allows you to retrieve the corresponding user_uuid. This can be useful for resolving ownership in systems where bank accounts may exist outside direct user context. For full schema details, refer to

​
Set Default Account

When users have multiple linked bank accounts, this endpoint allows you to mark one of them as the default for future transactions. This is useful for setting preferred disbursement or funding accounts for your users. For full schema details, refer to

​
Testing

For guidance on testing in Sandbox, see our Technical Overview guide.

​
Questions?

If you’re encountering any issues, contact your GrailPay integration support contact or open a support request via the portal.