Fanvue API Documentation

Three events share the payment resource. They are delivered in the Standard-Webhooks envelope; the fields below describe the data object.

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

checkout_link.payment.succeeded covers one-off purchases, initial subscription payments, and renewals. Branch on billing_reason to tell them apart.

Payment resource

Field	Type	Description
`object`	string	Always `"payment"`
`id`	string	Fanvue invoice number (e.g. `FV-12345`)
`status`	string	`pending` \| `succeeded` \| `failed`
`billing_reason`	string	`one_time` \| `subscription_initial` \| `subscription_renewal`
`gross`	integer	Gross amount in minor units
`net`	integer \| null	Creator net after fees, in minor units
`fees`	object	`{ fanvue_fee, transaction_fee }` in minor units (each may be `null`)
`currency`	string \| null	ISO 4217 currency code
`paid_in_full`	boolean	Whether the full amount has been collected (see BNPL installments)
`installment`	object \| null	`{ number, of }` for a BNPL financed sale; `null` for a normal payment
`subscription`	object \| null	`{ uuid }` when the payment is tied to a subscription
`client_reference_id`	string \| null	Your passthrough reference (see Attribution)
`transaction_id`	string \| null	Processor transaction id
`created_at`	string \| null	ISO 8601 creation time
`paid_at`	string \| null	ISO 8601 time the payment was paid (`null` until paid)
`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

BNPL installments

When a fan finances a purchase with Buy Now, Pay Later (BNPL), Fanvue is paid upfront, so the sale still arrives as a single checkout_link.payment.succeeded. The only difference is that it is marked as a financed sale:

paid_in_full is false, and
installment is { "number": 1, "of": N } (the first of N installments).

The fan’s later repayments (installments 2..N) are financing movement, not new Fanvue sales. Fanvue has already been paid. Those repayments arrive as checkout_link.installment.paid / .failed events, not as further payment.succeeded events, and the plan finishing emits checkout_link.plan.completed. For a normal (non-financed) payment, installment is null and paid_in_full is true once collected.

Examples

`checkout_link.payment.succeeded`

{
  "id": "f1a2b3c4-1111-4a2b-9c3d-aaaaaaaaaaaa",
  "type": "checkout_link.payment.succeeded",
  "timestamp": "2026-06-09T08:39:33.139Z",
  "data": {
    "object": "payment",
    "id": "FV-12345",
    "status": "succeeded",
    "billing_reason": "subscription_initial",
    "gross": 9999,
    "net": 8000,
    "fees": { "fanvue_fee": 1500, "transaction_fee": 499 },
    "currency": "USD",
    "paid_in_full": true,
    "installment": null,
    "subscription": { "uuid": "sub-uuid" },
    "client_reference_id": "your-crm-id-123",
    "transaction_id": "txn_abc",
    "created_at": "2026-06-09T08:39:30.000Z",
    "paid_at": "2026-06-09T08:39:33.000Z",
    "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" }
  }
}

`checkout_link.payment.succeeded` (BNPL financed sale)

The initial financed sale carries paid_in_full: false and installment: { number: 1, of: N }. gross is the full sale amount; currency is what the fan is charged (the processing currency). Repayments 2..N then arrive as installment events.

{
  "id": "f1a2b3c4-9999-4a2b-9c3d-aaaaaaaaaaaa",
  "type": "checkout_link.payment.succeeded",
  "timestamp": "2026-06-09T08:39:33.139Z",
  "data": {
    "object": "payment",
    "id": "FV-12350",
    "status": "succeeded",
    "billing_reason": "one_time",
    "gross": 30000,
    "net": 24000,
    "fees": { "fanvue_fee": 4500, "transaction_fee": 1500 },
    "currency": "EUR",
    "paid_in_full": false,
    "installment": { "number": 1, "of": 3 },
    "subscription": null,
    "client_reference_id": "your-crm-id-123",
    "transaction_id": "txn_split_1",
    "created_at": "2026-06-09T08:39:30.000Z",
    "paid_at": "2026-06-09T08:39:33.000Z",
    "checkout_link": {
      "uuid": "ck-uuid",
      "name": "Premium Bundle",
      "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" }
  }
}

`checkout_link.payment.pending`

{
  "id": "f1a2b3c4-2222-4a2b-9c3d-aaaaaaaaaaaa",
  "type": "checkout_link.payment.pending",
  "timestamp": "2026-06-09T08:39:33.139Z",
  "data": {
    "object": "payment",
    "id": "FV-12346",
    "status": "pending",
    "billing_reason": "one_time",
    "gross": 1499,
    "net": 1200,
    "fees": { "fanvue_fee": 224, "transaction_fee": 75 },
    "currency": "USD",
    "paid_in_full": false,
    "installment": null,
    "subscription": null,
    "client_reference_id": "your-crm-id-123",
    "transaction_id": "txn_def",
    "created_at": "2026-06-09T08:39:30.000Z",
    "paid_at": null,
    "checkout_link": {
      "uuid": "ck-uuid",
      "name": "Summer Bundle",
      "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" }
  }
}

`checkout_link.payment.failed`

{
  "id": "f1a2b3c4-3333-4a2b-9c3d-aaaaaaaaaaaa",
  "type": "checkout_link.payment.failed",
  "timestamp": "2026-06-09T08:39:33.139Z",
  "data": {
    "object": "payment",
    "id": "FV-12347",
    "status": "failed",
    "billing_reason": "subscription_renewal",
    "gross": 9999,
    "net": 8000,
    "fees": { "fanvue_fee": 1500, "transaction_fee": 499 },
    "currency": "USD",
    "paid_in_full": false,
    "installment": null,
    "subscription": { "uuid": "sub-uuid" },
    "client_reference_id": "your-crm-id-123",
    "transaction_id": "txn_ghi",
    "created_at": "2026-06-09T08:39:30.000Z",
    "paid_at": null,
    "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" }
  }
}

Overview

Creator events

Checkout

App webhooks

Legacy events (deprecated)

Checkout Payment Events

Payment resource

BNPL installments

Examples

`checkout_link.payment.succeeded`

`checkout_link.payment.succeeded` (BNPL financed sale)

`checkout_link.payment.pending`

`checkout_link.payment.failed`

​Payment resource

​BNPL installments

​Examples

​checkout_link.payment.succeeded

​checkout_link.payment.succeeded (BNPL financed sale)

​checkout_link.payment.pending

​checkout_link.payment.failed

Payment resource

BNPL installments

Examples

`checkout_link.payment.succeeded`

`checkout_link.payment.succeeded` (BNPL financed sale)

`checkout_link.payment.pending`

`checkout_link.payment.failed`