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 (notimestamp) - 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:
- Register a new webhook for the corresponding v2 event name (e.g.,
payment.v2.completed) - Update your handler to read fields from
data.*instead of the root level (for payment events) - Add handling for the new
timestampenvelope field - Verify the updated
eventstring matches the v2 name - Once confirmed working, you may unregister the v1 webhook