Skip to main content

​
Overview

The Manage Transactions section of the GrailPay Payments 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 filtering and pagination
  • Pause, resume, or cancel a transaction before it is fully settled
These capabilities are critical for building robust payment workflows. Whether you’re reconciling payments, reviewing transaction histories, intervening in suspicious activity, or responding to user-submitted errors, this suite of tools gives you the flexibility to safely manage ACH transactions.

​
Fetch a Transaction by UUID

This operation retrieves a specific transaction using its unique identifier. It is commonly used for:
  • Verifying the current status of a transaction
  • Reviewing transaction details for auditing or customer support
  • Debugging issues related to processing, metadata, or reconciliation
The response includes full details of the transaction, including payer and payee info, amount, processing status, timestamps, and associated payout data if applicable. Refer to the Fetch Transaction by UUID section in our API documentation for full request and response details.

​
List Transactions with Filters and Pagination

When managing a large volume of ACH activity, you may need to review a filtered set of transactions—whether for reporting, operational review, or anomaly detection. The API supports flexible filtering across attributes such as:
  • Date ranges (e.g., last 30 days)
  • Payer or payee identifiers
  • Account association
  • Transaction status (e.g., pending, paused, completed)
You can paginate through results and optionally sort by attributes like created_at. This functionality is commonly used to populate dashboards, generate audit logs, or feed data into internal tooling. Refer to the List Transactions section of our API documentation for query parameters and examples.

​
Cancel a Transaction

You may cancel a transaction if it is no longer valid or desired—such as in the case of incorrect bank details, suspected fraud, or a user-initiated reversal. In previous versions of the API, transactions could only be canceled prior to debit creation. In API v3, cancellations are supported up to the point when the payout (credit) is created, giving you greater control over timing and exception handling. There are three key cancellation paths:
  • Before the debit is created: The transaction is immediately canceled.
  • After the debit is created but before settlement: The transaction enters an AWAITING_CANCELLATION state. Once the debit settles, a Reverse Payout is automatically triggered, and the transaction is finalized as canceled.
  • After the debit has settled: A Reverse Payout is immediately triggered, and the transaction is canceled once the reversal completes.
When a transaction enters AWAITING_CANCELLATION, the TransactionAwaitingCancellation webhook is fired. Once cancellation is finalized, the TransactionCanceled webhook is sent.
Refer to the Cancel Transaction section in the API documentation for request and response formats.

​
Pause a Transaction

Pausing a transaction allows you to halt processing before the funds are moved. This is particularly useful in scenarios involving:
  • Fraud review queues
  • Manual approval workflows
  • Customer service hold scenarios
A paused transaction remains in the system but will not advance to processing until explicitly resumed. This can give internal teams time to review details or await additional information.
When a transaction is paused, the TransactionPaused webhook is emitted. Transactions that remain paused for more than 5 days are automatically canceled by the platform to prevent indefinite holds.
Refer to the Pause Transaction section in the API documentation for implementation details.

​
Resume a Transaction

Resuming a transaction that was previously paused returns it to the normal processing lifecycle. This is typically used after:
  • A manual review process has completed
  • A customer has confirmed transaction details
  • A fraud flag has been cleared
The transaction picks up from where it left off, continuing processing as if uninterrupted.
When a transaction is resumed, the TransactionResumed webhook is emitted.
Refer to the Resume Transaction section in the API documentation for more information.

​
Transaction Status Flow

The following table outlines how different actions affect transaction status and which webhooks are triggered:
ActionResulting StatusWebhook Emitted
PausePAUSEDTransactionPaused
ResumeResumes prior status (e.g., PENDING)TransactionResumed
Cancel (before debit)CANCELEDTransactionCanceled
Cancel (after debit, before settlement)AWAITING_CANCELLATION → CANCELEDTransactionAwaitingCancellation, then TransactionCanceled
Cancel (after debit settled)CANCELED (via Reverse Payout)TransactionCanceled

​
Timestamps & Auditing

The platform includes additional metadata to support traceability and compliance:
  • A canceled_at timestamp is recorded whenever a transaction is canceled
  • An ach_canceled_at timestamp is used to indicate ACH-level reversals
  • All transitions are available via the fetch endpoint for audit review

​
Error Handling

Transactions cannot be paused, resumed, or canceled if:
  • They are already in a terminal state (CANCELED, COMPLETED, FAILED)
  • The payout has already been created
  • They are already in the requested state (e.g., trying to pause an already paused transaction)
In these cases, the API will return a clear 403 or 404 response with a detailed error message to assist in troubleshooting.

​
Questions?

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

​
Resources