Skip to content
PGSwift Docs
Documentation/Migrating from V1

Migrating from V1

How to move a V1 webhook integration to the current webhook events.

The key structural difference between v1 and v2 is the unified envelope:

  • V1 payment — fields are at the root level of the payload (flat structure)
  • V1 disbursement — uses an { event, data } envelope (no timestamp)
  • V2 all events — always use { event, timestamp, data } — consistent across all event types

V2 keeps every v1 field, with the same name and type (amount is a string in both). The differences:

V1 event V2 event Fields added in V2
payment.completed payment.v2.completed payment_channel, payment_at, service_fee_rate_str, service_fee_amount_str, nett_amount_str
disbursement.completed disbursement.v2.completed (success), disbursement.v2.fail (fail), disbursement.v2.expired (expired) valid_account_name, reason, payment_at

V2 may add more fields later; each V2 event page lists its current fields. V2 also has transaction_settlement.settled, with no v1 equivalent.

To migrate:

  1. Register a new webhook for the corresponding v2 event name (e.g., payment.v2.completed)
  2. Update your handler to read fields from data.* instead of the root level (for payment events)
  3. Add handling for the new timestamp envelope field
  4. Verify the updated event string matches the v2 name
  5. Once confirmed working, you may unregister the v1 webhook