К основному содержанию
скилл CX Codex

refunds-and-disputes — скилл для Claude Code: функции и установка

Скилл refunds-and-disputes обучает агента управлять возвратами и спорами в Dodo Payments. Помогает настроить вебхуки, частичные выплаты по позициям заказа и отзыв доступа у клиентов.

MIT 208 установок ★ 14 обновлён 2026-10-20

Установить в Claude Code · Через Skills CLI (Vercel) Все способы и платформы ↓
npx skills add dodopayments/skills --skill refunds-and-disputes -a claude-code
Открыть на GitHub

Что делает refunds-and-disputes

Скилл добавляет в контекст правила работы с API Dodo Payments для оформления полных и частичных возвратов, а также обработки споров по чарджбэкам. Агент узнаёт структуру методов SDK dodopayments, четыре статуса возврата (pending, succeeded, review, failed) и логику синхронизации прав пользователя.

Все суммы в API передаются строго в минимальных единицах валюты — например, в центах для USD или пайсах для INR. Споры нельзя создать через API вручную: они приходят только со стороны карточных сетей, а сервис выступает в роли Merchant of Record.

Для боевой работы понадобятся переменные окружения DODO_PAYMENTS_API_KEY и DODO_PAYMENTS_WEBHOOK_KEY. Если вебхук возвращает ошибку или статус 500, Dodo повторит отправку события.

Какие задачи решает

  • оформить частичный возврат по конкретным позициям заказа
  • настроить проверку подписи и обработку вебхуков возвратов в Express
  • отозвать права доступа клиента при подтверждённом чарджбэке
  • восстановить доступ пользователю после выигрыша спора

Примеры запросов агенту

  • Напиши функцию частичного возврата для второго товара в заказе pay_abc123 через Dodo Payments
  • Сделай Express-эндпоинт для вебхуков Dodo с проверкой подписи и обработкой refund.succeeded
  • Покажи, как отозвать доступ к аккаунту при открытии спора и вернуть его по событию dispute.won

Как установить refunds-and-disputes

1Через Skills CLI (Vercel)

npx skills add dodopayments/skills --skill refunds-and-disputes -a claude-code

2Вручную: положить файлы

~/.claude/skills/refunds-and-disputes/SKILL.md

Папка скилла целиком; для одного проекта — .claude/skills/refunds-and-disputes/

По шагам, с командами для каждой платформы: Как установить скилл в Claude Code: пять способов

Вопросы о refunds-and-disputes

Как установить refunds-and-disputes в Claude Code?

Выполните в терминале команду npx skills add dodopayments/skills --skill refunds-and-disputes -a claude-code. Файл навыка сохранится по пути ~/.claude/skills/refunds-and-disputes/SKILL.md.

Что делает скилл refunds-and-disputes?

Он предоставляет ИИ-ассистенту готовые шаблоны кода и правила для работы с возвратами и чарджбэками в Dodo Payments. Агент учится вызывать методы SDK, отслеживать статусы платежей и управлять правами покупателей.

Можно ли создать спор по платежу через API?

Нет, споры инициируются исключительно карточной сетью покупателя. Через API Dodo Payments можно только получать их списки, запрашивать детали и передавать доказательства.

Исходный текст

SKILL.md · MIT
---
name: refunds-and-disputes
description: Dodo Payments refunds and disputes, covering full and partial refunds, refund statuses, dispute and chargeback lifecycle events, evidence, and revoking or restoring customer access. Use when issuing a refund, handling refund or dispute webhooks, responding to a chargeback, or reconciling entitlements after a payment reversal.
---

# Refunds and Disputes

This skill covers issuing refunds (full and partial), handling the dispute lifecycle, and managing customer access during payment reversals. Disputes are inbound-only; Dodo handles the card-network process as Merchant of Record while you control application access and evidence gathering.

## When to use this skill

- You need to issue a refund (full or partial) for a payment
- A customer disputes a charge and you need to respond with evidence
- You're building access-revocation logic tied to refund or dispute status
- You need to reconcile customer entitlements after a payment reversal
- You're handling refund or dispute webhooks in production

