> ## Documentation Index
> Fetch the complete documentation index at: https://api.fanvue.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Checkout Refunds and Disputes

> Reference for refund.created, dispute.flagged, and dispute.created webhook events fired on Fanvue checkout-link payments, with payload fields.

These events tell you when money is returned or contested. They are delivered in
the [Standard-Webhooks envelope](/docs/checkout/overview#event-envelope); the
fields below describe the `data` object.

| Event (`type`)                  | Resource | Fires when                                                     |
| ------------------------------- | -------- | -------------------------------------------------------------- |
| `checkout_link.refund.created`  | refund   | A checkout payment is refunded                                 |
| `checkout_link.dispute.flagged` | dispute  | An early chargeback warning is raised, before a formal dispute |
| `checkout_link.dispute.created` | dispute  | A formal dispute (chargeback) is opened                        |

## Refund resource

<Note>
  Fanvue reverses the **entire** original payment (partial card refunds are not
  modeled), so `full_amount` is always `true` and `amount` equals the original
  gross.
</Note>

| Field                 | Type           | Description                                                  |
| --------------------- | -------------- | ------------------------------------------------------------ |
| `object`              | string         | Always `"refund"`                                            |
| `id`                  | string         | Reversal invoice number (e.g. `FVC-12345`)                   |
| `payment_id`          | string         | Invoice number of the original (refunded) payment            |
| `amount`              | integer        | Refunded amount in minor units (positive)                    |
| `currency`            | string \| null | ISO 4217 currency code                                       |
| `reason`              | string \| null | Refund reason, if recorded                                   |
| `full_amount`         | boolean        | Always `true`                                                |
| `created_at`          | string \| null | ISO 8601 time the refund was created                         |
| `client_reference_id` | string \| null | Your passthrough reference, copied from the original payment |
| `checkout_link`       | object         | `{ uuid, name, product_uuid, product_price_uuid }`           |
| `purchaser`           | object         | `{ uuid, email }` of the buyer (`email` may be `null`)       |
| `creator`             | object         | `{ uuid }` of the creator                                    |
| `metadata`            | object         | Your passthrough metadata map                                |

### Example: `checkout_link.refund.created`

```json theme={null}
{
  "id": "f1a2b3c4-5555-4a2b-9c3d-aaaaaaaaaaaa",
  "type": "checkout_link.refund.created",
  "timestamp": "2026-06-09T08:40:00.000Z",
  "data": {
    "object": "refund",
    "id": "FVC-12345",
    "payment_id": "FV-12345",
    "amount": 9999,
    "currency": "USD",
    "reason": null,
    "full_amount": true,
    "created_at": "2026-06-09T08:40:00.000Z",
    "client_reference_id": "your-crm-id-123",
    "checkout_link": {
      "uuid": "ck-uuid",
      "name": "VIP Monthly",
      "product_uuid": "prod-uuid",
      "product_price_uuid": "pp-uuid"
    },
    "purchaser": { "uuid": "fan-uuid", "email": "fan@example.com" },
    "creator": { "uuid": "creator-uuid" },
    "metadata": { "affiliate_id": "aff_123", "campaign": "spring" }
  }
}
```

## Dispute resource

Both `dispute.flagged` (an early warning, before a formal chargeback) and
`dispute.created` (the formal chargeback) share the `dispute` resource. Use
`source` to identify the provider that reported it.

<Note>
  `checkout_link.dispute.flagged` is an **early chargeback warning**: the card
  network or a partner has signalled that a dispute is likely, but no formal
  chargeback has been filed yet. Treat it as a heads-up to prepare evidence or
  pre-emptively refund. `checkout_link.dispute.created` is the **formal
  dispute** being opened against the payment, and the same payment can produce a
  `flagged` event and later a `created` event.
</Note>

| Field        | Type            | Description                                                              |
| ------------ | --------------- | ------------------------------------------------------------------------ |
| `object`     | string          | Always `"dispute"`                                                       |
| `id`         | string          | Processor dispute / alert id                                             |
| `status`     | string \| null  | Processor status (e.g. `needs_response`)                                 |
| `amount`     | integer \| null | Disputed amount in minor units                                           |
| `currency`   | string \| null  | ISO 4217 currency code                                                   |
| `reason`     | string \| null  | Dispute reason, if provided                                              |
| `source`     | string          | `chargeback_help` \| `primer`                                            |
| `created_at` | string \| null  | ISO 8601 time the dispute was reported                                   |
| `payment`    | object          | The disputed payment: `{ id, transaction_id, checkout_link, purchaser }` |
| `creator`    | object          | `{ uuid }` of the creator                                                |
| `metadata`   | object          | Your passthrough metadata map                                            |

### Example: `checkout_link.dispute.created`

```json theme={null}
{
  "id": "f1a2b3c4-7777-4a2b-9c3d-aaaaaaaaaaaa",
  "type": "checkout_link.dispute.created",
  "timestamp": "2026-06-09T08:41:00.000Z",
  "data": {
    "object": "dispute",
    "id": "dp_abc123",
    "status": "needs_response",
    "amount": 9999,
    "currency": "USD",
    "reason": null,
    "source": "primer",
    "created_at": "2026-06-09T08:41:00.000Z",
    "payment": {
      "id": "FV-12345",
      "transaction_id": "txn_abc",
      "checkout_link": {
        "uuid": "ck-uuid",
        "name": "VIP Monthly",
        "product_uuid": "prod-uuid",
        "product_price_uuid": "pp-uuid"
      },
      "purchaser": { "uuid": "fan-uuid", "email": "fan@example.com" }
    },
    "creator": { "uuid": "creator-uuid" },
    "metadata": { "affiliate_id": "aff_123", "campaign": "spring" }
  }
}
```

The `checkout_link.dispute.flagged` event uses the identical shape with
`"type": "checkout_link.dispute.flagged"`; treat it as an early heads-up to
prepare evidence before a formal chargeback is filed.