A few rules hold for every endpoint. Read them once and the field tables make more sense.
externalId is your own id for the record, such as your invoice or customer number. Send the same externalId again and Hyfin updates that record instead of creating a new one.
_id is Hyfin's id for the record, and every create returns it. Save it: payment webhooks refer to invoices by _id, and the 4.0 Get endpoints look records up by it.
Every amount in 4.0 is a whole number of cents, in requests and in responses. Send 4599 for $45.99. Payment webhooks use cents too for sites on webhook version 4.0, the default for new sites.
A Date field is a calendar day with no time, written YYYY-MM-DD, such as 2026-10-23. A time or time zone sent with it is dropped, not converted, so the date stays as written. Invoice responses return invoiceDate and dueDate as a timestamp at midnight UTC on that date, such as 2026-10-23T00:00:00.000Z.
A Timestamp field is a moment in time in ISO 8601, with milliseconds and a time zone: YYYY-MM-DDTHH:mm:ss.SSSZ, such as 2026-10-23T15:04:05.123Z. Responses return timestamps in UTC. The updated_after query parameter accepts only this exact format.
Your software owns customers, items, invoices and subscriptions. Send them to Hyfin when they are created or change. Hyfin owns payments: it takes them, then tells you through the payment webhook.
The payment webhook sends one call each time a payment reaches a new status, so one payment can arrive more than once, for example as captured and later as settled. Match on the payment's _id and update the payment you already have rather than adding a new one.