Fee Events

Fee events are triggered when merchant fees for payments are reported by banking partners. This can occur a few hours after the payment is processed, as the actual fee amount is confirmed.

This applies to credit card payments, as each credit card fee can vary depending on its different tier (classic, platinum, etc).

When this happens, the feeType value changes from delayed to paystand, indicating the fee has been finalized.

Fee Status and Type Overview

Fee events have a status of "active" at resource.status. The fee type indicates the processing stage and can be found at resource.feeType:

Fee Type	Description
delayed	A fee event is sent with feeType = "delayed" when a delayed fee applies
paystand	The fee has been confirmed and processed by our banking partner. The feeType changes to "paystand"

Key Parameters

Parameter	Description
resource.amount	The merchant fee charged for this payment (e.g., 7.52)
resource.resourceAmount	The total amount paid by the payer (e.g., 289.82)
resource.currency	The currency in which the merchant fee was charged (e.g., USD)
resource.resource.id	The Payment ID associated with the fee
resource.resource.payerId	The Payer ID who made the payment
resource.resource.ownerId	The Merchant ID who received the payment

Event: Fee Status — Delayed

This event is triggered when a delayed fee is initially applied to a payment.

{
  "object": "event",
  "id": "kd1sp2kmn5p5or9d4n4hz798",
  "resource": {
    "object": "fee",
    "id": "osqfwkey615cjvzmvbx43hsf",
    "resourceAmount": "4.00",
    "currency": "USD",
    "feeType": "delayed",
    "resource": {
      "object": "payment",
      "id": "2w17pq7m168pmdpiczsruzud",
      "amount": "4.00",
      "currency": "USD",
      "status": "created",
      "ownerId": "f9r71ngfb6iymkupqkvm1ek8",
      "created": "2025-07-03T22:25:54.000Z",
      "lastUpdated": "2025-07-03T22:25:54.000Z",
      "payerId": "6buwtdydxa2bm4uitwts0g4s"
    },
    "status": "active",
    "created": "2025-07-03T22:25:54.000Z",
    "lastUpdated": "2025-07-03T22:25:54.000Z"
  },
  "diff": {
    "previous": {},
    "changes": {
      "object": "fee",
      "id": "osqfwkey615cjvzmvbx43hsf",
      "feeType": "delayed",
      "status": "active"
    }
  },
  "sourceId": "osqfwkey615cjvzmvbx43hsf",
  "sourceType": "Fee",
  "status": "active"
}

Event: Fee Status — Paystand

This event is triggered when the actual fee amount is confirmed by the banking partner.

{
  "object": "event",
  "id": "3odtdl6uvhp9p5ptxjs7x77q",
  "resource": {
    "object": "fee",
    "id": "vazuei5mtmompl35sdljh37n",
    "amount": "7.52",
    "resourceAmount": "289.82",
    "currency": "USD",
    "feeType": "paystand",
    "resource": {
      "object": "payment",
      "id": "0c2h0zkajp8ipfipmzca0qt6",
      "amount": "289.82",
      "currency": "USD",
      "status": "created",
      "ownerId": "belg86nbs3ahqbq6a7sbn2ez",
      "created": "2025-07-11T21:34:51.000Z",
      "lastUpdated": "2025-07-11T21:34:51.000Z",
      "payerId": "yl7d5pupdmqkhvbm337tzun1"
    },
    "status": "active",
    "created": "2025-07-11T21:34:54.000Z",
    "lastUpdated": "2025-07-11T21:34:54.000Z"
  },
  "diff": {
    "previous": {
      "feeType": "delayed"
    },
    "changes": {
      "amount": "7.52",
      "feeType": "paystand",
      "lastUpdated": "2025-07-11T21:34:54.000Z"
    }
  },
  "sourceId": "vazuei5mtmompl35sdljh37n",
  "sourceType": "Fee",
  "status": "active"
}

Key Fee Event Fields

Field	Description
resource.id	Unique fee identifier
resource.amount	Final merchant fee amount (only present when feeType is "paystand")
resource.resourceAmount	Original payment amount the fee applies to
resource.currency	Currency code
resource.feeType	Fee type ("delayed" or "paystand")
resource.resource.id	Payment ID this fee applies to
resource.resource.ownerId	Merchant ID
resource.resource.payerId	Payer ID
sourceType	Always "Fee" for fee events

Handling Fee Events

Best Practices

1. Use fee ID for idempotency: Track processed events using resource.id
2. Link to payments: Use resource.resource.id to associate fees with payments
3. Handle delayed fees: Be prepared for fees to be updated after initial payment
4. Update accounting: Adjust fee amounts when feeType changes to "paystand"
5. Monitor fee calculations: Verify fee amounts match expected calculations

Common Use Cases

• Cost accounting: Track actual merchant fees for each payment
• Profit calculation: Calculate net revenue after fees
• Financial reporting: Include actual fees in financial reports
• Reconciliation: Match fee amounts with processor statements
• Pricing analysis: Analyze fee costs across different payment methods

Fee Type Transitions

Typical flow:

1. Payment is processed → Fee event with feeType: "delayed" (no amount yet)
2. Banking partner confirms fee → Fee event with feeType: "paystand" and actual amount

Important Notes:

• Not all payments will have delayed fees
• Some fees may be calculated immediately
• Always use the most recent fee event for accurate amounts
• Fee amounts are only reliable when feeType: "paystand"