> ## 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. # Reconcile checkout payments and refund requests > Read checkout payments by invoice number or your own reference, track refundStatus and request or withdraw refunds through the API. Use these endpoints to match checkout-link sales against your own records, follow a payment's refund state and ask Fanvue to refund a payment. The payments endpoints are the source of truth to reconcile against; webhooks tell you when to look. Every endpoint lives under `/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 | Endpoint | Scope | Creator permission | Purpose | | - | - | - | - | | `GET .../checkout-links/payments` | `read:creator` | `earnings:read` | List payments, newest first, cursor paginated | | `GET .../checkout-links/payments/{invoiceNumber}` | `read:creator` | `earnings:read` | One payment by Fanvue invoice number | | `POST .../checkout-links/payments/{invoiceNumber}/refund-requests` | `write:creator` | `monetization:manage` | Ask Fanvue to refund the payment in full | | `GET .../checkout-links/refund-requests` | `read:creator` | `earnings:read` | List refund requests, filter by `status` or `invoiceNumber` | | `POST .../checkout-links/refund-requests/{uuid}/withdraw` | `write:creator` | `monetization:manage` | Take back a `pending` request | ## Read payments List a creator's payments, or fetch one by its Fanvue invoice number. The list takes `limit` (default 20, max 100), `cursor` (echo `nextCursor` from the previous page), `clientReferenceId` (the reference you [attached to the link](/docs/checkout/attribution)) and `status` (`pending`, `succeeded` or `failed`). ```bash theme={null} curl "https://api.fanvue.com/creators/3e0c2a1b-7d4f-4e8a-9c21-5b6d7e8f9a01/checkout-links/payments?clientReferenceId=order-123" \ -H "Authorization: Bearer " \ -H "X-Fanvue-API-Version: 2025-06-26" ``` ```bash theme={null} curl "https://api.fanvue.com/creators/3e0c2a1b-7d4f-4e8a-9c21-5b6d7e8f9a01/checkout-links/payments/FVE-20260619-1234" \ -H "Authorization: Bearer " \ -H "X-Fanvue-API-Version: 2025-06-26" ``` The payment is camelCase, and its fields reconcile like this: | Field | Use it for | | - | - | | `invoiceNumber` | The idempotency key for fulfilment. It matches `data.id` on the `checkout_link.payment.*` webhook | | `gross` | What the buyer paid | | `net` | The creator's amount after fees. Reconcile the creator's earnings from this | | `fees { fanvueFee, transactionFee }` | The deductions | | `currency` | Informational only. It names the local currency the fan paid in; every amount is already in USD minor units | Amounts are integers in [USD minor units (cents)](/docs/payments/overview#units-and-currency). 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](/docs/checkout/payments), and [Delivery, retries and idempotency](/docs/webhooks/delivery-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. | Value | Meaning | | - | - | | `null` | No refund request and no refund | | `pending` | A request is awaiting review | | `approved` | Fanvue accepted the request and is reversing the payment | | `failed` | A reversal attempt did not go through; Fanvue is still working it | | `refunded` | The money is back with the fan, through a request or a refund Fanvue issued without one | | `rejected` | Fanvue refused the request | | `withdrawn` | The creator took the request back | | `disputed` | The fan raised a chargeback, which blocks a refund | ## 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 receives `403` with `Refund requests are not enabled for this creator`. ```bash theme={null} curl -X POST "https://api.fanvue.com/creators/3e0c2a1b-7d4f-4e8a-9c21-5b6d7e8f9a01/checkout-links/payments/FVE-20260619-1234/refund-requests" \ -H "Authorization: Bearer " \ -H "X-Fanvue-API-Version: 2025-06-26" \ -H "Content-Type: application/json" \ -d '{ "reason": "requested_by_customer", "note": "Fan bought the bundle twice" }' ``` `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. A `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's `pending`. Once it's approved, the reversal may already be with the payment provider and can't be recalled, so withdraw returns `409`. ```bash theme={null} curl -X POST "https://api.fanvue.com/creators/3e0c2a1b-7d4f-4e8a-9c21-5b6d7e8f9a01/checkout-links/refund-requests/9d8c7b6a-5f4e-4d3c-8b2a-1f0e9d8c7b6a/withdraw" \ -H "Authorization: Bearer " \ -H "X-Fanvue-API-Version: 2025-06-26" ``` ## 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. | Value | Meaning | | - | - | | `pending` | Awaiting review | | `approved` | Accepted; Fanvue is reversing the payment | | `failed` | A reversal attempt did not go through and Fanvue is still working it. Not a decision against the request | | `refunded` | The money is back with the fan. `checkout_link.refund.created` fires | | `rejected` | Refused; the reason is in `reviewNote` | | `withdrawn` | The creator took the request back | | `chargebacked` | The fan disputed the payment with their bank first, so the money went back through the dispute | 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](/docs/checkout/refunds-disputes). This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.