# Reverse Payout Events

Reverse payout events are emitted when GrailPay must return funds to the original payor because a payout to the intended payee could not be completed. This can happen due to reasons like an invalid or closed bank account, or a failed delivery attempt after the payout was initiated.

These events help your platform stay aligned with the refund and reconciliation flow for failed disbursements. GrailPay emits events when a reverse payout is created (`reverse_payout.created`) or cancelled (`reverse_payout.cancelled`), when its ACH begins processing (`reverse_payout.processing`), and when it fails or completes (`reverse_payout.failed`, `reverse_payout.completed`). These allow you to track the full lifecycle of the reversal, update transaction statuses, and notify relevant users or systems of the outcome.

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

***

## `reverse_payout.created`

This webhook is triggered when a reverse payout (reversal of an undeliverable payout) is created.

```json title="Event"
{
  "event": "reverse_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": {
    "reverse_payout": {
      "uuid": "bc4abcaf-2adf-4d4d-b843-0d44175b250c",
      "status": "REVERSE_PAYOUT_PENDING",
      "amount": 10500,
      "sec_code": "ccd",
      "ach_return_code": null,
      "cancel_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"
          }
        }
      },
      "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"
          }
        }
      },
      "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": {
      "payout": {
        "uuid": "d1c3a7e2-5b8f-4f26-9a6a-6c2e0c4b9f52"
      },
      "transaction": {
        "uuid": "4a9f2d71-8e3c-4b65-a1f7-2f6d0c9b8a34"
      }
    }
  }
}
```

## `reverse_payout.cancelled`

This webhook is triggered when a reverse payout (reversal of an undeliverable payout) is cancelled.

```json title="Event"
{
  "event": "reverse_payout.cancelled",
  "event_uuid": "019f4d4c-3f00-7c1e-9a21-0123456789ab",
  "event_occurred_at": "2026-10-06 19:32:21",
  "event_version": 3,
  "vendor_uuid": "019e2711-5a92-735d-a7d5-669aec76b54f",
  "data": {
    "reverse_payout": {
      "uuid": "bc4abcaf-2adf-4d4d-b843-0d44175b250c",
      "status": "REVERSE_PAYOUT_PENDING",
      "trace_id": "ach_7kp2nxw9m4qr1bt",
      "amount": 10500,
      "sec_code": "ccd",
      "ach_return_code": null,
      "cancel_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"
          }
        }
      },
      "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"
          }
        }
      },
      "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": {
      "payout": {
        "uuid": "d1c3a7e2-5b8f-4f26-9a6a-6c2e0c4b9f52"
      },
      "transaction": {
        "uuid": "4a9f2d71-8e3c-4b65-a1f7-2f6d0c9b8a34"
      }
    }
  }
}
```

## `reverse_payout.processing`

This webhook is triggered when the ACH for a reverse payout (reversal of an undeliverable payout) has begun processing.

```json title="Event"
{
  "event": "reverse_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": {
    "reverse_payout": {
      "uuid": "bc4abcaf-2adf-4d4d-b843-0d44175b250c",
      "status": "REVERSE_PAYOUT_PENDING",
      "amount": 10500,
      "sec_code": "ccd",
      "ach_return_code": null,
      "cancel_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"
          }
        }
      },
      "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"
          }
        }
      },
      "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": {
      "payout": {
        "uuid": "d1c3a7e2-5b8f-4f26-9a6a-6c2e0c4b9f52"
      },
      "transaction": {
        "uuid": "4a9f2d71-8e3c-4b65-a1f7-2f6d0c9b8a34"
      }
    }
  }
}
```

## `reverse_payout.failed`

This webhook is triggered when the ACH for a reverse payout (reversal of an undeliverable payout) has failed.

```json title="Event"
{
  "event": "reverse_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": {
    "reverse_payout": {
      "uuid": "bc4abcaf-2adf-4d4d-b843-0d44175b250c",
      "status": "REVERSE_PAYOUT_PENDING",
      "amount": 10500,
      "sec_code": "ccd",
      "ach_return_code": null,
      "cancel_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"
          }
        }
      },
      "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"
          }
        }
      },
      "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": {
      "payout": {
        "uuid": "d1c3a7e2-5b8f-4f26-9a6a-6c2e0c4b9f52"
      },
      "transaction": {
        "uuid": "4a9f2d71-8e3c-4b65-a1f7-2f6d0c9b8a34"
      }
    }
  }
}
```

## `reverse_payout.completed`

This webhook is triggered when the ACH for a reverse payout (reversal of an undeliverable payout) has completed.

```json title="Event"
{
  "event": "reverse_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": {
    "reverse_payout": {
      "uuid": "bc4abcaf-2adf-4d4d-b843-0d44175b250c",
      "status": "REVERSE_PAYOUT_PENDING",
      "amount": 10500,
      "sec_code": "ccd",
      "ach_return_code": null,
      "cancel_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"
          }
        }
      },
      "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"
          }
        }
      },
      "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": {
      "payout": {
        "uuid": "d1c3a7e2-5b8f-4f26-9a6a-6c2e0c4b9f52"
      },
      "transaction": {
        "uuid": "4a9f2d71-8e3c-4b65-a1f7-2f6d0c9b8a34"
      }
    }
  }
}
```