## Core concepts

**Refunds** are initiated by you via the API. Each refund has a status that tells you whether the money has actually left your account. Partial refunds target specific line items in the original payment.

**Disputes** are initiated by the customer's card network. You cannot create them; you only list and retrieve them. The dispute lifecycle spans seven events, each requiring different application actions.

**Amounts** are always in the smallest currency unit (cents for USD, paise for INR, etc.).

**Access revocation** means removing the customer's ability to use the product or service. On a dispute, you typically revoke access while it's open. Restore it on `dispute.won` or `dispute.cancelled` (withdrawn, no further action needed); the losing outcomes (`dispute.accepted`, `dispute.lost`, `dispute.expired`) keep access revoked.

## Refunds

### Create a refund

```typescript
import DodoPayments from 'dodopayments';

const client = new DodoPayments({
  bearerToken: process.env.DODO_PAYMENTS_API_KEY,
  environment: 'test_mode',
});

// Full refund
const refund = await client.refunds.create({
  payment_id: 'pay_abc123',
});

console.log(refund.refund_id);
console.log(refund.status); // 'pending', 'succeeded', 'review', or 'failed'
```

### Partial refund by item

To refund only specific items from a payment, pass the `items` array with each item ID and the amount to refund in the smallest currency unit. Omit `amount` to refund the whole item:

```typescript
const partialRefund = await client.refunds.create({
  payment_id: 'pay_abc123',
  items: [
    { item_id: 'item_1' }, // no amount: the whole item is refunded
    { item_id: 'item_2', amount: 2500 },
  ],
});
```

### Refund statuses

Each refund has one of four statuses:

| Status | Meaning | Your action |
|---|---|---|
| `pending` | Refund is processing; money hasn't left your account yet | Wait for a webhook or poll the refund status |
| `succeeded` | Money has been returned to the customer | Revoke access if the product is non-refundable; update your records |
| `review` | Refund is under review (rare) | Contact support; do not assume it will succeed |
| `failed` | Refund failed; money remains in your account | Investigate the failure; consider retrying or contacting the customer |

### List and retrieve refunds

```typescript
// List all refunds
const refunds = await client.refunds.list();

// Retrieve a specific refund
const refund = await client.refunds.retrieve('ref_xyz789');
console.log(refund.status);
```

### Handle refund webhooks

Webhook signature verification is covered in the `webhook-integration` skill. Always verify the signature before processing.

```typescript
import DodoPayments from 'dodopayments';
import express from 'express';

const app = express();
app.use(express.raw({ type: 'application/json' }));

// `environment` is a narrow union, but env vars are `string | undefined`.
// Narrow explicitly rather than casting, and default to test mode so a missing
// variable can never accidentally hit live.
const environment = process.env.DODO_PAYMENTS_ENVIRONMENT === 'live_mode' ? 'live_mode' : 'test_mode';

const client = new DodoPayments({
  bearerToken: process.env.DODO_PAYMENTS_API_KEY,
  environment,
  webhookKey: process.env.DODO_PAYMENTS_WEBHOOK_KEY,
});

type WebhookEvent = ReturnType<typeof client.webhooks.unwrap>;

// Register ONE endpoint for every Dodo event. A second app.post('/webhook')
// would never run, because the first handler answers every request.
app.post('/webhook', async (req, res) => {
  let event: WebhookEvent;
  try {
    event = client.webhooks.unwrap(req.body.toString(), {
      headers: {
        'webhook-id': req.headers['webhook-id'] as string,
        'webhook-signature': req.headers['webhook-signature'] as string,
        'webhook-timestamp': req.headers['webhook-timestamp'] as string,
      },
    });
  } catch {
    // Only signature verification failures reach this branch
    res.status(401).json({ error: 'Invalid signature' });
    return;
  }

  try {
    await handleRefundEvent(event);
    await handleDisputeEvent(event); // defined under "Handle dispute webhooks"
    res.json({ received: true });
  } catch (error) {
    // Any non-2xx response makes Dodo retry the delivery
    console.error('Webhook handler failed:', error);
    res.status(500).json({ error: 'Webhook handler failed' });
  }
});

async function handleRefundEvent(event: WebhookEvent) {
  if (event.type === 'refund.succeeded') {
    const refund = event.data;
    if (!refund.is_partial) {
      // Full refund: nothing in the payment is still paid for
      await revokeCustomerAccess(refund.customer.customer_id);
    } else {
      // Partial refund: keep access to items that are still paid for, and
      // remove it for any item with nothing left to refund. Reading the line
      // items covers every case - an omitted amount, an explicit amount equal
      // to the item price, or several partial refunds that add up to it.
      const { items } = await client.payments.retrieveLineItems(refund.payment_id);
      const fullyRefundedItemIds = items
        .filter((item) => item.refundable_amount === 0)
        .map((item) => item.items_id);
      await revokeItemAccess(refund.customer.customer_id, fullyRefundedItemIds);
    }
    await updateRefundRecord(refund.refund_id, 'succeeded');
  }

  if (event.type === 'refund.failed') {
    const refund = event.data;
    // Refund failed; keep access active, alert support
    await logRefundFailure(refund.refund_id, refund.reason);
  }
}
```

