Refund Events

Refund events are triggered when a refund is created, either for an invoice or an unapplied payment (such as through AR Advance). These events help you track the refund processing lifecycle.

Refund Status Overview

Refund statuses can be found in the webhook payload at resource.status. The following statuses indicate the current state of the refund:

Status	Description
created	The refund request has been created
processing	The refund request is currently being processed
paid	The refund has been successfully completed
failed	The refund was declined

Event: Refund Status — Created

This event is triggered when a refund request is first created.

{
  "object": "event",
  "id": "p2rnc1t4x25iknj1q2otrlu0",
  "resource": {
    "object": "refund",
    "id": "m4t1vcuytk1dibsr6ygu4dkn",
    "amount": "289.82",
    "currency": "USD",
    "settlementAmount": "289.82",
    "settlementCurrency": "USD",
    "paymentId": "0c2h0zkajp8ipfipmzca0qt6",
    "resourceId": "0c2h0zkajp8ipfipmzca0qt6",
    "resourceType": "Payment",
    "ownerId": "belg86nbs3ahqbq6a7sbn2ez",
    "status": "created",
    "created": "2025-07-14T22:42:00.000Z",
    "lastUpdated": "2025-07-14T22:42:00.000Z",
    "feesRefunded": false,
    "resource": {
      "object": "payment",
      "id": "0c2h0zkajp8ipfipmzca0qt6",
      "amount": 289.82,
      "currency": "USD",
      "payer": {
        "object": "payer",
        "id": "yl7d5pupdmqkhvbm337tzun1",
        "name": "Mercury Rising Technologies",
        "email": "uluna+psx@paystand.com",
        "externalId": "CUST-42974F02",
        "ownerId": "belg86nbs3ahqbq6a7sbn2ez",
        "status": "active",
        "created": "2025-05-15T21:42:58.000Z",
        "lastUpdated": "2025-05-20T23:55:31.000Z"
      },
      "source": {
        "object": "source",
        "id": "r81a3m1u0753k713xx5zklnl",
        "nameOnCard": "Juan",
        "brand": "visa",
        "last4": "4242",
        "status": "active"
      },
      "sourceType": "Card",
      "status": "paid"
    }
  },
  "diff": {
    "previous": {},
    "changes": {
      "object": "refund",
      "id": "m4t1vcuytk1dibsr6ygu4dkn",
      "amount": "289.82",
      "currency": "USD",
      "status": "created",
      "feesRefunded": false
    }
  },
  "sourceId": "m4t1vcuytk1dibsr6ygu4dkn",
  "sourceType": "Refund",
  "status": "active",
  "created": "2025-07-14T22:42:01.000Z",
  "lastUpdated": "2025-07-14T22:42:02.000Z"
}

Event: Refund Status — Processing

This event is triggered when a refund moves to processing status.

{
  "object": "event",
  "id": "utteqhgfxnsqpi6a9s5ak8nu",
  "resource": {
    "object": "refund",
    "id": "m4t1vcuytk1dibsr6ygu4dkn",
    "amount": "289.82",
    "currency": "USD",
    "settlementAmount": "289.82",
    "settlementCurrency": "USD",
    "paymentId": "0c2h0zkajp8ipfipmzca0qt6",
    "resourceId": "0c2h0zkajp8ipfipmzca0qt6",
    "resourceType": "Payment",
    "ownerId": "belg86nbs3ahqbq6a7sbn2ez",
    "status": "processing",
    "created": "2025-07-14T22:42:00.000Z",
    "lastUpdated": "2025-07-14T22:42:02.000Z",
    "feesRefunded": false
  },
  "diff": {
    "previous": {
      "status": "created",
      "lastUpdated": "2025-07-14T22:42:00.000Z"
    },
    "changes": {
      "status": "processing",
      "lastUpdated": "2025-07-14T22:42:02.000Z"
    }
  },
  "sourceId": "m4t1vcuytk1dibsr6ygu4dkn",
  "sourceType": "Refund",
  "status": "active"
}

Event: Refund Status — Paid

This event is triggered when a refund is successfully completed.

{
  "object": "event",
  "id": "kezgzx3ra6qmo79i4hbctmsv",
  "resource": {
    "object": "refund",
    "id": "m4t1vcuytk1dibsr6ygu4dkn",
    "amount": "289.82",
    "currency": "USD",
    "settlementAmount": "289.82",
    "settlementCurrency": "USD",
    "paymentId": "0c2h0zkajp8ipfipmzca0qt6",
    "resourceId": "0c2h0zkajp8ipfipmzca0qt6",
    "resourceType": "Payment",
    "ownerId": "belg86nbs3ahqbq6a7sbn2ez",
    "status": "paid",
    "created": "2025-07-14T22:42:00.000Z",
    "lastUpdated": "2025-07-14T22:42:08.000Z",
    "balanceChangeId": "xx3n6dzgihffmwv5aroolmca",
    "feesRefunded": false
  },
  "diff": {
    "previous": {
      "status": "processing",
      "lastUpdated": "2025-07-14T22:42:02.000Z"
    },
    "changes": {
      "status": "paid",
      "lastUpdated": "2025-07-14T22:42:08.000Z",
      "balanceChangeId": "xx3n6dzgihffmwv5aroolmca"
    }
  },
  "sourceId": "m4t1vcuytk1dibsr6ygu4dkn",
  "sourceType": "Refund",
  "status": "active"
}

Key Refund Event Fields

Field	Description
resource.id	Unique refund identifier
resource.amount	Refund amount in the specified currency
resource.currency	Currency code (USD, EUR, etc.)
resource.status	Current refund status
resource.paymentId	Original payment being refunded
resource.feesRefunded	Whether associated fees were also refunded
resource.balanceChangeId	Balance change ID when refund is completed
sourceType	Always "Refund" for refund events

Handling Refund Events

Best Practices

1. Use refund ID for idempotency: Track processed events using resource.id
2. Reference original payment: Use paymentId to link refunds to payments
3. Monitor fee refunds: Check feesRefunded for complete refund processing
4. Track completion: Use balanceChangeId to confirm processing completion
5. Handle status progression: Validate refund status transitions

Common Use Cases

• Customer notifications: Send refund confirmations when status becomes "paid"
• Accounting updates: Update financial records when refund is processed
• Inventory management: Restore inventory for refunded items
• Reporting: Track refund metrics and trends
• Dispute resolution: Handle refunds related to dispute cases