Batch Refund Events

A batch refund is a single debit ACH from the processor’s bank account that funds a group of refunds at once. Batch refund events are used in integrations where the processor, rather than the original payee, is responsible for funding refund payouts, and give visibility into the moment refund funding is initiated for downstream reconciliation or tracking.

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

---

batch_refund.created

This webhook event is triggered when a debit ACH is initiated from the processor’s bank account to fund a batch of refunds. It signifies that GrailPay has begun collecting funds to fulfill refund requests that were previously grouped and approved for processing. This event is typically used in integrations where the processor, rather than the original payee, is responsible for funding the refund payouts. It ensures visibility into the moment refund funding is initiated, allowing for downstream reconciliation or tracking.

Event

{
  "event": "batch_refund.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": {
    "batch_refund": {
      "uuid": "",
      "amount": 10100,
      "refunds": [
        {
          "uuid": "9e77af94-0b25-4a6a-b86c-78b39f845659",
          "transaction_uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
          "client_reference_id": "refund",
          "status": "REFUND_COMPLETE",
          "amount": 170,
          "capture": {
            "trace_id": "ach_11n8xsq11wfpcde",
            "sec_code": "ccd",
            "ach_return_code": "R01",
            "bank_identifiers": {
              "debit_bank_id": "ach_11n4zxrp1twjebp",
              "debit_trace_id": "2145642244586478"
            },
            "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
            }
          },
          "payout": {
            "trace_id": "ach_11kxqh0a17ftg64",
            "sec_code": null,
            "ach_return_code": null,
            "bank_identifiers": {
              "debit_bank_id": "ach_11n4zxrp1twjebp",
              "debit_trace_id": "2145642244586478"
            },
            "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
            }
          },
          "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"
          },
          "batch": {
            "uuid": "32867d1a-2a81-4521-bd1b-b5d0a3a8df76",
            "refund_count": 4,
            "total_amount": 330
          }
        }
      ]
    }
  }
}