## Disputes

### Retrieve disputes

Disputes are inbound-only. You cannot create them; you can only list and retrieve them.

```typescript
// List all disputes
const disputes = await client.disputes.list();

// Retrieve a specific dispute
const dispute = await client.disputes.retrieve('dis_abc123');
console.log(dispute.dispute_status);
console.log(dispute.amount); // in smallest currency unit
```

### Dispute lifecycle

A dispute moves through seven events. Each event requires a different action from your application:

| Event | Meaning | Your action |
|---|---|---|
| `dispute.opened` | Customer initiated a chargeback | Record the dispute; consider revoking access immediately; gather evidence from your logs |
| `dispute.challenged` | You submitted evidence | Wait for the card network to review |
| `dispute.accepted` | You accepted (conceded) the dispute; funds go to the cardholder | Keep access revoked; mark the dispute as accepted in your records |
| `dispute.cancelled` | The dispute was withdrawn or cancelled | No further action needed; restore access you revoked on `dispute.opened` |
| `dispute.expired` | Dispute window closed without resolution | Treat as lost; keep access revoked |
| `dispute.won` | You won the dispute | Funds are retained; restore access; update customer records |
| `dispute.lost` | You lost the dispute | Funds returned to cardholder; keep access revoked; reconcile your records |

### Handle dispute webhooks

Webhook dispute payloads intentionally contain no customer field. Resolve the customer with an extra `disputes.retrieve()` call: the webhook's `dispute_id` identifies the dispute, and the returned `GetDispute` includes `customer`. Without this lookup, access-control handlers would receive `undefined`.

```typescript
async function resolveDisputeCustomerId(disputeId: string) {
  const dispute = await client.disputes.retrieve(disputeId);
  return dispute.customer.customer_id;
}

// Called from the single /webhook handler above, after signature verification
async function handleDisputeEvent(event: WebhookEvent) {
  if (event.type === 'dispute.opened') {
    const dispute = event.data;
    // Record the dispute and revoke access
    await recordDispute(dispute.dispute_id, dispute.payment_id, dispute.amount);
    const customerId = await resolveDisputeCustomerId(dispute.dispute_id);
    await revokeCustomerAccess(customerId);
    // Gather evidence from your system and submit via dashboard
    // (no evidence-submission API exists; use the Dodo dashboard)
  }

  if (event.type === 'dispute.won') {
    const dispute = event.data;
    // Funds retained; restore normal state
    await markDisputeResolved(dispute.dispute_id, 'won');
    const customerId = await resolveDisputeCustomerId(dispute.dispute_id);
    await restoreCustomerAccess(customerId);
  }

  if (event.type === 'dispute.lost') {
    const dispute = event.data;
    // Funds returned to cardholder; keep access revoked
    await markDisputeResolved(dispute.dispute_id, 'lost');
    // Do NOT restore access
  }

  if (event.type === 'dispute.accepted') {
    const dispute = event.data;
    // Merchant conceded; funds go to the cardholder and access stays revoked
    await markDisputeResolved(dispute.dispute_id, 'accepted');
    // Do NOT restore access
  }

  if (event.type === 'dispute.cancelled') {
    const dispute = event.data;
    // The dispute was withdrawn; no further action is needed, so undo the
    // revocation from dispute.opened
    await markDisputeResolved(dispute.dispute_id, 'cancelled');
    const customerId = await resolveDisputeCustomerId(dispute.dispute_id);
    await restoreCustomerAccess(customerId);
  }
}
```

