> ## Documentation Index
> Fetch the complete documentation index at: https://api.fanvue.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Ask Fanvue to refund a checkout-link payment
> Open a request that Fanvue refund the specified payment in full. This does not move money: Fanvue reviews the request, and only an approved one produces a refund. Track the outcome with the refund-requests list or the `checkout_link.refund.*` webhooks.
A payment can hold only one open request at a time, and only settled card payments inside Fanvue's refund window can carry one. Returns 404 if the payment does not exist or does not belong to this creator, 409 if it already has an open request or its last request was declined recently, and 422 if it can never be refunded or has fallen outside the window (the message says which).
The `checkout_link.refund.requested` and `checkout_link.refund.created` [webhook events](https://api.fanvue.com/docs/checkout/refunds) announce the new request and a completed refund. Rejected, failed, withdrawn and chargebacked outcomes do not emit an event yet, so poll the refund-requests list by `status` to observe those.
> [!NOTE]
>
> **Required scope**
>
> * `write:creator` — Modify creator profiles, settings, and creator-specific data.
## OpenAPI
````yaml /openapi-v1.json post /v1/creators/{creatorUserUuid}/checkout-links/payments/{invoiceNumber}/refund-requests
openapi: 3.1.0
info:
title: Fanvue API
version: '0.1'
servers:
- url: https://api.fanvue.com
security: []
paths:
/v1/creators/{creatorUserUuid}/checkout-links/payments/{invoiceNumber}/refund-requests:
post:
summary: Ask Fanvue to refund a checkout-link payment
description: >-
Open a request that Fanvue refund the specified payment in full. This
does not move money: Fanvue reviews the request, and only an approved
one produces a refund. Track the outcome with the refund-requests list
or the `checkout_link.refund.*` webhooks.
A payment can hold only one open request at a time, and only settled
card payments inside Fanvue's refund window can carry one. Returns 404
if the payment does not exist or does not belong to this creator, 409 if
it already has an open request or its last request was declined
recently, and 422 if it can never be refunded or has fallen outside the
window (the message says which).
The `checkout_link.refund.requested` and `checkout_link.refund.created` [webhook events](https://api.fanvue.com/docs/checkout/refunds) announce the new request and a completed refund. Rejected, failed, withdrawn and chargebacked outcomes do not emit an event yet, so poll the refund-requests list by `status` to observe those.
operationId: requestCreatorCheckoutLinkRefund
parameters:
- $ref: '#/components/parameters/ApiVersionHeader'
- schema:
type: string
format: uuid
required: true
name: creatorUserUuid
in: path
- schema:
type: string
description: Fanvue payment identifier (invoice number).
required: true
description: Fanvue payment identifier (invoice number).
name: invoiceNumber
in: path
requestBody:
content:
application/json:
schema:
type: object
properties:
reason:
type: string
enum:
- duplicate
- fraudulent
- requested_by_customer
- other
description: Why the creator is asking for the payment to be refunded.
note:
type: string
maxLength: 500
description: Optional context for the reviewer, up to 500 characters.
required:
- reason
responses:
'201':
description: Refund request opened
content:
application/json:
schema:
type: object
properties:
uuid:
type: string
description: Fanvue's unique refund-request identifier.
paymentId:
type: string
description: >-
Invoice number of the payment this request is against
(`invoiceNumber`).
status:
type: string
enum:
- pending
- approved
- failed
- refunded
- rejected
- withdrawn
- chargebacked
description: >-
Where the request stands. `pending` is awaiting review;
`approved` means Fanvue accepted it and is reversing the
payment; `failed` means a reversal attempt did not go
through and Fanvue is still working it (not a decision
against the request); `refunded` is the money back with
the fan, and also fires `checkout_link.refund.created`;
`rejected` is refused, with the reason in `reviewNote`;
`withdrawn` is the creator taking their own request back;
`chargebacked` means the fan disputed the payment with
their bank before the request was settled, so the money
went back through the dispute instead (see the
`checkout_link.dispute.*` events). The Fanvue dashboard
shows `approved` and `failed` together as "processing".
reason:
type: string
enum:
- duplicate
- fraudulent
- requested_by_customer
- other
description: Why the creator is asking for the payment to be refunded.
note:
type:
- string
- 'null'
description: The note the creator sent with the request.
reviewNote:
type:
- string
- 'null'
description: >-
Fanvue's reason for the decision; populated when `status`
is `rejected`.
createdAt:
type: string
format: date-time
description: When the request was opened.
resolvedAt:
type:
- string
- 'null'
format: date-time
description: >-
When the request reached a final state, or null while it
is still open.
required:
- uuid
- paymentId
- status
- reason
- note
- reviewNote
- createdAt
- resolvedAt
example:
uuid: 3f2b1a09-8c7d-4e6f-9a0b-1c2d3e4f5a6b
paymentId: FVE-20260619-1234
status: pending
reason: requested_by_customer
note: Fan bought the wrong tier
reviewNote: null
createdAt: '2026-06-20T09:00:00.000Z'
resolvedAt: null
'400':
description: >-
Bad Request - API version not supported OR validation failed OR
invalid UUID
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/UnsupportedVersionError'
- $ref: '#/components/schemas/ValidationError'
- $ref: '#/components/schemas/InvalidUuidError'
'401':
$ref: '#/components/responses/UnauthorizedResponse'
'403':
$ref: '#/components/responses/UnauthorizedResponse'
'404':
$ref: '#/components/responses/NotFoundResponse'
'409':
description: >-
The payment already has an open refund request, or its last request
was declined too recently to ask again
content:
application/json:
schema:
type: object
properties:
message:
type: string
required:
- message
'410':
$ref: '#/components/responses/SunsetVersionResponse'
'422':
description: The payment cannot be refunded, or is outside the refund window
content:
application/json:
schema:
type: object
properties:
message:
type: string
required:
- message
'429':
$ref: '#/components/responses/RateLimitResponse'
security:
- BearerAuth:
- write:creator
components:
parameters:
ApiVersionHeader:
name: X-Fanvue-API-Version
in: header
required: true
schema:
type: string
default: '2025-06-26'
example: '2025-06-26'
description: API version to use for the request
schemas:
UnsupportedVersionError:
type: object
properties:
error:
type: string
message:
type: string
required:
- error
- message
description: API version not supported
ValidationError:
type: object
properties:
errors:
type: array
items:
type: string
required:
- errors
description: Request validation failed
InvalidUuidError:
type: object
properties:
message:
type: string
required:
- message
description: Invalid UUID format provided
responses:
UnauthorizedResponse:
description: Unauthorized Response
content:
application/json:
schema:
type: object
properties:
error:
type: string
required:
- error
NotFoundResponse:
description: Not Found Response
content:
application/json:
schema:
type: object
properties:
message:
type: string
required:
- message
SunsetVersionResponse:
description: API version no longer supported (sunset)
content:
application/json:
schema:
type: object
properties:
error:
type: string
message:
type: string
nextVersion:
type: string
required:
- error
- message
RateLimitResponse:
description: Too many requests - rate limit exceeded
headers:
Retry-After:
description: Number of seconds to wait before retrying the request
schema:
type: integer
X-RateLimit-Limit:
description: The maximum number of requests allowed in the current window
schema:
type: integer
X-RateLimit-Remaining:
description: The number of requests remaining in the current window
schema:
type: integer
X-RateLimit-Reset:
description: The Unix timestamp (seconds) when the rate limit window resets
schema:
type: integer
content:
application/json:
schema:
type: object
properties:
error:
type: string
required:
- error
securitySchemes:
BearerAuth:
type: oauth2
description: >-
OAuth 2.0 access token, presented as a JWT bearer token in the
`Authorization` header. Obtain a token via the authorization-code flow;
the scopes granted to the token determine which operations it may call.
flows:
authorizationCode:
authorizationUrl: https://auth.fanvue.com/oauth2/auth
tokenUrl: https://auth.fanvue.com/oauth2/token
refreshUrl: https://auth.fanvue.com/oauth2/token
scopes:
read:self: >-
Access your own user profile information, including basic account
details and settings.
read:chat: >-
Read chat conversations, messages, and chat-related data. This
includes viewing chat lists and message history.
write:chat: >-
Create new chats and send messages. This scope is required for any
chat-related actions that modify data.
read:experience: >-
Exchange a fan's experience token for the resolved experience and
the fan's identity, so an embedded fan-facing experience can
render the right content.
write:experience: >-
Request that the creator publish or unpublish a fan-facing
experience. The app mints a request token; the creator confirms
and Fanvue performs the change.
read:fan: Access fan-related data and information within the platform.
read:post: Read posts, including post details, comments, likes, and tips.
write:post: Create, edit, and manage posts and content on behalf of users.
read:media: Access media files, images, videos, and other content assets.
write:media: >-
Upload, modify, and manage media files and content assets. Also
required for vault folder management.
read:creator: >-
Access creator profiles, content, and creator-specific
information.
write:creator: Modify creator profiles, settings, and creator-specific data.
read:insights: >-
Access analytics, metrics, and insights data for performance
tracking.
read:tracking_links: >-
Read tracking links and the users associated with them, including
per-user tracking metadata.
write:tracking_links: Create and delete tracking links.
read:agency: Read agency information, including the agency's team members.
write:agency: >-
Manage agency team members and invites, including inviting new
team members and creators.
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.