​
Overview

The Manage Transactions section of the GrailPay ACH API allows you to programmatically interact with existing transactions after they have been created. These endpoints enable you to:
  • Retrieve a single transaction by UUID
  • Fetch a list of transactions with filter and pagination support
  • Cancel a transaction before it is processed
These capabilities are essential for building robust workflows around transaction monitoring, auditing, and exception handling. Whether you’re reconciling payments, reviewing transaction histories, or stopping a transaction before it settles, these endpoints provide the flexibility needed to manage ACH transactions effectively and securely.

​
Cancel a Transaction

In some cases, you may need to cancel a transaction before it processes — for example, if incorrect account information was submitted or the transfer is no longer needed. The GrailPay ACH API supports transaction cancellation as long as the transaction is still in a pending state. A transaction in a pending state means it has been created but has not yet begun the ACH transfer process. Once processing begins, cancellation is no longer possible, and the transaction will follow the standard settlement lifecycle. To cancel a transaction, you’ll need the unique uuid returned when the transaction was created. Using this identifier, you can call the Cancel Transaction endpoint to halt the transaction. If successful, the transaction will be marked with a CANCELED status, and no funds will be moved. This capability is especially useful during integration testing or when managing user-submitted transactions that may need to be reversed before funds leave the payor’s account. For full details on how to cancel a transaction, including request structure and response codes, refer to the Cancel a Transaction section in our OpenAPI documentation.

​
Fetch a Transaction by UUID

To monitor the lifecycle or audit the history of a specific transaction, the GrailPay ACH API provides an endpoint to retrieve a transaction by its UUID. This is a vital tool for gaining visibility into individual transactions as they move through the system. Fetching a transaction is particularly useful for:
  • Verifying the current status of a payment (e.g., pending, completed, failed)
  • Reviewing the full transaction payload for auditing or support purposes
  • Debugging issues related to funding, metadata, or reconciliation
To use this endpoint, supply the unique uuid that was returned when the transaction was created. A successful request will return a comprehensive response including the transaction’s state, amount, payer and payee information, associated payout (if applicable), timestamps, and any custom metadata. This functionality helps ensure transparency and control within your payment operations and provides a reliable method for integrating transaction monitoring into your systems. For detailed request/response formats and example payloads, refer to the Fetch Transaction by UUID section in our OpenAPI documentation.

​
List Transactions with Filters and Pagination

To manage ACH operations at scale, it’s often necessary to review and analyze a broad set of transactions across your organization. The List Transactions endpoint in the GrailPay ACH API allows you to efficiently retrieve a filtered, paginated view of transaction records tailored to your operational, reporting, or auditing needs. This endpoint is especially useful for:
  • Building dashboards that display real-time or historical transaction activity
  • Generating financial reports filtered by time period, transaction status, or account association
  • Investigating anomalies such as failed transactions, delayed payouts, or unusual volumes
  • Monitoring high-value or time-sensitive payments
You can apply a variety of filters to refine your results, including but not limited to:
  • Date ranges to target specific time periods
  • Payer / Payee UUIDs or Account UUIDs for user-specific transaction histories
The endpoint also supports pagination to make handling large datasets manageable and performant. You can navigate through result pages using standard parameters like page and per_page, and optionally sort results based on fields like created_at. Whether you’re overseeing daily payment operations, compiling audit logs, or integrating data into internal tools, this endpoint gives you the control and flexibility to access transaction data at scale. For full details on filters, sorting options, and request/response structures, refer to the List Transactions section of our OpenAPI documentation.

​
Questions?

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

​
Resources

Below you will find some helpful resources to assist with understanding how transactions work in GrailPay.