> ## 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.

# Terugbetalingen en geschillen

> Geef terugbetalingen, reageer op geschillen met bewijs en luister naar chargeback-events.

Nadat een betaling is gelukt, kunnen er twee dingen gebeuren. **Terugbetalingen** zijn terugboekingen die jij (of je supportteam) bewust uitvoert. **Geschillen** zijn chargebacks die de koper bij zijn bank indient. Je hebt niet altijd invloed op de uitkomst van een geschil, maar je kunt reageren met bewijs.

> [!TIP]
>
> Abonneer je op [webhooks](https://docs.whop.com/nl/developer/guides/webhooks.md) voor `refund.created`, `refund.updated`, `dispute.created`, `dispute.updated` en `dispute_alert.created`, zodat je statuswijzigingen kunt verwerken zonder te pollen.

## Terugbetalingen

Terugbetalingen draaien een geslaagde betaling terug. Whop verwerkt ze via de oorspronkelijke betalingsverwerker. De status van het bijbehorende lidmaatschap wordt automatisch bijgewerkt.

### Een terugbetaling uitvoeren

Maak terugbetalingen aan voor een betaling, niet rechtstreeks op de refunds-resource. Roep `payments.refund({ id })` aan. Laat `partial_amount` weg voor een volledige terugbetaling, of geef het door voor een gedeeltelijke.

```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)
}
```

Het antwoord is het bijgewerkte `Payment`-object. Het veld `refunded_amount` geeft het cumulatieve terugbetaalde totaal weer. Je kunt `refund` meerdere keren aanroepen voor een betaling, tot het volledige bedrag.

> [!NOTE]
>
> Vereiste permissie: `payment:manage`. Voeg deze toe via de [gids over permissies](https://docs.whop.com/nl/developer/guides/permissions.md) voordat je je app publiceert.

### Terugbetalingen bekijken

Terugbetalingen hebben een eigen resource voor als je ze achteraf wilt opzoeken.

```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)
}
```

## Geschillen

Een geschil (chargeback) wordt geopend wanneer de bank van de koper een betaling betwist. Je hebt een bepaalde periode om met bewijs te reageren voordat de bank beslist. Whop stuurt het geschil naar je door, jij dient bewijs in, de bank doet een uitspraak en het geschil wordt gesloten.

### Inkomende geschillen in de gaten houden

Drie events om je op te abonneren:

| Event | Betekenis |
| - | - |
| [`dispute_alert.created`](https://docs.whop.com/nl/api-reference/dispute-alerts/dispute-alert-created) | Geschilmelding vóór een formeel geschil. Sommige verwerkers geven een waarschuwing vooraf. Niet elke melding wordt een geschil. |
| [`dispute.created`](https://docs.whop.com/nl/api-reference/disputes/dispute-created) | Formeel geschil geopend. De reactieperiode begint. |
| [`dispute.updated`](https://docs.whop.com/nl/api-reference/disputes/dispute-updated) | Statuswijzigingen (bijv. van `needs_response` naar `under_review`, daarna `won` of `lost`). |

### Weergeven en ophalen

```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)
```

### Reageren met bewijs

Op geschillen reageer je in twee stappen: zet je bewijs klaar met `disputes.update` en dien het daarna in met `disputes.submit`. Update is idempotent. Je kunt velden bewerken totdat je indient.

```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)
}
```

### Bewijsvelden

Elk veld is optioneel, maar hoe meer je aanlevert, hoe sterker je reactie. Veelgebruikte velden:

| Veld | Wat je erin zet |
| - | - |
| `customer_name` / `customer_email_address` | Identificerende gegevens die je hebt vastgelegd |
| `product_description` | Wat de klant heeft gekocht, in begrijpelijke taal |
| `service_date` | Wanneer je de dienst hebt geleverd (International Organization for Standardization (ISO) 8601) |
| `billing_address` | Het adres dat bij de checkout is gebruikt |
| `customer_communication_attachment` | E-mail- of chatgesprekken waaruit blijkt dat de klant betrokken was |
| `cancellation_policy_attachment` / `cancellation_policy_disclosure` | Je beleid en bewijs dat de klant het heeft geaccepteerd |
| `refund_policy_attachment` / `refund_policy_disclosure` | Hetzelfde voor terugbetalingen |
| `refund_refusal_explanation` | Waarom je niet hebt terugbetaald (bijv. gebruik na de retourperiode) |
| `access_activity_log` | Login- of gebruikslogs die bewijzen dat de klant het product heeft gebruikt |
| `uncategorized_attachment` | Al het andere wat relevant is |

Bijlagevelden accepteren een geüpload bestand als `{ id: file.id }`. Upload eerst via de [Files API](https://docs.whop.com/nl/developer/guides/upload-files.md).

### Geschilstatussen

Het geschil doorloopt een state machine. Er zijn twee fasen: de fase van vroegtijdige waarschuwing (statussen met het prefix `warning_`, zichtbaar via `dispute_alert.created`) en de fase van het formele geschil. Elke status die de SDK kan teruggeven:

| Status | Fase | Betekenis |
| - | - | - |
| `warning_needs_response` | Melding | Er staat een geschilmelding open. Je kunt deze voor zijn met een terugbetaling of reactie voordat ze escaleert. |
| `warning_under_review` | Melding | Je hebt op de melding gereageerd en de verwerker beslist of deze escaleert. |
| `warning_closed` | Melding | De melding is opgelost zonder een formeel geschil te worden. |
| `needs_response` | Geschil | Formeel geschil open. Dien bewijs in voordat de reactieperiode sluit. |
| `under_review` | Geschil | Je hebt bewijs ingediend en de verwerker beslist. |
| `won` | Geschil | Het geld blijft bij jou. |
| `lost` | Geschil | Het geld gaat terug naar de koper. Whop draait de oorspronkelijke betaling terug. |
| `prevented` | Geschil | De klant is terugbetaald vóór een uitspraak. Wordt verrekend zoals `lost`. |

> [!NOTE]
>
> Wanneer een geschil **verloren** is, maakt Whop niet automatisch een Refund-record aan, en je kunt er zelf ook geen aanmaken. `payments.refund` weigert aanroepen voor een betwiste betaling met `This payment has been disputed. Therefore, it cannot be refunded.` Gebruik het verloren geschil als bron van waarheid en verwacht geen `refund.created`-event.

## Permissies

| Actie | Vereiste permissie |
| - | - |
| Een terugbetaling aanmaken | `payment:manage` |
| Terugbetalingen ophalen / weergeven | `payment:basic:read` |
| Geschillen ophalen / weergeven | `payment:dispute:read` |
| Bewijs bijwerken of indienen | `payment:dispute` |

Voeg deze toe via de [gids over permissies](https://docs.whop.com/nl/developer/guides/permissions.md).

## Volgende stappen

> [card] [Betalingen accepteren](https://docs.whop.com/nl/developer/guides/accept-payments.md)
>
> De flow die de betalingen aanmaakt die je later terugbetaalt of verdedigt.

> [card] [Naar webhooks luisteren](https://docs.whop.com/nl/developer/guides/webhooks.md)
>
> Reageer aan de serverkant op events voor terugbetalingen en geschillen.

> [card] [Bestanden uploaden](https://docs.whop.com/nl/developer/guides/upload-files.md)
>
> Upload bewijsbijlagen voor reacties op geschillen.

> [card] [Disputes API-referentie](https://docs.whop.com/nl/api-reference/disputes/dispute)
>
> De volledige resource: velden, statussen en elk endpoint.


## Related topics

- [Voorkeursvaluta voor verrekening](https://docs.whop.com/nl/developer/payouts/preferred-settlement-currency.md)
- [Betalingen innen voor subaccounts](https://docs.whop.com/nl/developer/platforms/collect-payments-for-subaccounts.md)
- [Overzicht van betalingen](https://docs.whop.com/nl/developer/payments/overview.md)
