Manage Transactions

​

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
• Search returns — transactions or payouts that failed in the ACH network
• Review clawbacks that recover funds after a return following a payout
• 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

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.

---

​

List Returns

A return is any transaction or payout that failed after entering the ACH network—for example, a debit that was returned for insufficient funds (R01) or a payout that could not be credited to the receiving account. The Search Returns endpoint provides a single, paginated view of these failures across both legs of a transfer:

• Capture leg (capture) — the debit (transaction) leg was returned.
• Payout leg (payout) — the credit (payout) leg was returned.

When the filter[leg] parameter is omitted, both capture and payout returns are included. Each return record links back to its related objects—the transaction, payout, clawback, and reverse_payout where applicable—along with the entity, payor, and payee involved, so you can reconcile a failure without additional lookups. This functionality is commonly used to:

• Build return and exception dashboards or daily reconciliation reports
• Trigger retry or customer-outreach workflows based on the ACH return code
• Investigate a specific failure by transaction, payout, entity, or trace ID

The endpoint supports flexible filtering across attributes such as:

• Leg — capture or payout
• ACH return code — a single code (filter[ach_return_code]) or several comma-separated codes (filter[ach_return_codes])
• Amount — in cents, with dynamic operators (e.g., filter[amount]=>10000, filter[amount]=<=50000)
• Related object UUIDs — transaction, payout, clawback, reverse payout, or entity (payor/payee)
• Date range — filter[start_date] and filter[end_date], matched against the ACH failure date (YYYY-MM-DD)
• Identifiers — bank ID, ACH trace ID, and (for processors) vendor ID

You can sort by ach_failed_at or amount—prefix the field with - for descending order—and paginate with page and per_page. Refer to the Get All Returns section in the API documentation for the full list of query parameters and the response schema.

---

​

Clawbacks

A clawback is triggered automatically when an ACH return occurs after a payout has already been sent—the return reverses the funds back to the payer, and the clawback debits the payee to offset the difference. Clawbacks move through their own lifecycle (CLAWBACK_PENDING → CLAWBACK_ACH_PENDING → CLAWBACK_COMPLETE, with CLAWBACK_ACH_FAILED and CLAWBACK_CANCELLED as terminal exceptions). See Clawback in Transaction States for the full status reference and the webhook that accompanies each step. The following read-only endpoints let you list clawbacks and retrieve a single clawback for reporting, reconciliation, and support workflows. Each clawback record includes its status, amount (in cents), clawback_type (transaction or vendor_fee), the payee being debited, the originating ach_return_code, and identity pointers back to the related transaction and payout.

​

List Clawbacks

Returns a paginated list of clawbacks visible to the authenticated user. Supported filters include:

• Status — filter[status] (e.g., CLAWBACK_PENDING, CLAWBACK_ACH_FAILED, CLAWBACK_COMPLETE)
• Amount — in cents, with dynamic operators (e.g., filter[amount]=>100, filter[amount]=<=500)
• Related object UUIDs — parent transaction (filter[transaction_uuid]), merchant (filter[merchant_uuid]), or payee (filter[payee_uuid])
• Identifiers — clawback UUID (filter[uuid]), ACH trace ID (filter[ach_id]), and client reference ID (filter[client_reference_id], partial match)
• Date range — filter[start_date] and filter[end_date], matched against the clawback creation date (YYYY-MM-DD)

You can sort by created_at or amount—prefix the field with - for descending order—and paginate with page and per_page. Refer to the Get All Clawbacks section in the API documentation for the full list of query parameters and the response schema.

​

Fetch Clawback by UUID

Retrieves the details of a single clawback, along with identity pointers to its related transaction and payout. The clawback UUID is generated when the clawback is created. Refer to the Get Clawback section in the API documentation for request and response details.

---

​

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.

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. 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. 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:

---

​

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

• Transaction States
• ACH Return Codes
• Scenario: Direct Payout
• Scenario: Batch Payout