### Evidence submission

Dodo handles the card-network dispute process as Merchant of Record. You submit evidence through the Dodo dashboard, not via API. No evidence-submission API exists.

When a dispute opens, gather your evidence (order confirmation, delivery proof, customer communication, etc.) and upload it to the dashboard within the dispute window (10 days from when the dispute is created). The card network reviews your evidence and makes a final decision.

## Access revocation pattern

A common pattern for managing access during disputes:

```typescript
async function handleDisputeLifecycle(
  dispute: Awaited<ReturnType<typeof client.disputes.retrieve>>,
) {
  const customerId = dispute.customer.customer_id;

  switch (dispute.dispute_status) {
    case 'dispute_opened':
      // Revoke access immediately
      await revokeCustomerAccess(customerId);
      break;

    case 'dispute_won':
      // You won; restore access
      await restoreCustomerAccess(customerId);
      break;

    case 'dispute_lost':
      // You lost; keep access revoked
      // (do nothing)
      break;

    case 'dispute_accepted':
      // You conceded; funds go to the cardholder and access stays revoked
      break;

    case 'dispute_cancelled':
      // Withdrawn; no further action needed, so restore access
      await restoreCustomerAccess(customerId);
      break;

    case 'dispute_expired':
      // Treat as lost; keep access revoked
      break;

    case 'dispute_challenged':
      // Evidence is under review; keep access revoked
      break;
  }
}
```

## Reconciling entitlements after refund

When a refund succeeds, you must reconcile the customer's access. If the product is non-refundable (e.g., a digital download or subscription already used), revoke access. If it's refundable (e.g., a subscription not yet started), you may restore access or leave it revoked depending on your policy.

```typescript
async function reconcileRefund(refund) {
  if (refund.status !== 'succeeded') {
    return; // Not yet final
  }

  const payment = await client.payments.retrieve(refund.payment_id);
  const customer = payment.customer;

  // Revoke access for non-refundable products
  const includesNonRefundableProduct = payment.product_cart?.some(({ product_id }) =>
    isNonRefundable(product_id),
  );

  if (includesNonRefundableProduct) {
    await revokeCustomerAccess(customer.customer_id);
  }

  // Update your entitlement records
  await updateEntitlementRecord(customer.customer_id, {
    refund_id: refund.refund_id,
    refund_amount: refund.amount,
    refund_date: new Date(),
  });
}
```

## Common mistakes

**Auto-refunding without revoking access.** A refund webhook means money is leaving your account. If the product is non-refundable, revoke access immediately. Don't wait for the customer to ask.

**Treating `dispute.opened` as final.** A dispute is not lost until the card network says so. Keep access revoked while it's open, but don't delete customer data or close their account.

**Ignoring partial refunds when computing entitlements.** If a customer refunds only one item from a multi-item purchase, their entitlement to the other items remains valid. Track refunds by item, not just by payment.

**Restoring access on a losing outcome.** `dispute.accepted`, `dispute.lost`, and `dispute.expired` resolve (or typically resolve) in the cardholder's favor; keep access revoked. Restore access only on `dispute.won` or `dispute.cancelled` (the dispute was withdrawn and needs no further action).

**Submitting evidence after the dispute window closes.** You have 10 days from when the dispute is created to respond. Set a calendar reminder and gather evidence immediately when a dispute opens.

