Skip to main content

Disputes

A dispute (chargeback) occurs when a customer contests a payment with their bank or card issuer. Use the dispute service to list disputes, submit evidence, and manage dispute resolution. Evidence can include files (documents, screenshots) or text (descriptions, explanations).

import { createOakClient, createDisputeService } from '@oaknetwork/payments-sdk';

const client = createOakClient({ ... });
const disputes = createDisputeService(client);

Methods​

MethodDescription
list(query?)List disputes with optional filters
updateEvidence(disputeId, evidence)Add or update evidence for a dispute
submit(disputeId)Submit a dispute for review
close(disputeId)Close a dispute (accept the chargeback)

List disputes​

const result = await disputes.list({
limit: 20,
offset: 0,
});

if (result.ok) {
for (const dispute of result.value.data) {
console.log(`${dispute.id} — ${dispute.status} — ${dispute.amount}`);
}
}

Update evidence​

Add evidence to support your case. Evidence can be files or text:

File evidence​

const result = await disputes.updateEvidence('dsp_abc123', {
type: 'file',
file_id: 'file_xyz789',
category: 'receipt',
description: 'Original purchase receipt',
});

if (result.ok) {
console.log('Evidence added');
}

Text evidence​

const result = await disputes.updateEvidence('dsp_abc123', {
type: 'text',
category: 'customer_communication',
content: 'Customer confirmed receipt of goods via email on 2026-04-15.',
});

if (result.ok) {
console.log('Evidence added');
}

Evidence request fields​

FieldTypeRequiredDescription
type"file" | "text"YesEvidence type
file_idstringFile onlyID of an uploaded file
categorystringYesEvidence category (e.g., "receipt", "customer_communication")
descriptionstringNoDescription of the evidence
contentstringText onlyText content of the evidence

Submit a dispute​

After adding all evidence, submit the dispute for review:

const result = await disputes.submit('dsp_abc123');

if (result.ok) {
console.log('Dispute submitted for review');
}

Close a dispute​

Accept the chargeback and close the dispute:

const result = await disputes.close('dsp_abc123');

if (result.ok) {
console.log('Dispute closed');
}

Response data​

FieldTypeDescription
idstringDispute ID
payment_idstringAssociated payment ID
statusstringDispute status
amountnumberDisputed amount
reasonstringDispute reason
evidencearraySubmitted evidence items
created_atstringISO timestamp
updated_atstringISO timestamp