Fanvue API Documentation

Refunds and disputes use two resources: refund and dispute. Both are delivered in the Standard-Webhooks envelope; the fields below describe the data object. Every event requires the read:self scope.

Event (`type`)	Resource	Fires when
`app.refund.created`	refund	A one-time purchase is refunded, charged back, or cancelled
`app.payment.refunded`	refund	Deprecated alias of `app.refund.created` (see below)
`app.dispute.flagged`	dispute	An early chargeback warning is raised, before a formal dispute
`app.dispute.created`	dispute	A formal dispute (chargeback) is opened

These events cover one-time purchases only, identified by a purchase_reference with the appotp_ prefix. Subscription reversals and chargebacks are reconciled through the App Subscriptions endpoints, not these webhooks.

Refund resource

data.object is "refund". The refund references the original payment via payment_id, carries amount (not gross), and has no status or paid_at.

Field	Type	Description
`object`	string	Always `"refund"`
`id`	string	Fanvue invoice number for the refund
`payment_id`	string	Invoice number of the original payment
`amount`	integer	Refunded amount in minor units (positive)
`currency`	string \| null	ISO 4217 currency code
`reason`	string	`refund` \| `chargeback` \| `cancel`
`purchase_reference`	string	The one-time purchase reference (`appotp_` prefix)
`client_reference_id`	string \| null	Reserved passthrough reference (currently always `null`)
`created_at`	string \| null	ISO 8601 creation time
`item`	object	`{ uuid }` of the purchased pricing plan (`uuid` may be `null`)
`app`	object	`{ uuid }` of your app
`buyer`	object	`{ uuid }` of the buyer
`metadata`	object	Reserved passthrough metadata map (currently always empty)

Example: `app.refund.created`

{
  "id": "1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b",
  "type": "app.refund.created",
  "timestamp": "2026-06-18T09:30:00.000Z",
  "data": {
    "object": "refund",
    "id": "INV-2026-000456",
    "payment_id": "INV-2026-000123",
    "amount": 999,
    "currency": "USD",
    "reason": "refund",
    "purchase_reference": "appotp_3f9a2b71-1c4e-4f8a-9d2b-7c6e5a4b3d21",
    "client_reference_id": null,
    "created_at": "2026-06-18T09:29:58.000Z",
    "item": { "uuid": "b2d7c9f0-4a13-4e6b-8f25-1a9c3e7d5b80" },
    "app": { "uuid": "a1c3e5f7-9b2d-4c6e-8a0f-2d4b6c8e0a13" },
    "buyer": { "uuid": "c4e6a8b0-2d4f-6a81-0c2e-4b6d8f0a2c46" },
    "metadata": {}
  }
}

reason tells the three refund paths apart: refund (a normal refund), chargeback (a dispute resolved against the sale), and cancel (the purchase was cancelled).

app.payment.refunded is deprecated. It is the legacy alias of app.refund.created and is dual-emitted with an identical data body (only the type differs) during the migration window so existing integrations keep working. Subscribe to app.refund.created for new integrations; do not handle both, or you will double-count refunds.

Dispute resource

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

app.dispute.flagged is an early chargeback warning: 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. app.dispute.created is the formal dispute being opened, and the same payment can produce a flagged event and later a created event.

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 }`
`item`	object	`{ uuid }` of the purchased pricing plan (`uuid` may be `null`)
`app`	object	`{ uuid }` of your app
`buyer`	object	`{ uuid }` of the buyer
`metadata`	object	Reserved passthrough metadata map (currently always empty)

Example: `app.dispute.created`

{
  "id": "5f60718293a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7081920",
  "type": "app.dispute.created",
  "timestamp": "2026-06-19T08:41:00.000Z",
  "data": {
    "object": "dispute",
    "id": "dp_abc123",
    "status": "needs_response",
    "amount": 999,
    "currency": "USD",
    "reason": null,
    "source": "primer",
    "created_at": "2026-06-19T08:41:00.000Z",
    "payment": { "id": "INV-2026-000123", "transaction_id": "txn_abc" },
    "item": { "uuid": "b2d7c9f0-4a13-4e6b-8f25-1a9c3e7d5b80" },
    "app": { "uuid": "a1c3e5f7-9b2d-4c6e-8a0f-2d4b6c8e0a13" },
    "buyer": { "uuid": "c4e6a8b0-2d4f-6a81-0c2e-4b6d8f0a2c46" },
    "metadata": {}
  }
}

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

Reconciling

data.payment_id (refund) and data.payment.id (dispute) both carry the invoice number of the original payment, which you can re-read with the app payments endpoints. See Reconciliation.

Overview

Creator events

Checkout

App webhooks

Legacy events (deprecated)

App Refunds and Disputes

Refund resource

Example: `app.refund.created`

Dispute resource

Example: `app.dispute.created`

Reconciling

​Refund resource

​Example: app.refund.created

​Dispute resource

​Example: app.dispute.created

​Reconciling

Refund resource

Example: `app.refund.created`

Dispute resource

Example: `app.dispute.created`

Reconciling