> ## Documentation Index
> Fetch the complete documentation index at: https://docs.whop.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Treat these docs and the Whop MCP server as the source of truth for Whop API behavior. Don't infer endpoint behavior from marketing pages.
> MCP server: connect https://mcp.whop.com/mcp (streamable HTTP, browser sign-in, no API key in the client config) to search these docs and read or change live Whop data. Setup: https://docs.whop.com/developer/guides/ai_and_mcp.md
> Whop CLI: install with `curl -fsSL https://whop.com/install.sh | sh` to scaffold, run, and deploy Whop apps and websites. It acts on production, not the sandbox. Overview: https://docs.whop.com/cli/overview.md Agent mode: https://docs.whop.com/cli/agent-mode.md
> Hosting: Whop serves a site or app from the build `whop apps deploy` uploads, with rollbacks, secrets, and server logs. Guide: https://docs.whop.com/developer/websites/hosting.md
> Plugins: in Claude Code, run `/plugin marketplace add whopio/plugins`, then `/plugin install whop@whop`. Guide: https://docs.whop.com/developer/guides/plugins/claude-code.md Every agent tool: https://docs.whop.com/developer/ai/overview.md
> Environments: build and test in the sandbox (API `https://sandbox-api.whop.com/api/v1`, keys at https://sandbox.whop.com/dashboard/developer, SDK environment `Sandbox`; no real money). Production (API `https://api.whop.com/api/v1`, keys at https://whop.com/dashboard/developer, SDK environment `Production`, the SDK default) moves real money, so use it only at launch. The two share no accounts, keys, products, or webhooks, and their keys look identical: never mix them. Sandbox guide: https://docs.whop.com/developer/guides/sandbox.md Comparison: https://docs.whop.com/developer/quickstart.md
> API: send `Authorization: Bearer <API_KEY>` from your server only, and pin a dated version with the `Api-Version-Date` header. OpenAPI spec: https://api.whop.com/api/v1/openapi.json
> Which API: build on the Current API, whose pages live under https://docs.whop.com/api-reference/ (start at https://docs.whop.com/api-reference/overview.md). Pages under /api-reference/legacy/ are the Legacy API. Use one only when https://docs.whop.com/api-reference/stability.md lists the resource as Legacy-only.

# Remboursements et litiges

> Émettez des remboursements, répondez aux litiges avec des preuves et écoutez les événements de rétrofacturation.

Deux choses peuvent se produire après qu'un paiement a abouti. Les **remboursements** sont une annulation que vous (ou votre équipe d'assistance) émettez délibérément. Les **litiges** sont des rétrofacturations que l'acheteur dépose auprès de sa banque. Vous ne contrôlez pas toujours l'issue d'un litige, mais vous pouvez y répondre avec des preuves.

