# Transaction Events

Transaction events provide visibility into the full lifecycle of the debit side of a payment, when funds are pulled from the payor's bank account. These events allow your platform to monitor the status of ACH debits as they move through creation, processing, completion, or failure.

Each webhook corresponds to a specific stage of the transaction journey, from initial creation (`transaction.created`) to settlement (`transaction.completed`), including events for pause and resume, cancellation, decline, and failure. By subscribing to these events, you can build real-time audit trails, trigger status updates, and automate downstream actions tied to the movement of funds from the payor.

:::note
If a transaction cannot be processed, the error details are sent in the payload through `ach_return_code`. For a list of ACH return codes see our [Return Codes](/docs/resources/return-codes) documentation.
:::

All payloads below are shown in full, including the [event envelope](/docs/technical/webhooks/events/#event-envelope).

***

## `transaction.created`

This webhook is triggered when a transaction has been successfully created in the GrailPay system but ACH processing has not yet begun. It marks the initial step in the transaction lifecycle.

```json title="Event"
{
  "event": "transaction.created",
  "event_uuid": "019d072d-1203-7695-842b-a15567fbb0d8",
  "event_occurred_at": "2026-04-05 14:28:33",
  "event_version": 3,
  "vendor_uuid": "019e2711-5a92-735d-a7d5-669aec76b54f",
  "data": {
    "transaction": {
      "uuid": "9b97f15d-83bc-41ad-9514-0437180d0192",
      "client_reference_id": "2",
      "status": "IN_PAYOUT",
      "currency": "USD",
      "trace_id": "ach_11jzggrptrftyd",
      "amount": 3245,
      "transaction_fee": 0,
      "payout_delay_days": 0,
      "company_name": "MoneyOne",
      "description": "sending money",
      "addenda": null,
      "type": "api",
      "modality": {
        "transaction": {
          "payment_rail": "ach",
          "speed": "standard"
        },
        "payout": {
          "payment_rail": "ach",
          "speed": "standard"
        }
      },
      "ach_return_code": null,
      "cancel_reason": null,
      "declined_reason": null,
      "bank_identifiers": {
        "debit_bank_id": "ach_11n4zxrp1twjebp",
        "debit_trace_id": "2145642244586478"
      },
      "payor": {
        "uuid": "f3d8c9d1-0b8b-4e79-bc41-8998cbbd58b1",
        "user_uuid": "f3d8c9d1-0b8b-4e79-bc41-8998cbbd58b1",
        "type": "person",
        "name": "John Doe",
        "processor_mid": null,
        "bank_account": {
          "uuid": "9b97f121-a449-4b52-9f36-6c55f18394d6",
          "aggregator_type": "manual",
          "provider_type": "manual",
          "account_name": "Acme, Inc",
          "account_type": "checking",
          "account_number": "1111222233330000",
          "routing_number": "011401533",
          "institution_name": "Bank of America",
          "aggregator": "mx",
          "is_default": true,
          "client_reference_id": "client-1234",
          "status": "connected",
          "timestamps": {
            "created_at": "2024-06-25 13:57:03"
          }
        }
      },
      "payee": {
        "uuid": "1a437e1f-c112-4534-ac44-2de71cec9f1f",
        "user_uuid": "f3d8c9d1-0b8b-4e79-bc41-8998cbbd58b1",
        "type": "business",
        "name": "Acme Pest Control",
        "processor_mid": null,
        "bank_account": {
          "uuid": "9b97f121-a449-4b52-9f36-6c55f18394d6",
          "aggregator_type": "manual",
          "provider_type": "manual",
          "account_name": "Acme, Inc",
          "account_type": "checking",
          "account_number": "1111222233330000",
          "routing_number": "011401533",
          "institution_name": "Bank of America",
          "aggregator": "mx",
          "is_default": true,
          "client_reference_id": "client-1234",
          "status": "connected",
          "timestamps": {
            "created_at": "2024-06-25 13:57:03"
          }
        }
      },
      "timestamps": {
        "created_at": "2024-06-25 13:57:03"
      },
      "ach_timestamps": {
        "created_at": "2024-03-20 16:00:28",
        "processed_at": null,
        "sent_at": null,
        "settled_at": "2024-03-20 17:00:27",
        "failed_at": null,
        "cancelled_at": null,
        "declined_at": null
      }
    }
  }
}
```

## `transaction.awaiting_cancellation`

This webhook is triggered when a cancellation request for a transaction has been received and the debit ACH has not settled yet.

```json title="Event"
{
  "event": "transaction.awaiting_cancellation",
  "event_uuid": "019d072d-1203-7695-842b-a15567fbb0d8",
  "event_occurred_at": "2026-04-05 14:28:33",
  "event_version": 3,
  "vendor_uuid": "019e2711-5a92-735d-a7d5-669aec76b54f",
  "data": {
    "transaction": {
      "uuid": "9b97f15d-83bc-41ad-9514-0437180d0192",
      "client_reference_id": "2",
      "status": "IN_PAYOUT",
      "currency": "USD",
      "trace_id": "ach_11jzggrptrftyd",
      "amount": 3245,
      "transaction_fee": 0,
      "payout_delay_days": 0,
      "company_name": "MoneyOne",
      "description": "sending money",
      "addenda": null,
      "type": "api",
      "modality": {
        "transaction": {
          "payment_rail": "ach",
          "speed": "standard"
        },
        "payout": {
          "payment_rail": "ach",
          "speed": "standard"
        }
      },
      "ach_return_code": null,
      "cancel_reason": null,
      "declined_reason": null,
      "bank_identifiers": {
        "debit_bank_id": "ach_11n4zxrp1twjebp",
        "debit_trace_id": "2145642244586478"
      },
      "payor": {
        "uuid": "f3d8c9d1-0b8b-4e79-bc41-8998cbbd58b1",
        "user_uuid": "f3d8c9d1-0b8b-4e79-bc41-8998cbbd58b1",
        "type": "person",
        "name": "John Doe",
        "processor_mid": null,
        "bank_account": {
          "uuid": "9b97f121-a449-4b52-9f36-6c55f18394d6",
          "aggregator_type": "manual",
          "provider_type": "manual",
          "account_name": "Acme, Inc",
          "account_type": "checking",
          "account_number": "1111222233330000",
          "routing_number": "011401533",
          "institution_name": "Bank of America",
          "aggregator": "mx",
          "is_default": true,
          "client_reference_id": "client-1234",
          "status": "connected",
          "timestamps": {
            "created_at": "2024-06-25 13:57:03"
          }
        }
      },
      "payee": {
        "uuid": "1a437e1f-c112-4534-ac44-2de71cec9f1f",
        "user_uuid": "f3d8c9d1-0b8b-4e79-bc41-8998cbbd58b1",
        "type": "business",
        "name": "Acme Pest Control",
        "processor_mid": null,
        "bank_account": {
          "uuid": "9b97f121-a449-4b52-9f36-6c55f18394d6",
          "aggregator_type": "manual",
          "provider_type": "manual",
          "account_name": "Acme, Inc",
          "account_type": "checking",
          "account_number": "1111222233330000",
          "routing_number": "011401533",
          "institution_name": "Bank of America",
          "aggregator": "mx",
          "is_default": true,
          "client_reference_id": "client-1234",
          "status": "connected",
          "timestamps": {
            "created_at": "2024-06-25 13:57:03"
          }
        }
      },
      "timestamps": {
        "created_at": "2024-06-25 13:57:03"
      },
      "ach_timestamps": {
        "created_at": "2024-03-20 16:00:28",
        "processed_at": null,
        "sent_at": null,
        "settled_at": "2024-03-20 17:00:27",
        "failed_at": null,
        "cancelled_at": null,
        "declined_at": null
      }
    }
  }
}
```

## `transaction.paused`

This webhook is triggered when a transaction has been paused, typically due to compliance or risk review processes.

```json title="Event"
{
  "event": "transaction.paused",
  "event_uuid": "019d072d-1203-7695-842b-a15567fbb0d8",
  "event_occurred_at": "2026-04-05 14:28:33",
  "event_version": 3,
  "vendor_uuid": "019e2711-5a92-735d-a7d5-669aec76b54f",
  "data": {
    "transaction": {
      "uuid": "9b97f15d-83bc-41ad-9514-0437180d0192",
      "client_reference_id": "2",
      "status": "IN_PAYOUT",
      "currency": "USD",
      "trace_id": "ach_11jzggrptrftyd",
      "amount": 3245,
      "transaction_fee": 0,
      "payout_delay_days": 0,
      "company_name": "MoneyOne",
      "description": "sending money",
      "addenda": null,
      "type": "api",
      "modality": {
        "transaction": {
          "payment_rail": "ach",
          "speed": "standard"
        },
        "payout": {
          "payment_rail": "ach",
          "speed": "standard"
        }
      },
      "ach_return_code": null,
      "cancel_reason": null,
      "declined_reason": null,
      "bank_identifiers": {
        "debit_bank_id": "ach_11n4zxrp1twjebp",
        "debit_trace_id": "2145642244586478"
      },
      "payor": {
        "uuid": "f3d8c9d1-0b8b-4e79-bc41-8998cbbd58b1",
        "user_uuid": "f3d8c9d1-0b8b-4e79-bc41-8998cbbd58b1",
        "type": "person",
        "name": "John Doe",
        "processor_mid": null,
        "bank_account": {
          "uuid": "9b97f121-a449-4b52-9f36-6c55f18394d6",
          "aggregator_type": "manual",
          "provider_type": "manual",
          "account_name": "Acme, Inc",
          "account_type": "checking",
          "account_number": "1111222233330000",
          "routing_number": "011401533",
          "institution_name": "Bank of America",
          "aggregator": "mx",
          "is_default": true,
          "client_reference_id": "client-1234",
          "status": "connected",
          "timestamps": {
            "created_at": "2024-06-25 13:57:03"
          }
        }
      },
      "payee": {
        "uuid": "1a437e1f-c112-4534-ac44-2de71cec9f1f",
        "user_uuid": "f3d8c9d1-0b8b-4e79-bc41-8998cbbd58b1",
        "type": "business",
        "name": "Acme Pest Control",
        "processor_mid": null,
        "bank_account": {
          "uuid": "9b97f121-a449-4b52-9f36-6c55f18394d6",
          "aggregator_type": "manual",
          "provider_type": "manual",
          "account_name": "Acme, Inc",
          "account_type": "checking",
          "account_number": "1111222233330000",
          "routing_number": "011401533",
          "institution_name": "Bank of America",
          "aggregator": "mx",
          "is_default": true,
          "client_reference_id": "client-1234",
          "status": "connected",
          "timestamps": {
            "created_at": "2024-06-25 13:57:03"
          }
        }
      },
      "timestamps": {
        "created_at": "2024-06-25 13:57:03"
      },
      "ach_timestamps": {
        "created_at": "2024-03-20 16:00:28",
        "processed_at": null,
        "sent_at": null,
        "settled_at": "2024-03-20 17:00:27",
        "failed_at": null,
        "cancelled_at": null,
        "declined_at": null
      }
    }
  }
}
```

## `transaction.resumed`

This webhook is triggered when a paused transaction has been resumed and is back in processing.

```json title="Event"
{
  "event": "transaction.resumed",
  "event_uuid": "019d072d-1203-7695-842b-a15567fbb0d8",
  "event_occurred_at": "2026-04-05 14:28:33",
  "event_version": 3,
  "vendor_uuid": "019e2711-5a92-735d-a7d5-669aec76b54f",
  "data": {
    "transaction": {
      "uuid": "9b97f15d-83bc-41ad-9514-0437180d0192",
      "client_reference_id": "2",
      "status": "IN_PAYOUT",
      "currency": "USD",
      "trace_id": "ach_11jzggrptrftyd",
      "amount": 3245,
      "transaction_fee": 0,
      "payout_delay_days": 0,
      "company_name": "MoneyOne",
      "description": "sending money",
      "addenda": null,
      "type": "api",
      "modality": {
        "transaction": {
          "payment_rail": "ach",
          "speed": "standard"
        },
        "payout": {
          "payment_rail": "ach",
          "speed": "standard"
        }
      },
      "ach_return_code": null,
      "cancel_reason": null,
      "declined_reason": null,
      "bank_identifiers": {
        "debit_bank_id": "ach_11n4zxrp1twjebp",
        "debit_trace_id": "2145642244586478"
      },
      "payor": {
        "uuid": "f3d8c9d1-0b8b-4e79-bc41-8998cbbd58b1",
        "user_uuid": "f3d8c9d1-0b8b-4e79-bc41-8998cbbd58b1",
        "type": "person",
        "name": "John Doe",
        "processor_mid": null,
        "bank_account": {
          "uuid": "9b97f121-a449-4b52-9f36-6c55f18394d6",
          "aggregator_type": "manual",
          "provider_type": "manual",
          "account_name": "Acme, Inc",
          "account_type": "checking",
          "account_number": "1111222233330000",
          "routing_number": "011401533",
          "institution_name": "Bank of America",
          "aggregator": "mx",
          "is_default": true,
          "client_reference_id": "client-1234",
          "status": "connected",
          "timestamps": {
            "created_at": "2024-06-25 13:57:03"
          }
        }
      },
      "payee": {
        "uuid": "1a437e1f-c112-4534-ac44-2de71cec9f1f",
        "user_uuid": "f3d8c9d1-0b8b-4e79-bc41-8998cbbd58b1",
        "type": "business",
        "name": "Acme Pest Control",
        "processor_mid": null,
        "bank_account": {
          "uuid": "9b97f121-a449-4b52-9f36-6c55f18394d6",
          "aggregator_type": "manual",
          "provider_type": "manual",
          "account_name": "Acme, Inc",
          "account_type": "checking",
          "account_number": "1111222233330000",
          "routing_number": "011401533",
          "institution_name": "Bank of America",
          "aggregator": "mx",
          "is_default": true,
          "client_reference_id": "client-1234",
          "status": "connected",
          "timestamps": {
            "created_at": "2024-06-25 13:57:03"
          }
        }
      },
      "timestamps": {
        "created_at": "2024-06-25 13:57:03"
      },
      "ach_timestamps": {
        "created_at": "2024-03-20 16:00:28",
        "processed_at": null,
        "sent_at": null,
        "settled_at": "2024-03-20 17:00:27",
        "failed_at": null,
        "cancelled_at": null,
        "declined_at": null
      }
    }
  }
}
```

## `transaction.cancelled`

This webhook is triggered whenever a transaction is canceled before it is processed. It confirms that no funds will be captured or disbursed for the canceled transaction.

```json title="Event"
{
  "event": "transaction.cancelled",
  "event_uuid": "019d072d-1203-7695-842b-a15567fbb0d8",
  "event_occurred_at": "2026-04-05 14:28:33",
  "event_version": 3,
  "vendor_uuid": "019e2711-5a92-735d-a7d5-669aec76b54f",
  "data": {
    "transaction": {
      "uuid": "9b97f15d-83bc-41ad-9514-0437180d0192",
      "client_reference_id": "2",
      "status": "IN_PAYOUT",
      "currency": "USD",
      "trace_id": "ach_11jzggrptrftyd",
      "amount": 3245,
      "transaction_fee": 0,
      "payout_delay_days": 0,
      "company_name": "MoneyOne",
      "description": "sending money",
      "addenda": null,
      "type": "api",
      "modality": {
        "transaction": {
          "payment_rail": "ach",
          "speed": "standard"
        },
        "payout": {
          "payment_rail": "ach",
          "speed": "standard"
        }
      },
      "ach_return_code": null,
      "cancel_reason": null,
      "declined_reason": null,
      "bank_identifiers": {
        "debit_bank_id": "ach_11n4zxrp1twjebp",
        "debit_trace_id": "2145642244586478"
      },
      "payor": {
        "uuid": "f3d8c9d1-0b8b-4e79-bc41-8998cbbd58b1",
        "user_uuid": "f3d8c9d1-0b8b-4e79-bc41-8998cbbd58b1",
        "type": "person",
        "name": "John Doe",
        "processor_mid": null,
        "bank_account": {
          "uuid": "9b97f121-a449-4b52-9f36-6c55f18394d6",
          "aggregator_type": "manual",
          "provider_type": "manual",
          "account_name": "Acme, Inc",
          "account_type": "checking",
          "account_number": "1111222233330000",
          "routing_number": "011401533",
          "institution_name": "Bank of America",
          "aggregator": "mx",
          "is_default": true,
          "client_reference_id": "client-1234",
          "status": "connected",
          "timestamps": {
            "created_at": "2024-06-25 13:57:03"
          }
        }
      },
      "payee": {
        "uuid": "1a437e1f-c112-4534-ac44-2de71cec9f1f",
        "user_uuid": "f3d8c9d1-0b8b-4e79-bc41-8998cbbd58b1",
        "type": "business",
        "name": "Acme Pest Control",
        "processor_mid": null,
        "bank_account": {
          "uuid": "9b97f121-a449-4b52-9f36-6c55f18394d6",
          "aggregator_type": "manual",
          "provider_type": "manual",
          "account_name": "Acme, Inc",
          "account_type": "checking",
          "account_number": "1111222233330000",
          "routing_number": "011401533",
          "institution_name": "Bank of America",
          "aggregator": "mx",
          "is_default": true,
          "client_reference_id": "client-1234",
          "status": "connected",
          "timestamps": {
            "created_at": "2024-06-25 13:57:03"
          }
        }
      },
      "timestamps": {
        "created_at": "2024-06-25 13:57:03"
      },
      "ach_timestamps": {
        "created_at": "2024-03-20 16:00:28",
        "processed_at": null,
        "sent_at": null,
        "settled_at": "2024-03-20 17:00:27",
        "failed_at": null,
        "cancelled_at": null,
        "declined_at": null
      }
    }
  }
}
```

## `transaction.processing`

This webhook is triggered when an ACH debit has been successfully initiated as part of a transaction. It indicates that the funds capture process has begun from the payor's bank account.

```json title="Event"
{
  "event": "transaction.processing",
  "event_uuid": "019d072d-1203-7695-842b-a15567fbb0d8",
  "event_occurred_at": "2026-04-05 14:28:33",
  "event_version": 3,
  "vendor_uuid": "019e2711-5a92-735d-a7d5-669aec76b54f",
  "data": {
    "transaction": {
      "uuid": "9b97f15d-83bc-41ad-9514-0437180d0192",
      "client_reference_id": "2",
      "status": "IN_PAYOUT",
      "currency": "USD",
      "trace_id": "ach_11jzggrptrftyd",
      "amount": 3245,
      "transaction_fee": 0,
      "payout_delay_days": 0,
      "company_name": "MoneyOne",
      "description": "sending money",
      "addenda": null,
      "type": "api",
      "modality": {
        "transaction": {
          "payment_rail": "ach",
          "speed": "standard"
        },
        "payout": {
          "payment_rail": "ach",
          "speed": "standard"
        }
      },
      "ach_return_code": null,
      "cancel_reason": null,
      "declined_reason": null,
      "bank_identifiers": {
        "debit_bank_id": "ach_11n4zxrp1twjebp",
        "debit_trace_id": "2145642244586478"
      },
      "payor": {
        "uuid": "f3d8c9d1-0b8b-4e79-bc41-8998cbbd58b1",
        "user_uuid": "f3d8c9d1-0b8b-4e79-bc41-8998cbbd58b1",
        "type": "person",
        "name": "John Doe",
        "processor_mid": null,
        "bank_account": {
          "uuid": "9b97f121-a449-4b52-9f36-6c55f18394d6",
          "aggregator_type": "manual",
          "provider_type": "manual",
          "account_name": "Acme, Inc",
          "account_type": "checking",
          "account_number": "1111222233330000",
          "routing_number": "011401533",
          "institution_name": "Bank of America",
          "aggregator": "mx",
          "is_default": true,
          "client_reference_id": "client-1234",
          "status": "connected",
          "timestamps": {
            "created_at": "2024-06-25 13:57:03"
          }
        }
      },
      "payee": {
        "uuid": "1a437e1f-c112-4534-ac44-2de71cec9f1f",
        "user_uuid": "f3d8c9d1-0b8b-4e79-bc41-8998cbbd58b1",
        "type": "business",
        "name": "Acme Pest Control",
        "processor_mid": null,
        "bank_account": {
          "uuid": "9b97f121-a449-4b52-9f36-6c55f18394d6",
          "aggregator_type": "manual",
          "provider_type": "manual",
          "account_name": "Acme, Inc",
          "account_type": "checking",
          "account_number": "1111222233330000",
          "routing_number": "011401533",
          "institution_name": "Bank of America",
          "aggregator": "mx",
          "is_default": true,
          "client_reference_id": "client-1234",
          "status": "connected",
          "timestamps": {
            "created_at": "2024-06-25 13:57:03"
          }
        }
      },
      "timestamps": {
        "created_at": "2024-06-25 13:57:03"
      },
      "ach_timestamps": {
        "created_at": "2024-03-20 16:00:28",
        "processed_at": null,
        "sent_at": null,
        "settled_at": "2024-03-20 17:00:27",
        "failed_at": null,
        "cancelled_at": null,
        "declined_at": null
      }
    }
  }
}
```

## `transaction.failed`

This webhook is triggered when a transaction fails at any stage of processing, whether due to account issues, validation errors, or ACH return codes.

```json title="Event"
{
  "event": "transaction.failed",
  "event_uuid": "019d072d-1203-7695-842b-a15567fbb0d8",
  "event_occurred_at": "2026-04-05 14:28:33",
  "event_version": 3,
  "vendor_uuid": "019e2711-5a92-735d-a7d5-669aec76b54f",
  "data": {
    "transaction": {
      "uuid": "9b97f15d-83bc-41ad-9514-0437180d0192",
      "client_reference_id": "2",
      "status": "IN_PAYOUT",
      "currency": "USD",
      "trace_id": "ach_11jzggrptrftyd",
      "amount": 3245,
      "transaction_fee": 0,
      "payout_delay_days": 0,
      "company_name": "MoneyOne",
      "description": "sending money",
      "addenda": null,
      "type": "api",
      "modality": {
        "transaction": {
          "payment_rail": "ach",
          "speed": "standard"
        },
        "payout": {
          "payment_rail": "ach",
          "speed": "standard"
        }
      },
      "ach_return_code": null,
      "cancel_reason": null,
      "declined_reason": null,
      "bank_identifiers": {
        "debit_bank_id": "ach_11n4zxrp1twjebp",
        "debit_trace_id": "2145642244586478"
      },
      "payor": {
        "uuid": "f3d8c9d1-0b8b-4e79-bc41-8998cbbd58b1",
        "user_uuid": "f3d8c9d1-0b8b-4e79-bc41-8998cbbd58b1",
        "type": "person",
        "name": "John Doe",
        "processor_mid": null,
        "bank_account": {
          "uuid": "9b97f121-a449-4b52-9f36-6c55f18394d6",
          "aggregator_type": "manual",
          "provider_type": "manual",
          "account_name": "Acme, Inc",
          "account_type": "checking",
          "account_number": "1111222233330000",
          "routing_number": "011401533",
          "institution_name": "Bank of America",
          "aggregator": "mx",
          "is_default": true,
          "client_reference_id": "client-1234",
          "status": "connected",
          "timestamps": {
            "created_at": "2024-06-25 13:57:03"
          }
        }
      },
      "payee": {
        "uuid": "1a437e1f-c112-4534-ac44-2de71cec9f1f",
        "user_uuid": "f3d8c9d1-0b8b-4e79-bc41-8998cbbd58b1",
        "type": "business",
        "name": "Acme Pest Control",
        "processor_mid": null,
        "bank_account": {
          "uuid": "9b97f121-a449-4b52-9f36-6c55f18394d6",
          "aggregator_type": "manual",
          "provider_type": "manual",
          "account_name": "Acme, Inc",
          "account_type": "checking",
          "account_number": "1111222233330000",
          "routing_number": "011401533",
          "institution_name": "Bank of America",
          "aggregator": "mx",
          "is_default": true,
          "client_reference_id": "client-1234",
          "status": "connected",
          "timestamps": {
            "created_at": "2024-06-25 13:57:03"
          }
        }
      },
      "timestamps": {
        "created_at": "2024-06-25 13:57:03"
      },
      "ach_timestamps": {
        "created_at": "2024-03-20 16:00:28",
        "processed_at": null,
        "sent_at": null,
        "settled_at": "2024-03-20 17:00:27",
        "failed_at": null,
        "cancelled_at": null,
        "declined_at": null
      }
    }
  }
}
```

## `transaction.completed`

This webhook is triggered when a transaction has been successfully debited from the payer, meaning the ACH debit from the payor has been settled, and we have begun the payout process to the payee.

```json title="Event"
{
  "event": "transaction.completed",
  "event_uuid": "019d072d-1203-7695-842b-a15567fbb0d8",
  "event_occurred_at": "2026-04-05 14:28:33",
  "event_version": 3,
  "vendor_uuid": "019e2711-5a92-735d-a7d5-669aec76b54f",
  "data": {
    "transaction": {
      "uuid": "9b97f15d-83bc-41ad-9514-0437180d0192",
      "client_reference_id": "2",
      "status": "IN_PAYOUT",
      "currency": "USD",
      "trace_id": "ach_11jzggrptrftyd",
      "amount": 3245,
      "transaction_fee": 0,
      "payout_delay_days": 0,
      "company_name": "MoneyOne",
      "description": "sending money",
      "addenda": null,
      "type": "api",
      "modality": {
        "transaction": {
          "payment_rail": "ach",
          "speed": "standard"
        },
        "payout": {
          "payment_rail": "ach",
          "speed": "standard"
        }
      },
      "ach_return_code": null,
      "cancel_reason": null,
      "declined_reason": null,
      "bank_identifiers": {
        "debit_bank_id": "ach_11n4zxrp1twjebp",
        "debit_trace_id": "2145642244586478"
      },
      "payor": {
        "uuid": "f3d8c9d1-0b8b-4e79-bc41-8998cbbd58b1",
        "user_uuid": "f3d8c9d1-0b8b-4e79-bc41-8998cbbd58b1",
        "type": "person",
        "name": "John Doe",
        "processor_mid": null,
        "bank_account": {
          "uuid": "9b97f121-a449-4b52-9f36-6c55f18394d6",
          "aggregator_type": "manual",
          "provider_type": "manual",
          "account_name": "Acme, Inc",
          "account_type": "checking",
          "account_number": "1111222233330000",
          "routing_number": "011401533",
          "institution_name": "Bank of America",
          "aggregator": "mx",
          "is_default": true,
          "client_reference_id": "client-1234",
          "status": "connected",
          "timestamps": {
            "created_at": "2024-06-25 13:57:03"
          }
        }
      },
      "payee": {
        "uuid": "1a437e1f-c112-4534-ac44-2de71cec9f1f",
        "user_uuid": "f3d8c9d1-0b8b-4e79-bc41-8998cbbd58b1",
        "type": "business",
        "name": "Acme Pest Control",
        "processor_mid": null,
        "bank_account": {
          "uuid": "9b97f121-a449-4b52-9f36-6c55f18394d6",
          "aggregator_type": "manual",
          "provider_type": "manual",
          "account_name": "Acme, Inc",
          "account_type": "checking",
          "account_number": "1111222233330000",
          "routing_number": "011401533",
          "institution_name": "Bank of America",
          "aggregator": "mx",
          "is_default": true,
          "client_reference_id": "client-1234",
          "status": "connected",
          "timestamps": {
            "created_at": "2024-06-25 13:57:03"
          }
        }
      },
      "timestamps": {
        "created_at": "2024-06-25 13:57:03"
      },
      "ach_timestamps": {
        "created_at": "2024-03-20 16:00:28",
        "processed_at": null,
        "sent_at": null,
        "settled_at": "2024-03-20 17:00:27",
        "failed_at": null,
        "cancelled_at": null,
        "declined_at": null
      }
    }
  }
}
```

## `transaction.declined`

This webhook is triggered when a transaction has been queued and then declined due to transaction rules. The `declined_reason` field on the transaction and the `declined_at` timestamp within `ach_timestamps` indicate why and when the transaction was declined.

```json title="Event"
{
  "event": "transaction.declined",
  "event_uuid": "019d072d-1203-7695-842b-a15567fbb0d8",
  "event_occurred_at": "2026-04-05 14:28:33",
  "event_version": 3,
  "vendor_uuid": "019e2711-5a92-735d-a7d5-669aec76b54f",
  "data": {
    "transaction": {
      "uuid": "9b97f15d-83bc-41ad-9514-0437180d0192",
      "client_reference_id": "2",
      "status": "IN_PAYOUT",
      "currency": "USD",
      "trace_id": "ach_11jzggrptrftyd",
      "amount": 3245,
      "transaction_fee": 0,
      "payout_delay_days": 0,
      "company_name": "MoneyOne",
      "description": "sending money",
      "addenda": null,
      "type": "api",
      "modality": {
        "transaction": {
          "payment_rail": "ach",
          "speed": "standard"
        },
        "payout": {
          "payment_rail": "ach",
          "speed": "standard"
        }
      },
      "ach_return_code": null,
      "cancel_reason": null,
      "declined_reason": null,
      "bank_identifiers": {
        "debit_bank_id": "ach_11n4zxrp1twjebp",
        "debit_trace_id": "2145642244586478"
      },
      "payor": {
        "uuid": "f3d8c9d1-0b8b-4e79-bc41-8998cbbd58b1",
        "user_uuid": "f3d8c9d1-0b8b-4e79-bc41-8998cbbd58b1",
        "type": "person",
        "name": "John Doe",
        "processor_mid": null,
        "bank_account": {
          "uuid": "9b97f121-a449-4b52-9f36-6c55f18394d6",
          "aggregator_type": "manual",
          "provider_type": "manual",
          "account_name": "Acme, Inc",
          "account_type": "checking",
          "account_number": "1111222233330000",
          "routing_number": "011401533",
          "institution_name": "Bank of America",
          "aggregator": "mx",
          "is_default": true,
          "client_reference_id": "client-1234",
          "status": "connected",
          "timestamps": {
            "created_at": "2024-06-25 13:57:03"
          }
        }
      },
      "payee": {
        "uuid": "1a437e1f-c112-4534-ac44-2de71cec9f1f",
        "user_uuid": "f3d8c9d1-0b8b-4e79-bc41-8998cbbd58b1",
        "type": "business",
        "name": "Acme Pest Control",
        "processor_mid": null,
        "bank_account": {
          "uuid": "9b97f121-a449-4b52-9f36-6c55f18394d6",
          "aggregator_type": "manual",
          "provider_type": "manual",
          "account_name": "Acme, Inc",
          "account_type": "checking",
          "account_number": "1111222233330000",
          "routing_number": "011401533",
          "institution_name": "Bank of America",
          "aggregator": "mx",
          "is_default": true,
          "client_reference_id": "client-1234",
          "status": "connected",
          "timestamps": {
            "created_at": "2024-06-25 13:57:03"
          }
        }
      },
      "timestamps": {
        "created_at": "2024-06-25 13:57:03"
      },
      "ach_timestamps": {
        "created_at": "2024-03-20 16:00:28",
        "processed_at": null,
        "sent_at": null,
        "settled_at": "2024-03-20 17:00:27",
        "failed_at": null,
        "cancelled_at": null,
        "declined_at": null
      }
    }
  }
}
```