Skip to content
GrailPay GrailPay GrailPay
Select theme

Clawback Events

Clawbacks occur when a transaction that has already been disbursed to the payee fails, often due to insufficient funds, a return from the receiving bank, or a rejection by the ACH network. In such cases, GrailPay initiates a payout return to recover the funds, which is referred to as a clawback. These events are crucial for maintaining the integrity of your payment workflows, ensuring that failed disbursements are properly tracked and reconciled.

GrailPay emits a series of webhook events throughout the clawback lifecycle: when a clawback record is created (clawback.created), when its ACH debit begins processing (clawback.processing), when it fails (clawback.failed), and when it completes (clawback.completed). By subscribing to these events, you can monitor failed transactions in real time, update internal records, trigger customer notifications, or pause related operations until resolution.

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

clawback.created

Section titled “clawback.created”

This webhook is triggered when a payout return (clawback) has been initiated by the GrailPay system, but the ACH debit has not been created. A clawback is required when a transaction fails (e.g., due to an ACH return) after the payout (credit) has already been disbursed to the recipient.

Event
{
  "event": "clawback.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": {
    "clawback": {
      "uuid": "8f5a6e9d-2c41-4f90-bb3f-9e8a9a3b7f1c",
      "status": "CLAWBACK_ACH_PENDING",
      "amount": 15000,
      "sec_code": "ccd",
      "clawback_type": "transaction",
      "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"
          }
        }
      },
      "ach_return_code": null,
      "delay_days": 2,
      "trace_id": "ach_7r9m2f4q8xk1c6v",
      "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": {
      "payout": {
        "uuid": "d1c3a7e2-5b8f-4f26-9a6a-6c2e0c4b9f52"
      },
      "transaction": {
        "uuid": "4a9f2d71-8e3c-4b65-a1f7-2f6d0c9b8a34"
      }
    }
  }
}

clawback.processing

Section titled “clawback.processing”

This webhook is triggered when the ACH debit for a payout return (clawback) has begun processing.

Event
{
  "event": "clawback.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": {
    "clawback": {
      "uuid": "8f5a6e9d-2c41-4f90-bb3f-9e8a9a3b7f1c",
      "status": "CLAWBACK_ACH_PENDING",
      "amount": 15000,
      "sec_code": "ccd",
      "clawback_type": "transaction",
      "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"
          }
        }
      },
      "ach_return_code": null,
      "delay_days": 2,
      "trace_id": "ach_7r9m2f4q8xk1c6v",
      "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": {
      "payout": {
        "uuid": "d1c3a7e2-5b8f-4f26-9a6a-6c2e0c4b9f52"
      },
      "transaction": {
        "uuid": "4a9f2d71-8e3c-4b65-a1f7-2f6d0c9b8a34"
      }
    }
  }
}

clawback.failed

Section titled “clawback.failed”

This webhook is triggered when a payout return (clawback) attempt fails within the GrailPay system.

Event
{
  "event": "clawback.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": {
    "clawback": {
      "uuid": "8f5a6e9d-2c41-4f90-bb3f-9e8a9a3b7f1c",
      "status": "CLAWBACK_ACH_PENDING",
      "amount": 15000,
      "sec_code": "ccd",
      "clawback_type": "transaction",
      "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"
          }
        }
      },
      "ach_return_code": null,
      "delay_days": 2,
      "trace_id": "ach_7r9m2f4q8xk1c6v",
      "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": {
      "payout": {
        "uuid": "d1c3a7e2-5b8f-4f26-9a6a-6c2e0c4b9f52"
      },
      "transaction": {
        "uuid": "4a9f2d71-8e3c-4b65-a1f7-2f6d0c9b8a34"
      }
    }
  }
}

clawback.completed

Section titled “clawback.completed”

This webhook is triggered when the payout return (clawback) has been successfully debited from the original payee’s account.

Event
{
  "event": "clawback.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": {
    "clawback": {
      "uuid": "8f5a6e9d-2c41-4f90-bb3f-9e8a9a3b7f1c",
      "status": "CLAWBACK_ACH_PENDING",
      "amount": 15000,
      "sec_code": "ccd",
      "clawback_type": "transaction",
      "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"
          }
        }
      },
      "ach_return_code": null,
      "delay_days": 2,
      "trace_id": "ach_7r9m2f4q8xk1c6v",
      "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": {
      "payout": {
        "uuid": "d1c3a7e2-5b8f-4f26-9a6a-6c2e0c4b9f52"
      },
      "transaction": {
        "uuid": "4a9f2d71-8e3c-4b65-a1f7-2f6d0c9b8a34"
      }
    }
  }
}

Maintained by EkLine