Skip to content
Select theme

Transaction States & Events

This page outlines the various states a transaction can move through during its lifecycle, with the corresponding Event that appears in API payloads.


The main transaction states represent the key stages in a transaction’s lifecycle—from the initial debit of funds from the payer to the final payout to the payee. These states are reflected on the transaction record and indicate the progression of funds, starting with the capture phase and concluding when the transaction enters the payout (credit) phase.

State Description Event
QUEUED The transaction has been added to our pipeline for processing. No Event
DECLINED The transaction was declined by transaction rules after being queued; declined_reason says why. transaction.declined
CAPTURE_PENDING The transaction has been started. transaction.created
CAPTURE_ACH_PENDING The debit from the payor is in progress; waiting for deposit into the FBO account. transaction.processing
PAYOUT_PENDING_ACH The debit from the payor has been completed and deposited into the FBO account. transaction.completed
CAPTURE_ACH_FAILED The debit from the payor has failed. May occur after the payout has already completed. transaction.failed
PAUSED The transaction has been paused transaction.paused
AWAITING_CANCELLATION The transaction was requested to be cancelled before the debit has settled. transaction.awaiting_cancellation
CANCELED The transaction was cancelled upon request. transaction.cancelled
CLAWBACK A clawback was performed due to a failed debit after payout. clawback.completed
PAYOUT_ACH_PENDING The credit process to the payee has started, but the ACH credit has not been created yet. No Event
IN_PAYOUT The transaction has been included in a direct or batch payout. No Event

In our webhooks and API responses, the capture status field indicates the current state of the capture phase of a transaction. This phase involves debiting funds from the payor and depositing them into the FBO account. The capture status provides insights into the progress of this process, from initiation to completion or failure.

State Description Event
QUEUED The transaction has been added to our pipeline for processing. No Event
CAPTURE_PENDING The transaction has been started. transaction.created
CAPTURE_ACH_PENDING The debit from the payor is in progress; waiting for deposit into the FBO account. transaction.processing
CAPTURE_ACH_FAILED The debit from the payor has failed. May occur after the payout has already completed. transaction.failed
CAPTURE_COMPLETE The debit from the payor has been completed and deposited into the FBO account. transaction.completed
PAUSED The transaction has been paused transaction.paused
AWAITING_CANCELLATION The transaction was requested to be cancelled before the debit has settled. transaction.awaiting_cancellation
CANCELED The transaction was cancelled upon request. transaction.cancelled

The payout states represent the stages involved in crediting funds to the payee after a successful capture of funds from the payor. These states indicate the progress of the payout process, starting from the initiation of the payout to its completion or failure.

The following states occur during the payout phase of a transaction, when funds are being sent to the payee. The states below are relevant to payouts created using the ACH payment rail.

State Description Event
PAYOUT_ACH_PENDING ACH credit is in progress; waiting for confirmation. payout.processing
PAYOUT_COMPLETE Confirmation received that funds were sent to the payee. payout.completed
PAYOUT_ACH_FAILED Payout to the payee failed. payout.failed

The following states occur during the payout phase of a transaction, when funds are being sent to the payee. The states below are relevant to payouts created using the FedNow payment rail.

State Description Event
PENDING The credit to the payee has started, but the Instant credit has not been created yet. —
PROCESSING Instant credit is in progress; waiting for confirmation. —
CANCELED The payout has been cancelled. payout.failed
SENT The Credit has been sent and is awaiting for the receiving institution to accept the payment -
DONE The credit is complete. payout.completed
ERROR Payout to the payee failed due to an error in the transfer. payout.failed
REJECTED Payout to the payee failed due to being rejected by the destination institution payout.failed
BLOCKED Payout to the payee failed due to being blocked by the destination institution payout.failed

A successful transaction only involves the capture and payout phases. The following additional flows occur in edge cases such as errors or refunds.


These occur when a payout fails and funds need to be returned to the payer.

State Description Event
REVERSE_PAYOUT_PENDING The reversal credit to the payer has been initiated. reverse_payout.created
REVERSE_PAYOUT_ACH_PENDING ACH credit has been picked up by the bank; confirmation is pending. reverse_payout.processing
REVERSE_PAYOUT_ACH_COMPLETE Confirmation received that funds were returned to the payer. reverse_payout.completed
REVERSE_PAYOUT_ACH_FAILED Reverse payout failed. reverse_payout.failed
REVERSE_PAYOUT_CANCELLED The reverse payout has been cancelled. —

A clawback is initiated if the debit from the payor is reversed after funds were already sent to the payee.

State Description Event
CLAWBACK_PENDING The Clawback has been created within the GrailPay system and is awaiting the creation of debit from the payee clawback.created
CLAWBACK_ACH_PENDING Bank is processing the debit from the payee; waiting for deposit into the FBO account. clawback.processing
CLAWBACK_COMPLETE The clawback completed successfully; funds returned to the FBO account. clawback.completed
CLAWBACK_ACH_FAILED The clawback ACH failed. clawback.failed
CLAWBACK_CANCELLED The clawback has been cancelled.

Refunds are initiated post-transaction to return funds to the original payer via the Refund a Transaction API.

State Description Event
REFUND_PENDING Refund requested from payee to payer. refund.created
REFUND_CAPTURE_ACH_PENDING Debit from payee to FBO is in progress. refund.capture_processing
REFUND_ACH_PENDING ACH credit to payer initiated. refund.capture_completed, refund.payout_processing
REFUND_COMPLETE Refund has completed successfully. refund.payout_completed
REFUND_FAILED The refund process failed. refund.capture_failed, refund.payout_failed
REFUND_CANCELLED Refund has been cancelled No Event

Maintained by EkLine