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.

---

payout.processing

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

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.

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.

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"
      ]
    }
  }
}