Processor Payout Events

Processor payout events are triggered throughout the lifecycle of payouts initiated on behalf of a specific processor. Unlike standard payouts, processor payouts are always processed in batches, allowing multiple payouts to be grouped and executed together.

GrailPay emits webhook events for each milestone in the processor payout process: when its transfer begins processing (processor_payout.processing), and when it completes or fails (processor_payout.completed, processor_payout.failed). These events enable your platform to monitor payout progress, reconcile processor-level transactions, and respond promptly to any issues that arise during processing.

All payloads below are shown in full, including the event envelope.

---

processor_payout.processing

This webhook is triggered when the transfer for a processor payout has begun processing.

Event

{
  "event": "processor_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": {
    "processor_payout": {
      "uuid": "8b2536c0-01c4-4699-8a97-b68eb8fb6b4f",
      "type": "batch",
      "status": "PENDING",
      "trace_id": "ach_11jzp20wtve6z8",
      "amount": 5278900,
      "ach_return_code": null,
      "ledger_shared": false,
      "modality": {
        "payment_rail": "ach",
        "speed": "standard"
      },
      "bank_identifiers": {
        "debit_bank_id": "ach_11n4zxrp1twjebp",
        "debit_trace_id": "2145642244586478"
      },
      "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"
      ]
    }
  }
}

processor_payout.failed

This webhook is triggered when the transfer for a processor payout has failed.

Event

{
  "event": "processor_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": {
    "processor_payout": {
      "uuid": "8b2536c0-01c4-4699-8a97-b68eb8fb6b4f",
      "type": "batch",
      "status": "PENDING",
      "trace_id": "ach_11jzp20wtve6z8",
      "amount": 5278900,
      "ach_return_code": null,
      "ledger_shared": false,
      "modality": {
        "payment_rail": "ach",
        "speed": "standard"
      },
      "bank_identifiers": {
        "debit_bank_id": "ach_11n4zxrp1twjebp",
        "debit_trace_id": "2145642244586478"
      },
      "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"
      ]
    }
  }
}

processor_payout.completed

This webhook is triggered when the transfer for a processor payout has completed.

Event

{
  "event": "processor_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": {
    "processor_payout": {
      "uuid": "8b2536c0-01c4-4699-8a97-b68eb8fb6b4f",
      "type": "batch",
      "status": "PENDING",
      "trace_id": "ach_11jzp20wtve6z8",
      "amount": 5278900,
      "ach_return_code": null,
      "ledger_shared": false,
      "modality": {
        "payment_rail": "ach",
        "speed": "standard"
      },
      "bank_identifiers": {
        "debit_bank_id": "ach_11n4zxrp1twjebp",
        "debit_trace_id": "2145642244586478"
      },
      "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"
      ]
    }
  }
}