> [!TIP]
>
> Abonnez-vous aux [webhooks](https://docs.whop.com/fr/developer/guides/webhooks.md) pour `refund.created`, `refund.updated`, `dispute.created`, `dispute.updated` et `dispute_alert.created` afin de rapprocher les changements de statut sans interrogation périodique.

## Remboursements

Les remboursements annulent un paiement réussi. Whop les traite via le processeur de paiement d'origine. Le statut de l'adhésion correspondante se met à jour automatiquement.

### Émettre un remboursement

Créez les remboursements à partir d'un paiement, et non directement sur la ressource des remboursements. Appelez `payments.refund({ id })`. Omettez `partial_amount` pour un remboursement total, ou transmettez-le pour un remboursement partiel.

```typescript TypeScript theme={null}
import { WhopClient } from "@whop/sdk";

const client = new WhopClient({ token: process.env.WHOP_API_KEY });

// Full refund
const fullRefund = await client.payments.refund({ id: "pay_xxxxxxxxxxxxx" });

// Partial refund
const partialRefund = await client.payments.refund({
  id: "pay_xxxxxxxxxxxxx",
  partial_amount: 5.0, // in payment currency, e.g. 5 USD
});
```

```python Python theme={null}
import os
from whop_sdk import Whop

client = Whop(token=os.environ["WHOP_API_KEY"])

# Full refund
full_refund = client.payments.refund("pay_xxxxxxxxxxxxx")

# Partial refund
partial_refund = client.payments.refund(
    "pay_xxxxxxxxxxxxx",
    partial_amount=5.0,
)
```

```ruby Ruby theme={null}
require "whop_sdk"

client = Whop_sdk::Client.new(token: ENV.fetch("WHOP_API_KEY"))

# Full refund
full_refund = client.payments.refund(id: "pay_xxxxxxxxxxxxx")

# Partial refund
partial_refund = client.payments.refund(
  id: "pay_xxxxxxxxxxxxx",
  partial_amount: 5.0,
)
```

```rust Rust theme={null}
use whop_sdk::prelude::*;

let config = ClientConfig {
    token: Some(std::env::var("WHOP_API_KEY").unwrap()),
    ..Default::default()
};
let client = Whop::new(config).expect("Failed to build client");

// Full refund
let full_refund = client
    .payments
    .refund(&"pay_xxxxxxxxxxxxx".to_string(), &RefundPaymentsRequest::default(), None)
    .await?;

// Partial refund
let partial_refund = client
    .payments
    .refund(
        &"pay_xxxxxxxxxxxxx".to_string(),
        &RefundPaymentsRequest {
            partial_amount: Some(5.0), // in payment currency, e.g. 5 USD
        },
        None,
    )
    .await?;
```

```go Go theme={null}
import (
    "context"
    "log"
    "os"

    whopsdk "github.com/whopio/whopsdk-go/v2"
    "github.com/whopio/whopsdk-go/v2/client"
    "github.com/whopio/whopsdk-go/v2/option"
)

client := client.NewWhop(option.WithToken(os.Getenv("WHOP_API_KEY")))

// Full refund
_, err := client.Payments.Refund(context.TODO(), &whopsdk.RefundPaymentsRequest{
    ID: "pay_xxxxxxxxxxxxx",
})
if err != nil {
    log.Fatal(err)
}

// Partial refund
_, err = client.Payments.Refund(context.TODO(), &whopsdk.RefundPaymentsRequest{
    ID:            "pay_xxxxxxxxxxxxx",
    PartialAmount: whopsdk.Float64(5.0), // in payment currency, e.g. 5 USD
})
if err != nil {
    log.Fatal(err)
}
```

La réponse est l'objet `Payment` mis à jour. Le champ `refunded_amount` reflète le total cumulé remboursé. Vous pouvez appeler `refund` plusieurs fois pour un même paiement, jusqu'à son montant total.

> [!NOTE]
>
> Permission requise : `payment:manage`. Ajoutez-la depuis le [guide des permissions](https://docs.whop.com/fr/developer/guides/permissions.md) avant de publier votre application.

### Consulter les remboursements

Les remboursements disposent de leur propre ressource si vous devez les retrouver après coup.

```typescript TypeScript theme={null}
const refund = await client.refunds.retrieve({ id: "ref_xxxxxxxxxxxxx" });

const refunds = await client.refunds.list({
  account_id: "biz_xxxxxxxxxxxxx",
});

for await (const item of refunds) {
  console.log(item);
}
```

```python Python theme={null}
refund = client.refunds.retrieve("ref_xxxxxxxxxxxxx")

for item in client.refunds.list(account_id="biz_xxxxxxxxxxxxx"):
    print(item)
```

```ruby Ruby theme={null}
refund = client.refunds.retrieve(id: "ref_xxxxxxxxxxxxx")

client.refunds.list(account_id: "biz_xxxxxxxxxxxxx").each do |item|
  puts item
end
```

```rust Rust theme={null}
let refund = client
    .refunds
    .retrieve(&"ref_xxxxxxxxxxxxx".to_string(), None)
    .await?;

let refunds = client
    .refunds
    .list(
        &RefundsListQueryRequest {
            account_id: Some("biz_xxxxxxxxxxxxx".to_string()),
            ..Default::default()
        },
        None,
    )
    .await?;

for item in refunds.data {
    println!("{item:?}");
}
```

```go Go theme={null}
refund, err := client.Refunds.Retrieve(context.TODO(), &whopsdk.RetrieveRefundsRequest{
    ID: "ref_xxxxxxxxxxxxx",
})
if err != nil {
    log.Fatal(err)
}
fmt.Println(refund)

page, err := client.Refunds.List(context.TODO(), &whopsdk.ListRefundsRequest{
    AccountID: whopsdk.String("biz_xxxxxxxxxxxxx"),
})
if err != nil {
    log.Fatal(err)
}

iter := page.Iterator()
for iter.Next(context.TODO()) {
    fmt.Println(iter.Current())
}
if err := iter.Err(); err != nil {
    log.Fatal(err)
}
```

## Litiges

Un litige (rétrofacturation) s'ouvre lorsque la banque de l'acheteur conteste un paiement. Vous disposez d'un délai pour répondre avec des preuves avant que la banque ne tranche. Whop vous transmet le litige, vous soumettez vos preuves, la banque statue et le litige est clos.

### Surveiller les litiges entrants

Trois événements auxquels vous abonner :

| Événement | Signification |
| - | - |
| [`dispute_alert.created`](https://docs.whop.com/fr/api-reference/dispute-alerts/dispute-alert-created) | Alerte de litige avant un litige formel. Certains processeurs préviennent à l'avance. Toutes les alertes ne se transforment pas en litige. |
| [`dispute.created`](https://docs.whop.com/fr/api-reference/disputes/dispute-created) | Litige formel ouvert. Le délai de réponse commence. |
| [`dispute.updated`](https://docs.whop.com/fr/api-reference/disputes/dispute-updated) | Changements de statut (par exemple de `needs_response` à `under_review`, puis `won` ou `lost`). |

### Lister et récupérer

```typescript TypeScript theme={null}
const disputes = await client.disputes.list({
  account_id: "biz_xxxxxxxxxxxxx",
});

for await (const item of disputes) {
  console.log(item);
}

const dispute = await client.disputes.retrieve({ id: "dspt_xxxxxxxxxxxxx" });
```

```python Python theme={null}
for item in client.disputes.list(account_id="biz_xxxxxxxxxxxxx"):
    print(item)

dispute = client.disputes.retrieve("dspt_xxxxxxxxxxxxx")
```

```ruby Ruby theme={null}
client.disputes.list(account_id: "biz_xxxxxxxxxxxxx").each do |item|
  puts item
end

dispute = client.disputes.retrieve(id: "dspt_xxxxxxxxxxxxx")
```

```rust Rust theme={null}
let disputes = client
    .disputes
    .list(
        &DisputesListQueryRequest {
            account_id: Some("biz_xxxxxxxxxxxxx".to_string()),
            ..Default::default()
        },
        None,
    )
    .await?;

for item in disputes.data {
    println!("{item:?}");
}

let dispute = client
    .disputes
    .retrieve(&"dspt_xxxxxxxxxxxxx".to_string(), None)
    .await?;
```

```go Go theme={null}
page, err := client.Disputes.List(context.TODO(), &whopsdk.ListDisputesRequest{
    AccountID: whopsdk.String("biz_xxxxxxxxxxxxx"),
})
if err != nil {
    log.Fatal(err)
}

iter := page.Iterator()
for iter.Next(context.TODO()) {
    fmt.Println(iter.Current())
}
if err := iter.Err(); err != nil {
    log.Fatal(err)
}

dispute, err := client.Disputes.Retrieve(context.TODO(), &whopsdk.RetrieveDisputesRequest{
    ID: "dspt_xxxxxxxxxxxxx",
})
if err != nil {
    log.Fatal(err)
}
fmt.Println(dispute)
```

### Répondre avec des preuves

La réponse aux litiges se fait en deux étapes : préparez vos preuves avec `disputes.update`, puis soumettez-les avec `disputes.submit`. La mise à jour est idempotente. Vous pouvez modifier les champs jusqu'à la soumission.

```typescript TypeScript theme={null}
// Stage evidence (call as many times as needed)
await client.disputes.update({
  id: "dspt_xxxxxxxxxxxxx",
  evidence: {
    customer_name: "Jane Doe",
    customer_email_address: "jane@example.com",
    product_description: "Annual subscription to Acme Pro, purchased 2026-01-15.",
    service_date: "2026-01-15",
    refund_policy_disclosure: "Customer agreed to no-refunds policy at checkout.",
    notes: "Customer used the product 47 times across 8 sessions before disputing.",
  },
});

// Submit evidence to the processor. After this, you can no longer edit.
await client.disputes.submit({ id: "dspt_xxxxxxxxxxxxx" });
```

```python Python theme={null}
client.disputes.update(
    "dspt_xxxxxxxxxxxxx",
    evidence={
        "customer_name": "Jane Doe",
        "customer_email_address": "jane@example.com",
        "product_description": "Annual subscription to Acme Pro, purchased 2026-01-15.",
        "service_date": "2026-01-15",
        "refund_policy_disclosure": "Customer agreed to no-refunds policy at checkout.",
        "notes": "Customer used the product 47 times across 8 sessions before disputing.",
    },
)

client.disputes.submit("dspt_xxxxxxxxxxxxx")
```

```ruby Ruby theme={null}
# Stage evidence (call as many times as needed)
client.disputes.update(
  id: "dspt_xxxxxxxxxxxxx",
  evidence: {
    customer_name: "Jane Doe",
    customer_email_address: "jane@example.com",
    product_description: "Annual subscription to Acme Pro, purchased 2026-01-15.",
    service_date: "2026-01-15",
    refund_policy_disclosure: "Customer agreed to no-refunds policy at checkout.",
    notes: "Customer used the product 47 times across 8 sessions before disputing.",
  },
)

# Submit evidence to the processor. After this, you can no longer edit.
client.disputes.submit(id: "dspt_xxxxxxxxxxxxx")
```

```rust Rust theme={null}
// Stage evidence (call as many times as needed)
client
    .disputes
    .update(
        &"dspt_xxxxxxxxxxxxx".to_string(),
        &UpdateDisputesRequest {
            evidence: Some(DisputesUpdateDisputesRequestEvidence {
                customer_name: Some("Jane Doe".to_string()),
                customer_email_address: Some("jane@example.com".to_string()),
                product_description: Some(
                    "Annual subscription to Acme Pro, purchased 2026-01-15.".to_string(),
                ),
                service_date: Some("2026-01-15".to_string()),
                refund_policy_disclosure: Some(
                    "Customer agreed to no-refunds policy at checkout.".to_string(),
                ),
                notes: Some(
                    "Customer used the product 47 times across 8 sessions before disputing.".to_string(),
                ),
                ..Default::default()
            }),
        },
        None,
    )
    .await?;

// Submit evidence to the processor. After this, you can no longer edit.
client
    .disputes
    .submit(&"dspt_xxxxxxxxxxxxx".to_string(), None)
    .await?;
```

```go Go theme={null}
// Stage evidence (call as many times as needed)
_, err := client.Disputes.Update(context.TODO(), &whopsdk.UpdateDisputesRequest{
    ID: "dspt_xxxxxxxxxxxxx",
    Evidence: &whopsdk.UpdateDisputesRequestEvidence{
        CustomerName:           whopsdk.String("Jane Doe"),
        CustomerEmailAddress:   whopsdk.String("jane@example.com"),
        ProductDescription:     whopsdk.String("Annual subscription to Acme Pro, purchased 2026-01-15."),
        ServiceDate:            whopsdk.String("2026-01-15"),
        RefundPolicyDisclosure: whopsdk.String("Customer agreed to no-refunds policy at checkout."),
        Notes:                  whopsdk.String("Customer used the product 47 times across 8 sessions before disputing."),
    },
})
if err != nil {
    log.Fatal(err)
}

// Submit evidence to the processor. After this, you can no longer edit.
if _, err := client.Disputes.Submit(context.TODO(), &whopsdk.SubmitDisputesRequest{
    ID: "dspt_xxxxxxxxxxxxx",
}); err != nil {
    log.Fatal(err)
}
```

### Champs de preuve

Tous les champs sont facultatifs, mais plus vous en fournissez, plus votre réponse est solide. Les plus courants :

| Champ | Contenu à y mettre |
| - | - |
| `customer_name` / `customer_email_address` | Les informations d'identification dont vous disposez |
| `product_description` | Ce que le client a acheté, en langage clair |
| `service_date` | La date à laquelle vous avez fourni le service (format ISO 8601 de l'Organisation internationale de normalisation) |
| `billing_address` | L'adresse utilisée lors du checkout |
| `customer_communication_attachment` | Fils d'e-mails ou de chat montrant l'implication du client |
| `cancellation_policy_attachment` / `cancellation_policy_disclosure` | Votre politique et la preuve que le client l'a acceptée |
| `refund_policy_attachment` / `refund_policy_disclosure` | Idem pour les remboursements |
| `refund_refusal_explanation` | Pourquoi vous n'avez pas remboursé (par exemple utilisation au-delà du délai de retour) |
| `access_activity_log` | Journaux de connexion ou d'utilisation prouvant que le client a utilisé le produit |
| `uncategorized_attachment` | Tout autre élément pertinent |

Les champs de pièce jointe acceptent un fichier téléversé sous la forme `{ id: file.id }`. Téléversez-le d'abord via l'[API Files](https://docs.whop.com/fr/developer/guides/upload-files.md).

### Statuts des litiges

Le litige évolue au sein d'une machine à états. Il comporte deux phases : la phase d'alerte précoce (statuts préfixés par `warning_`, signalés via `dispute_alert.created`) et la phase de litige formel. Voici tous les statuts que le SDK peut renvoyer :

| Statut | Phase | Signification |
| - | - | - |
| `warning_needs_response` | Alerte | Une alerte de litige est ouverte. Vous pouvez la devancer avec un remboursement ou une réponse avant qu'elle ne s'aggrave. |
| `warning_under_review` | Alerte | Vous avez répondu à l'alerte, et le processeur décide s'il faut l'escalader. |
| `warning_closed` | Alerte | L'alerte s'est résolue sans devenir un litige formel. |
| `needs_response` | Litige | Litige formel ouvert. Soumettez vos preuves avant la fin du délai de réponse. |
| `under_review` | Litige | Vous avez soumis vos preuves, et le processeur délibère. |
| `won` | Litige | Les fonds vous restent acquis. |
| `lost` | Litige | Les fonds retournent à l'acheteur. Whop annule le paiement d'origine. |
| `prevented` | Litige | Le client a été remboursé avant toute décision. Se règle comme `lost`. |

> [!NOTE]
>
> Lorsqu'un litige est **perdu**, Whop ne crée pas automatiquement d'enregistrement de remboursement, et vous ne pouvez pas en créer un vous-même. `payments.refund` rejette les appels portant sur un paiement contesté avec `This payment has been disputed. Therefore, it cannot be refunded.` Considérez le litige perdu comme la source de vérité, et n'attendez pas d'événement `refund.created`.

## Permissions

| Action | Permission requise |
| - | - |
| Créer un remboursement | `payment:manage` |
| Récupérer / lister les remboursements | `payment:basic:read` |
| Récupérer / lister les litiges | `payment:dispute:read` |
| Mettre à jour ou soumettre des preuves | `payment:dispute` |

Ajoutez-les depuis le [guide des permissions](https://docs.whop.com/fr/developer/guides/permissions.md).

## Étapes suivantes

> [card] [Accepter des paiements](https://docs.whop.com/fr/developer/guides/accept-payments.md)
>
> Le flux qui crée les paiements que vous rembourserez ou défendrez plus tard.

> [card] [Écouter les webhooks](https://docs.whop.com/fr/developer/guides/webhooks.md)
>
> Réagissez côté serveur aux événements de remboursement et de litige.

> [card] [Téléverser des fichiers](https://docs.whop.com/fr/developer/guides/upload-files.md)
>
> Téléversez des pièces jointes de preuve pour vos réponses aux litiges.

> [card] [Référence de l'API Disputes](https://docs.whop.com/fr/api-reference/disputes/dispute)
>
> Ressource complète : champs, statuts et tous les endpoints.


## Related topics

- [Devise de règlement préférée](https://docs.whop.com/fr/developer/payouts/preferred-settlement-currency.md)
- [Référence de l'API Stats](https://docs.whop.com/fr/api-reference/stats/stats.md)
- [Vue d'ensemble des paiements](https://docs.whop.com/fr/developer/payments/overview.md)
