This page outlines the various states a transaction can move through during its lifecycle, with the
corresponding Event that appears in API payloads.
To follow the entire movement of funds from a payer to a payee, you will need to monitor both the main transaction states
and the payout states outlined below.
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 |
|---|
CAPTURE_PENDING | The transaction has been started. | TransactionStarted |
CAPTURE_ACH_PENDING | The debit from the payor is in progress; waiting for deposit into the FBO account. | TransactionCaptureStarted |
CAPTURE_ACH_FAILED | The debit from the payor has failed. May occur after the payout has already completed. | TransactionFailed |
PAUSED | The transaction has been paused | TransactionPaused |
AWAITING_CANCELLATION | The transaction was requested to be cancelled before the debit has settled. | TransactionAwaitingCancellation |
CANCELED | The transaction was canceled upon request. | TransactionCanceled |
CLAWBACK | A clawback was performed due to a failed debit after payout. | ClawbackComplete |
PAYOUT_PENDING_ACH | The credit to the payee has started, but the ACH credit has not been created yet. | PayoutCreated |
IN_PAYOUT | The transaction has been included in a direct or batch payout. | PayoutComplete |
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_COMPLETE | Confirmation received that funds were sent to the payee. | PayoutComplete |
PAYOUT_ACH_FAILED | Payout to the payee failed. | PayoutFailed |
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 ACH credit has not been created yet. | PayoutCreated |
PROCESSING | ACH credit is in progress; waiting for confirmation. | — |
CANCELED | Confirmation received that funds were sent to the payee. | PayoutFailed |
SENT | The Credit has been sent and is awaiting for the receiving institution to accept the payment | - |
DONE | The credit is complete. | PayoutComplete |
ERROR | Payout to the payee failed due to an error in the transfer. | PayoutFailed |
REJECTED | Payout to the payee failed due to being rejected by the destination institution | PayoutFailed |
BLOCKED | Payout to the payee failed due to being blocked by the desitination institution | PayoutFailed |
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_ACH_PENDING | ACH credit has been picked up by the bank; confirmation is pending. | ReversePayoutStarted |
REVERSE_PAYOUT_ACH_COMPLETE | Confirmation received that funds were returned to the payer. | ReversePayoutCompleted |
REVERSE_PAYOUT_ACH_FAILED | Reverse payout failed. | ReversePayoutFailed |
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 | ClawbackStarted |
CLAWBACK_ACH_PENDING | Bank is processing the debit from the payee; waiting for deposit into the FBO account. | ClawbackCaptureStarted |
CLAWBACK_COMPLETE | The clawback completed successfully; funds returned to the FBO account. | ClawbackCompleted |
CLAWBACK_ACH_FAILED | The clawback ACH failed. | ClawbackFailed |
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. | RefundPending |
REFUND_CAPTURE_ACH_PENDING | Debit from payee to FBO is in progress. | RefundCaptureStarted |
REFUND_ACH_PENDING | ACH credit to payer initiated. | RefundCaptureCompleted, RefundPayoutPending |
REFUND_COMPLETE | Refund has completed successfully. | RefundPayoutCompleted |
REFUND_FAILED | The refund process failed. | RefundCaptureFailed, RefundPayoutFailed |
REFUND_CANCELLED | Refund has been cancelled | RefundPayoutCompleted |
