/creators/{creatorUserUuid}/checkout-links, so an agency or app can reconcile for a creator it manages. Each call needs the scope and the creator permission listed in the table.
Endpoints
Read payments
List a creator’s payments, or fetch one by its Fanvue invoice number. The list takeslimit (default 20, max 100), cursor (echo nextCursor from the previous page), clientReferenceId (the reference you attached to the link) and status (pending, succeeded or failed).
Amounts are integers in USD minor units (cents). On a tax-inclusive link
gross is the pre-tax base, so compare the fan’s charge against total and tax on the webhook payload rather than gross. Both are described in Checkout link payment events, and Delivery, retries and idempotency covers deduplicating on the webhook side.
Payment refundStatus
refundStatus on the payment is null when nothing has been asked for or paid back. The six values from pending to withdrawn mirror the payment’s most recent refund request.
Request a refund
A refund request asks Fanvue to refund one payment in full. Nothing moves until Fanvue approves it. Refund requests are available to creators who have them enabled; any other account receives403 with Refund requests are not enabled for this creator.
reason is duplicate, fraudulent, requested_by_customer or other, and note is optional, up to 500 characters. The response is 201 with the request, carrying uuid, paymentId, status, reason, note, reviewNote, createdAt and resolvedAt.
The endpoint enforces these rules:
- A request needs a settled payment inside the 180-day refund window, paid by card, Apple Pay, Google Pay, Pix or Fanvue wallet. A BNPL instalment sale is not eligible through this flow, and older payments return
422, so send the creator to support for either. - A payment holds one open request at a time. A second request, or one soon after a rejection, returns
409. - A payment that can never be refunded returns
422, and the message says which rule applied.
checkout_link.refund.created event fires for every full refund of a checkout-link payment, whether a request preceded it or not.
Withdraw a request
You can withdraw a request while it’spending. Once it’s approved, the reversal may already be with the payment provider and can’t be recalled, so withdraw returns 409.
Refund request status
The refund request is a separate resource from the refund. The request records what the creator asked for and Fanvue’s decision, the refund is the money moving back, and paymentId joins the two.
The Checkout Links page shows
approved and failed together as “processing”.
Only two events announce request activity: checkout_link.refund.requested when a request opens and checkout_link.refund.created when money moves. Read rejected, failed, withdrawn and chargebacked outcomes from the list endpoint filtered by status, or from refundStatus on the payment. The webhook refund_request resource and its fields are in Checkout link refund and dispute events.