Disputes & chargebacks

A dispute (chargeback) is initiated by a cardholder through their issuing bank. When opened, VINR debits the disputed amount from your balance, notifies you, and gives you a window to submit evidence. This page explains the dispute lifecycle, how to respond, and how to use the Disputes API.

Dispute lifecycleAskCopy

Opened → Evidence due → Under review → Won / Lost
                                     ↘ Accepted (no contest)

Dispute reason codesAskCopy

Reason codes identify the cardholder's claim. Defense requirements differ by code.

Full code reference is available in the API reference.

Responding to a disputeAskCopy

import { Vinr } from '@vinr/sdk';
const vinr = new Vinr({ secretKey: process.env.VINR_SECRET_KEY });

await vinr.disputes.update('dis_...', {
  evidence: {
    customerName: 'Maria Santos',
    customerEmailAddress: 'maria@example.com',
    productDescription: 'Annual SaaS subscription — confirmed in onboarding email',
    accessActivityLog: 'Customer logged in 47 times between purchase and dispute date',
    refundPolicy: 'No refunds after 14-day trial per Terms of Service section 8',
    // Attach files as base64 or upload separately via vinr.files.create()
    receiptUrl: 'https://cdn.example.com/receipts/inv_2026_04.pdf',
  },
  submit: true,   // false to save as draft, true to submit immediately
});

await vinr.disputes.accept('dis_...');

Uploading evidence filesAskCopy

Large evidence (PDFs, screenshots) should be uploaded as files first, then referenced in the evidence object:

import { readFileSync } from 'fs';

const file = await vinr.files.create({
  purpose: 'dispute_evidence',
  file: {
    data: readFileSync('tracking-screenshot.png'),
    name: 'tracking-screenshot.png',
    type: 'image/png',
  },
});

await vinr.disputes.update('dis_...', {
  evidence: { shippingDocumentation: file.id },
  submit: true,
});

Dispute webhooksAskCopy

Subscribe to these events to drive automated workflows:

// Webhook handler
const event = vinr.webhooks.verify(payload, signature);

if (event.type === 'dispute.opened') {
  const dis = event.data;
  await alertOpsTeam({
    id: dis.id,
    amount: dis.amount,
    currency: dis.currency,
    reason: dis.reason,
    evidenceDueBy: dis.evidenceDueBy,   // ISO 8601
  });
}

Preventing disputesAskCopy

Most disputes are preventable. High-impact interventions:

• 3D Secure — Shifts liability to the issuer for fraud.* reason codes. Enable on high-value or high-risk transactions.
• Clear billing descriptors — Cardholder confusion ("I don't recognize this charge") drives consumer_dispute.* disputes. Use a recognizable name.
• Prompt refunds — Process refunds within 5 business days to head off credit_not_processed disputes.
• Cancel subscriptions instantly — A customer who cancelled but was charged 30 days later is almost certain to dispute. Honor cancellations immediately.
• Send receipts — A receipt email gives you evidence and reduces post-purchase doubt.

Chargeback Uploader (bulk)AskCopy

For platforms or high-volume merchants, upload evidence files in bulk using the Chargeback Uploader. Prepare a ZIP archive following the upload format spec, then:

await vinr.disputes.bulkUpload({
  file: readFileSync('evidence-bundle.zip'),
  // Evidence is matched to disputes by payment ID from the manifest file inside the ZIP
});

Test a dispute scenarioAskCopy

Use test card 4000000000000259 (any future expiry, any CVC) to trigger an automatic dispute in test mode. The dispute is created approximately 7 seconds after the charge is captured, giving you a sandbox to test your webhook handler and evidence submission flow end-to-end.

Next stepsAskCopy