Quickvee PayDocs
Browse topics

Manage Transactions

Overview

The Manage Transactions section of the Quickvee Pay 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 ksuid
  • 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 KSUID

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.

Example

curl --location '{base}/api/v1/m/payments/{ksuid}' \
--header 'Content-Type: application/json' \
--header 'X-API-Key: {sha256(API_KEY)}' \
--header 'X-Timestamp: {current_unix_timestamp}' \
--header 'X-Nonce: {unique_random_string}' \
--header 'X-Signature: {hex_encoded_signature}'

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.

Example

curl --location '{base}/api/v1/m/payments?limit=10&offset=0&sort_order=-created_at,updated_at' \
--header 'Content-Type: application/json' \
--header 'X-API-Key: {sha256(API_KEY)}' \
--header 'X-Timestamp: {current_unix_timestamp}' \
--header 'X-Nonce: {unique_random_string}' \
--header 'X-Signature: {hex_encoded_signature}'

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.

Given the multi-party file-based nature of ACH, Quickvee Pay cannot truly cancel a debit once the file has entered the Sent state. At this point, the debit file has been sent to the ACH network and will proceed according to the rules and regulations of ACH.

After a debit enters the Sent State, it will process and settle as expected according to the applicable rules and regulations of ACH. Quickvee Pay's cancellation functionality acts as a recuperation mechanism that creates a reverse payout to reverse the funds of the transfer once the debit has settled. In the event that a debit initially succeeds but then fails due to an ACH return, a reverse payout will not be needed and will not be created. If an ACH return does not occur within the allowable window, a reverse payout will automatically be created given the cancellation.

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 event is fired. Once cancellation is finalized, the TransactionCanceled event is sent.

Example

curl --location '{base}/api/v1/m/payments/{ksuid}/cancel' \
--header 'Content-Type: application/json' \
--header 'X-API-Key: {sha256(API_KEY)}' \
--header 'X-Timestamp: {current_unix_timestamp}' \
--header 'X-Nonce: {unique_random_string}' \
--header 'X-Signature: {hex_encoded_signature}'

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 event is emitted. Transactions that remain paused for more than 5 days are automatically canceled by the platform to prevent indefinite holds.

Example

curl --location '{base}/api/v1/m/payments/{ksuid}/pause' \
--header 'Content-Type: application/json' \
--header 'X-API-Key: {sha256(API_KEY)}' \
--header 'X-Timestamp: {current_unix_timestamp}' \
--header 'X-Nonce: {unique_random_string}' \
--header 'X-Signature: {hex_encoded_signature}'

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 event is emitted.

Example

curl --location '{base}/api/v1/m/payments/{ksuid}/resume' \
--header 'Content-Type: application/json' \
--header 'X-API-Key: {sha256(API_KEY)}' \
--header 'X-Timestamp: {current_unix_timestamp}' \
--header 'X-Nonce: {unique_random_string}' \
--header 'X-Signature: {hex_encoded_signature}'

Transaction Status Flow

API actions map to status changes:

  • Pause — Status becomes PAUSED.
  • Resume — Processing continues from the prior status (for example PENDING).
  • Cancel (before debit is created) — Status becomes CANCELED.
  • Cancel (after debit, before settlement) — Status moves to AWAITING_CANCELLATION, then CANCELED when the cancellation flow completes.
  • Cancel (after debit has settled) — Ends as CANCELED (via reverse payout).

For narrative detail on cancellation timing and reverse payouts, see Cancel a Transaction above.

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.

Next Up

Read Idempotency

Questions?

If you're encountering any issues, please reach out to support@quickveepay.com.

Resources