Use this when your system should mark an invoice paid the moment the customer pays.
To find the invoice a payment paid, read allocations[].ref . It is the invoice _id that Add/Update Invoice returned when you created the invoice, so save that _id next to your own record.
When a payment on an invoice reaches a new status in the Hyfin application, the webhook will be called and the following data format will be POSTED to the provided webhook URL. Each status is sent once per payment, so a payment that is captured and later settled produces two calls, distinguished by the status field. Declined payments and failed refunds are not sent by default. To receive them, ask Hyfin to turn them on for your app.
A refund is sent as its own payment, with is_refund set to true and orig_payment set to the _id of the payment it refunded.
Webhook payloads use snake_case keys, unlike the camelCase used by the 4.0 API itself. Amounts are integer cents.
This 4.0 shape is sent only to sites whose webhook version is set to 4.0, which is the default for newly created sites. A site left on an earlier webhook version keeps receiving the older payload, where amounts are decimal dollars.
{
"action": "payment",
"data": {
"_id": "6385807aa90735097a811cf6",
"display_name": "VISA **** 5123",
"site": "6201825a0cf5e23261a08646",
"customer": "649dc5bb468bd5b5d863c7d1",
"type": "payment_card",
"sub_type": "visa",
"amount": 4964,
"totals": {
"subtotal": 3000,
"taxes": 300,
"total": 3300,
"extra_fees": 1164,
"tips": 500
},
"paid_on": "2026-05-13T19:29:28.000Z",
"status": "captured",
"is_refund": false,
"allocations": [
{
"ref_type": "Invoice",
"ref": "649dc5bb468bd5b5d863c7d2",
"amount": 3300
}
],
"payment_transaction_events": [
{
"type": "sale",
"amount": 4964,
"successful": true,
"created_at": "2026-05-13T19:29:28.000Z",
"transaction_id": "32483237915423321"
}
]
}
}