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

# Reembolsos y disputas

> Emite reembolsos, responde a disputas con pruebas y escucha los eventos de contracargo.

Después de que un pago se procesa pueden ocurrir dos cosas. Los **reembolsos** son una reversión que tú (o tu equipo de soporte) emites de forma intencionada. Las **disputas** son contracargos que el comprador presenta ante su banco. No siempre controlas cómo se resuelve una disputa, pero puedes responder con pruebas.

> [!TIP]
>
> Suscríbete a los [webhooks](https://docs.whop.com/es/developer/guides/webhooks.md) de `refund.created`, `refund.updated`, `dispute.created`, `dispute.updated` y `dispute_alert.created` para poder conciliar los cambios de estado sin hacer sondeos.

## Reembolsos

Los reembolsos revierten un pago completado. Whop los procesa a través del procesador de pagos original. El estado de la membresía correspondiente se actualiza automáticamente.

### Emitir un reembolso

Crea los reembolsos sobre un pago, no directamente en el recurso de reembolsos. Llama a `payments.refund({ id })`. Omite `partial_amount` para un reembolso total o pásalo para uno parcial.

```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 respuesta es el objeto `Payment` actualizado. El campo `refunded_amount` refleja el total reembolsado acumulado. Puedes llamar a `refund` varias veces para un mismo pago hasta su importe total.

> [!NOTE]
>
> Permiso requerido: `payment:manage`. Añádelo desde la [guía de permisos](https://docs.whop.com/es/developer/guides/permissions.md) antes de publicar tu app.

### Consultar reembolsos

Los reembolsos tienen su propio recurso por si necesitas consultarlos más tarde.

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

## Disputas

Una disputa (contracargo) se abre cuando el banco del comprador impugna un pago. Tienes un plazo para responder con pruebas antes de que el banco decida. Whop te reenvía la disputa, tú envías las pruebas, el banco dictamina y la disputa se cierra.

### Vigilar las disputas entrantes

Hay tres eventos a los que suscribirse:

| Evento | Significado |
| - | - |
| [`dispute_alert.created`](https://docs.whop.com/es/api-reference/dispute-alerts/dispute-alert-created) | Alerta de disputa antes de una disputa formal. Algunos procesadores avisan con antelación. No todas las alertas se convierten en disputas. |
| [`dispute.created`](https://docs.whop.com/es/api-reference/disputes/dispute-created) | Se abrió una disputa formal. Comienza el plazo de respuesta. |
| [`dispute.updated`](https://docs.whop.com/es/api-reference/disputes/dispute-updated) | Cambios de estado (p. ej., de `needs_response` a `under_review` y luego a `won` o `lost`). |

### Listar y obtener

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

### Responder con pruebas

Las disputas tienen una respuesta en dos pasos: prepara tus pruebas con `disputes.update` y luego envíalas con `disputes.submit`. La actualización es idempotente. Puedes editar los campos hasta que las envíes.

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

### Campos de pruebas

Todos los campos son opcionales, pero cuanto más aportes, más sólida será la respuesta. Los más habituales:

| Campo | Qué incluir |
| - | - |
| `customer_name` / `customer_email_address` | La información identificativa que tienes registrada |
| `product_description` | Lo que compró el cliente, en lenguaje sencillo |
| `service_date` | Cuándo prestaste el servicio (International Organization for Standardization (ISO) 8601) |
| `billing_address` | La dirección usada en el checkout |
| `customer_communication_attachment` | Hilos de correo electrónico o chat que muestran la interacción del cliente |
| `cancellation_policy_attachment` / `cancellation_policy_disclosure` | Tu política y la prueba de que el cliente la aceptó |
| `refund_policy_attachment` / `refund_policy_disclosure` | Lo mismo para los reembolsos |
| `refund_refusal_explanation` | Por qué no reembolsaste (p. ej., uso fuera del plazo de devolución) |
| `access_activity_log` | Registros de inicio de sesión o de uso que demuestran que el cliente usó el producto |
| `uncategorized_attachment` | Cualquier otra cosa relevante |

Los campos de adjuntos aceptan un archivo subido como `{ id: file.id }`. Súbelo primero mediante la [API de archivos](https://docs.whop.com/es/developer/guides/upload-files.md).

### Estados de disputa

La disputa avanza a través de una máquina de estados. Hay dos fases: la fase de alerta temprana (estados con el prefijo `warning_`, que se notifican mediante `dispute_alert.created`) y la fase de disputa formal. Todos los estados que puede devolver el SDK:

| Estado | Fase | Significado |
| - | - | - |
| `warning_needs_response` | Alerta | Hay una alerta de disputa abierta. Puedes adelantarte con un reembolso o una respuesta antes de que escale. |
| `warning_under_review` | Alerta | Respondiste a la alerta y el procesador está decidiendo si escalarla. |
| `warning_closed` | Alerta | La alerta se resolvió sin convertirse en una disputa formal. |
| `needs_response` | Disputa | Disputa formal abierta. Envía las pruebas antes de que se cierre el plazo de respuesta. |
| `under_review` | Disputa | Enviaste las pruebas y el procesador está decidiendo. |
| `won` | Disputa | Los fondos se quedan contigo. |
| `lost` | Disputa | Los fondos vuelven al comprador. Whop revierte el pago original. |
| `prevented` | Disputa | Se reembolsó al cliente antes de cualquier resolución. Se liquida como `lost`. |

> [!NOTE]
>
> Cuando una disputa se **pierde**, Whop no crea automáticamente un registro de reembolso y tampoco puedes crearlo tú. `payments.refund` rechaza las llamadas sobre un pago disputado con `This payment has been disputed. Therefore, it cannot be refunded.` Toma la disputa perdida como fuente de verdad y no esperes un evento `refund.created`.

## Permisos

| Acción | Permiso requerido |
| - | - |
| Crear un reembolso | `payment:manage` |
| Obtener / listar reembolsos | `payment:basic:read` |
| Obtener / listar disputas | `payment:dispute:read` |
| Actualizar o enviar pruebas | `payment:dispute` |

Añádelos desde la [guía de permisos](https://docs.whop.com/es/developer/guides/permissions.md).

## Próximos pasos

> [card] [Aceptar pagos](https://docs.whop.com/es/developer/guides/accept-payments.md)
>
> El flujo que crea los pagos que más adelante reembolsarás o defenderás.

> [card] [Escuchar webhooks](https://docs.whop.com/es/developer/guides/webhooks.md)
>
> Reacciona a los eventos de reembolsos y disputas en el servidor.

> [card] [Subir archivos](https://docs.whop.com/es/developer/guides/upload-files.md)
>
> Sube adjuntos de pruebas para las respuestas a disputas.

> [card] [Referencia de la API de disputas](https://docs.whop.com/es/api-reference/disputes/dispute)
>
> El recurso completo: campos, estados y todos los endpoints.
