Manage Bank Accounts

Overview

The GrailPay Payments 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 the value appears on every bank account record the API returns:

• 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 uuid. It supports date range filtering and pagination to help you tailor the results to your needs.

Note

This functionality is only available for accounts connected through our Bank Link SDK.

For full schema details, refer to

• Fetch Account Transaction History

---

Fetch Bank Account Owners

For accounts linked through the GrailPay Bank Link SDK, you can retrieve owner information directly from the user’s connected bank. This provides access to verified account holder details such as name, address, and contact information — useful for identity verification, compliance checks, and onboarding workflows.

This endpoint returns the owner information associated with a specific linked bank account using its uuid.

Note

This functionality is only available for accounts connected through our Bank Link SDK.

For full schema details, refer to

• Fetch Bank Account Owners

Delete Bank Account

You can delete a bank account associated with a person or business by referencing its 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.

Note

Bank accounts can only be deleted after a period of time has passed since the last transcation was settled, to account for potential returns eliciting clawbacks on the bank account. This time period is 30 days for business bank accounts, and 70 days for consumer bank accounts.

For full schema details, refer to

• Delete Bank Account

---

Fetch Bank Account

This endpoint allows you to retrieve detailed information about a specific bank account using its uuid. It’s helpful for auditing, troubleshooting, or displaying bank account metadata within your application.

For full schema details, refer to

• Fetch Bank Account

---

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.

Note

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

• Fetch Account Balance

---

List All Bank Accounts

This endpoint returns a list of bank accounts for the entities you have onboarded — people, businesses, and merchants. It supports pagination and is useful for building dashboards or reconciling linked accounts.

For full schema details, refer to

• List Bank Accounts

---

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

• Set Default Account

---

Testing

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

---

Questions?

If you’re encountering any issues, please reach out to support@grailpay.com.

---