Fanvue API Documentation

Three events share the payment resource. They are delivered in the Standard-Webhooks envelope; the fields below describe the data object. Every event requires the read:self scope.

Event (`type`)	Fires when
`app.payment.pending`	A charge is created and awaiting confirmation
`app.payment.succeeded`	A charge succeeds
`app.payment.failed`	A charge fails

app.payment.* events cover both one-time purchases and subscription charges; branch on billing_reason to tell them apart. The money and the access state are separate events: a subscription’s initial charge emits both app.payment.succeeded (with billing_reason: subscription_initial) and app.subscription.activated.

Payment resource

data.object is "payment" for all three events.

Field	Type	Description
`object`	string	Always `"payment"`
`id`	string	Fanvue invoice number for the payment
`status`	string	`pending` \| `succeeded` \| `failed`
`billing_reason`	string	`one_time` \| `subscription_initial` \| `subscription_renewal`
`gross`	integer	Gross amount in minor units
`currency`	string \| null	ISO 4217 currency code
`reason`	string \| null	Decline / failure message on `failed`; `null` for `pending` and `succeeded`
`purchase_reference`	string	The `appotp_` purchase reference for a one-time purchase, or the subscription’s billing reference otherwise
`client_reference_id`	string \| null	Reserved passthrough reference (currently always `null`)
`created_at`	string \| null	ISO 8601 creation time
`paid_at`	string \| null	ISO 8601 time the payment was paid (`null` until paid)
`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)

Examples

`app.payment.succeeded` (subscription initial charge)

{
  "id": "9f2c1e7a4b8d6f30a1c2e3d4b5a6978c0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b",
  "type": "app.payment.succeeded",
  "timestamp": "2026-06-17T13:12:45.123Z",
  "data": {
    "object": "payment",
    "id": "INV-2026-000123",
    "status": "succeeded",
    "billing_reason": "subscription_initial",
    "gross": 999,
    "currency": "USD",
    "reason": null,
    "purchase_reference": "sub_3f9a2b71-1c4e-4f8a-9d2b-7c6e5a4b3d21",
    "client_reference_id": null,
    "created_at": "2026-06-17T13:12:40.000Z",
    "paid_at": "2026-06-17T13:12:44.880Z",
    "item": { "uuid": "b2d7c9f0-4a13-4e6b-8f25-1a9c3e7d5b80" },
    "app": { "uuid": "a1c3e5f7-9b2d-4c6e-8a0f-2d4b6c8e0a13" },
    "buyer": { "uuid": "c4e6a8b0-2d4f-6a81-0c2e-4b6d8f0a2c46" },
    "metadata": {}
  }
}

A one-time purchase looks the same with "billing_reason": "one_time" and a purchase_reference carrying the appotp_ prefix; a renewal uses "billing_reason": "subscription_renewal".

`app.payment.pending`

{
  "id": "1b2c3d4e5f60718293a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6",
  "type": "app.payment.pending",
  "timestamp": "2026-06-17T13:12:40.500Z",
  "data": {
    "object": "payment",
    "id": "INV-2026-000123",
    "status": "pending",
    "billing_reason": "one_time",
    "gross": 999,
    "currency": "USD",
    "reason": null,
    "purchase_reference": "appotp_3f9a2b71-1c4e-4f8a-9d2b-7c6e5a4b3d21",
    "client_reference_id": null,
    "created_at": "2026-06-17T13:12:40.000Z",
    "paid_at": null,
    "item": { "uuid": "b2d7c9f0-4a13-4e6b-8f25-1a9c3e7d5b80" },
    "app": { "uuid": "a1c3e5f7-9b2d-4c6e-8a0f-2d4b6c8e0a13" },
    "buyer": { "uuid": "c4e6a8b0-2d4f-6a81-0c2e-4b6d8f0a2c46" },
    "metadata": {}
  }
}

`app.payment.failed`

{
  "id": "2c3d4e5f60718293a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7",
  "type": "app.payment.failed",
  "timestamp": "2026-06-17T13:12:45.000Z",
  "data": {
    "object": "payment",
    "id": "INV-2026-000123",
    "status": "failed",
    "billing_reason": "subscription_renewal",
    "gross": 999,
    "currency": "USD",
    "reason": "card_declined",
    "purchase_reference": "sub_3f9a2b71-1c4e-4f8a-9d2b-7c6e5a4b3d21",
    "client_reference_id": null,
    "created_at": "2026-06-17T13:12:40.000Z",
    "paid_at": null,
    "item": { "uuid": "b2d7c9f0-4a13-4e6b-8f25-1a9c3e7d5b80" },
    "app": { "uuid": "a1c3e5f7-9b2d-4c6e-8a0f-2d4b6c8e0a13" },
    "buyer": { "uuid": "c4e6a8b0-2d4f-6a81-0c2e-4b6d8f0a2c46" },
    "metadata": {}
  }
}

Reconciling

Payments can be re-read by invoice number: data.id matches the invoiceNumber path parameter on the app payments endpoints. See Reconciliation.

Overview

Creator events

Checkout

App webhooks

Legacy events (deprecated)

App Payment Events

Payment resource

Examples

`app.payment.succeeded` (subscription initial charge)

`app.payment.pending`

`app.payment.failed`

Reconciling

​Payment resource

​Examples

​app.payment.succeeded (subscription initial charge)

​app.payment.pending

​app.payment.failed

​Reconciling

Payment resource

Examples

`app.payment.succeeded` (subscription initial charge)

`app.payment.pending`

`app.payment.failed`

Reconciling