refunds-and-disputes

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 only on dispute.won; all other outcomes keep access revoked until you reconcile them separately.

Refunds

Create a refund

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: