# Payout Events

Payout events reflect the final stage in GrailPay's transaction lifecycle, where funds are disbursed from the platform to a payee's linked bank account. These events are essential for tracking when money has been successfully moved out of the system, or when something has gone wrong. Whether you're monitoring cash flow, updating transaction statuses, or reconciling financial data, payout events provide the real-time signals you need.

GrailPay emits webhook events for each state in a payout's lifecycle: when its ACH credit begins processing (`payout.processing`), when it fails (`payout.failed`), and when it completes (`payout.completed`).

The `failover` field on the payout object is `null` in the ordinary case. When a payout is replaced by another payout, the original carries `failover.superseded_by` with the replacement's UUID, and the replacement carries `failover.supersedes` with the original's UUID.

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

***

<!-- `payout.created` is not emitted yet. Uncomment this section when it ships.
## `payout.created`

This webhook is triggered each time a payout (transfer of funds to the payee) has been created and is awaiting the ACH to be created.

```json title="Event"
{
  "event": "payout.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": {
    "payout": {
      "uuid": "8b2536c0-01c4-4699-8a97-b68eb8fb6b4f",
      "client_reference_id": "Payout_1784_1710950428",
      "entity": {
        "type": "merchant",
        "uuid": "5be9d011-b504-44d5-981f-0ec98ceab4c1"
      },
      "type": "individual",
      "status": "PAYOUT_COMPLETE",
      "trace_id": "ach_11jzp20wtve6z8",
      "amount": 3245,
      "speed": "standard",
      "sec_code": "ccd",
      "ach_return_code": null,
      "payout_failure_reason": null,
      "modality": {
        "payment_rail": "ach",
        "speed": "standard"
      },
      "bank_identifiers": {
        "debit_bank_id": "ach_11n4zxrp1twjebp",
        "debit_trace_id": "2145642244586478"
      },
      "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"
          }
        }
      },
      "failover": null,
      "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
      }
    },
    "relations": {
      "transaction_uuids": [
        "a6de4ae5-bec0-4466-b983-a8b8392dcb3a"
      ]
    }
  }
}
```
-->
## `payout.processing`

This webhook is triggered when the ACH credit to the payee has begun processing.

```json title="Event"
{
  "event": "payout.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": {
    "payout": {
      "uuid": "8b2536c0-01c4-4699-8a97-b68eb8fb6b4f",
      "client_reference_id": "Payout_1784_1710950428",
      "entity": {
        "type": "merchant",
        "uuid": "5be9d011-b504-44d5-981f-0ec98ceab4c1"
      },
      "type": "individual",
      "status": "PAYOUT_COMPLETE",
      "trace_id": "ach_11jzp20wtve6z8",
      "amount": 3245,
      "speed": "standard",
      "sec_code": "ccd",
      "ach_return_code": null,
      "payout_failure_reason": null,
      "modality": {
        "payment_rail": "ach",
        "speed": "standard"
      },
      "bank_identifiers": {
        "debit_bank_id": "ach_11n4zxrp1twjebp",
        "debit_trace_id": "2145642244586478"
      },
      "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"
          }
        }
      },
      "failover": null,
      "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
      }
    },
    "relations": {
      "transaction_uuids": [
        "a6de4ae5-bec0-4466-b983-a8b8392dcb3a"
      ]
    }
  }
}
```

## `payout.failed`

This webhook is triggered when a payout, the transfer of funds to the payee's bank account, fails. This may occur for several reasons, such as invalid account details, routing issues, or problems reported by the receiving financial institution.

```json title="Event"
{
  "event": "payout.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": {
    "payout": {
      "uuid": "8b2536c0-01c4-4699-8a97-b68eb8fb6b4f",
      "client_reference_id": "Payout_1784_1710950428",
      "entity": {
        "type": "merchant",
        "uuid": "5be9d011-b504-44d5-981f-0ec98ceab4c1"
      },
      "type": "individual",
      "status": "PAYOUT_COMPLETE",
      "trace_id": "ach_11jzp20wtve6z8",
      "amount": 3245,
      "speed": "standard",
      "sec_code": "ccd",
      "ach_return_code": null,
      "payout_failure_reason": null,
      "modality": {
        "payment_rail": "ach",
        "speed": "standard"
      },
      "bank_identifiers": {
        "debit_bank_id": "ach_11n4zxrp1twjebp",
        "debit_trace_id": "2145642244586478"
      },
      "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"
          }
        }
      },
      "failover": null,
      "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
      }
    },
    "relations": {
      "transaction_uuids": [
        "a6de4ae5-bec0-4466-b983-a8b8392dcb3a"
      ]
    }
  }
}
```

## `payout.completed`

This webhook is triggered each time a payout (transfer of funds to the payee) has been completed.

```json title="Event"
{
  "event": "payout.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": {
    "payout": {
      "uuid": "8b2536c0-01c4-4699-8a97-b68eb8fb6b4f",
      "client_reference_id": "Payout_1784_1710950428",
      "entity": {
        "type": "merchant",
        "uuid": "5be9d011-b504-44d5-981f-0ec98ceab4c1"
      },
      "type": "individual",
      "status": "PAYOUT_COMPLETE",
      "trace_id": "ach_11jzp20wtve6z8",
      "amount": 3245,
      "speed": "standard",
      "sec_code": "ccd",
      "ach_return_code": null,
      "payout_failure_reason": null,
      "modality": {
        "payment_rail": "ach",
        "speed": "standard"
      },
      "bank_identifiers": {
        "debit_bank_id": "ach_11n4zxrp1twjebp",
        "debit_trace_id": "2145642244586478"
      },
      "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"
          }
        }
      },
      "failover": null,
      "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
      }
    },
    "relations": {
      "transaction_uuids": [
        "a6de4ae5-bec0-4466-b983-a8b8392dcb3a"
      ]
    }
  }
}
```