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`
`reason`	string \| null	Sanitised failure reason on `payment.failed`; `null` otherwise. See Failure reasons
`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

Failure reasons

checkout_link.payment.failed carries a sanitised reason. Values are deliberately coarse: Fanvue’s risk screening is never disclosed, so declines it drives surface under neutral values.

`reason`	What happened	What to do
`insufficient_funds`	The buyer’s account can’t cover the charge	Soft decline; worth the buyer retrying later or with another method
`expired_card`	The card has expired	The buyer needs a different or updated card
`bank_decline`	The issuer declined without a more specific reason	Another attempt or method may succeed; persistent declines mean the buyer contacts their bank
`invalid_details`	Card or billing details were invalid or malformed	The buyer re-enters their details
`verification_failed`	A verification check (CVV, AVS, 3DS) failed or wasn’t completed	The buyer retries and completes verification
`limit_exceeded`	An issuer limit was hit: amount, daily spend, or attempts	Retry later, or with a smaller amount or different method
`other`	No specific category, including technical failures	Retry later; a different method if it persists

Two rules:

You don’t retry charges yourself. Checkout is buyer-present: a failed one-time payment ends there unless the buyer tries again, and failed renewals enter Fanvue’s own retry schedule (dunning). Don’t treat the first failed renewal as churn.
Use reason for ops and analytics: spotting a decline spike, deciding when to re-engage a buyer, reconciling failed revenue.

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.

Failure reasons

checkout_link.payment.failed carries a sanitised reason. Values are deliberately coarse: Fanvue’s risk screening is never disclosed, and declines it drives surface under neutral values.

`reason`	What happened	What to do
`insufficient_funds`	The buyer’s account can’t cover the charge	Soft decline: the buyer can retry later or use another method
`expired_card`	The card has expired	The buyer needs an updated or different card
`bank_decline`	The issuer declined without a more specific reason	Another attempt or method may succeed; persistent declines mean the buyer should contact their bank
`invalid_details`	Card or billing details were invalid or malformed	The buyer re-enters their details
`verification_failed`	A verification check (CVV, AVS, 3DS) failed or wasn’t completed	The buyer retries and completes verification
`limit_exceeded`	An issuer limit was hit: amount, daily spend, or attempts	Soft decline: retry later, or with a smaller amount or different method
`other`	No specific category, including technical failures	Retry later; a different method if it persists

Two rules:

You don’t retry charges yourself. Checkout is buyer-present: a failed one-time payment ends unless the buyer tries again, and failed renewals enter Fanvue’s own retry schedule, so don’t treat the first payment.failed on a renewal as churn.
Use reason for ops and analytics: spotting a decline spike, deciding when to re-engage a buyer, and reconciling failed revenue.

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",
    "reason": "insufficient_funds",
    "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

Failure reasons

BNPL installments

Failure reasons

Examples

`checkout_link.payment.succeeded`

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

`checkout_link.payment.pending`

`checkout_link.payment.failed`

​Payment resource

​Failure reasons

​BNPL installments

​Failure reasons

​Examples

​checkout_link.payment.succeeded

​checkout_link.payment.succeeded (BNPL financed sale)

​checkout_link.payment.pending

​checkout_link.payment.failed

Payment resource

Failure reasons

BNPL installments

Failure reasons

Examples

`checkout_link.payment.succeeded`

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

`checkout_link.payment.pending`

`checkout_link.payment.failed`