**Assuming Dodo will handle access revocation.** Dodo handles the card-network process; you handle application access. Dodo won't revoke your customer's subscription or file access automatically.

## Resources

- [Refunds API](https://docs.dodopayments.com/api-reference/refunds/post-refunds)
- [Refunds feature guide](https://docs.dodopayments.com/features/transactions/refunds)
- [Dispute webhooks](https://docs.dodopayments.com/developer-resources/webhooks/intents/dispute)
- The `webhook-integration` skill for signature verification

© dodopayments · MIT · dodopayments/skills

Похожие скиллы

Все скиллы по теме «Бэкенд и API» →
stripe Mindrally Правила интеграции Stripe в TypeScript, React и Next.js — приём платежей на сервере, подписки, вебхуки. Регламентирует реализацию оплаты в проекте. CX Codex +1 747установок dodopayments Dodo Payments Плагин dodopayments для Claude Code и Codex подключает интеграцию Dodo Payments к задачам с платежами, подписками и биллингом. Агент загружает подходящий скилл по запросу и может обращаться к API и документации через MCP. CX Codex ★ 1 596звёзд репо mcp-server InvoiceBox mcp-server — MCP-сервер для Claude Code: ассистент выставляет счета, проверяет оплату, подтверждает отгрузку и делает возврат с подтверждением человека. CX Codex +1 stripe-integration Seth Hobson Скилл stripe-integration для Claude Code подключает Stripe: Checkout, подписки, вебхуки, возвраты и сохранение способов оплаты. Описывает платёжные сценарии для веб- и мобильных приложений. CX Codex +1 13 404установок payment-testing kindlmann Скилл payment-testing для Claude Code помогает настроить сквозные проверки списаний, сценариев 3DS и вебхуков в песочницах Stripe, Adyen и PayPal с помощью Playwright. CX Codex +1 1 300установок stripe-payments jezweb Скилл stripe-payments для Claude Code добавляет приём платежей через Stripe: Checkout Sessions, подписки, вебхуки и портал клиента. Помогает выбрать нужный API и написать рабочий код интеграции. CX Codex +1 1 100установок

Из того же набора17

Весь набор →
license-keys Скилл license-keys настраивает проверку лицензионных ключей Dodo Payments в приложениях и CLI. Помогает ограничить число активаций на пользователя или устройство. CX Codex +1 696установок credit-based-billing Скилл credit-based-billing для биллинга на кредитах в Dodo Payments: пулы, гранты, списания по метрикам, перенос остатка и оверэдж. CX Codex +1 672установок testing-and-go-live Скилл testing-and-go-live проводит платёжную интеграцию Dodo Payments через тестовый режим: карты, отказы, продления, вебхуки. И доводит до боевого запуска по чек-листу. CX Codex +1 219установок framework-adapters Скилл framework-adapters подключает официальные адаптеры Dodo Payments в Next.js, Express, Hono или Nuxt. Настраивает маршруты для чекаута, портала клиента и вебхуков. CX Codex +1 209установок product-catalog-management Скилл product-catalog-management управляет каталогом Dodo Payments: создание разовых и регулярных тарифов, работа с аддонами и загрузка изображений. CX Codex +1 208установок customer-management Скилл customer-management для Claude Code управляет клиентами Dodo Payments: создаёт записи, настраивает портал и способы оплаты, ведёт кошельки и связывает пользователей приложения с ID клиентов для биллинга. CX Codex +1 202установок discounts-and-promotions Скилл discounts-and-promotions помогает настроить промокоды Dodo Payments: создать скидку, проверить её ограничения и разобраться, почему код не применяется. CX Codex +1 199установок localized-pricing Скилл localized-pricing помогает настроить мультивалютные расчёты в Dodo Payments: фиксированные региональные цены, конвертацию Adaptive Currency и скидки паритета покупательской способности (PPP). CX Codex +1 198установок

Спонсоры проекта

Компании, которые помогают держать аналитику открытой