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.

Main Transaction States

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

Capture Status States

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`

Payout States (Credit to Payee)

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.

ACH Payouts

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`

FedNow Payouts

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`

Sub-Operations

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

Reverse Payout States

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

Clawback

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.

Refund

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