Webhooks > Payment

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 and failed refunds are not sent unless your integration is configured to receive them.

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.

Sample Webhook Payload - Successful Payment

			
{
  "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:28Z",
    "status": "captured",
    "allocations": [
      {
        "ref_type": "Invoice",
        "ref": "649dc5bb468bd5b5d863c7d2",
        "amount": 3300
      }
    ],
    "payment_transaction_events": [
      {
        "type": "sale",
        "amount": 4964,
        "successful": true,
        "created_at": "2026-05-13T19:29:28Z",
        "transaction_id": "32483237915423321"
      }
    ]
  }
}

Data Types

			
type PaymentType = "payment_card" | "ach" | "eft" | "apple_pay" | "google_pay" | "oxxo" | "spei" | "bnpl" | "dlocal" | "cash" | "check" | "other"

type PaymentSubType = "visa" | "mastercard" | "amex" | "discover" | "diners" | "jcb" | "checking" | "savings" | "oxxo" | "spei" | "bnpl" | "google_pay" | "dlocal" | "cash" | "check" | "other"

type PaymentStatus = "failed" | "declined" | "created" | "expired" | "cancelled" | "authorized" | "captured" | "voided" | "settled" | "returned" | "refundFailed" | "refunded" | "refundSettled" | "chargebacked" | "refundRequested"

type PaymentTransactionEventType = "create" | "verify" | "auth" | "cancel" | "expire" | "decline" | "void" | "capture" | "sale" | "return" | "batch" | "settle" | "refund" | "chargeback" | "misc" | "activatePaymentDevice"