BiasDocs

Disputes

A dispute is a cardholder’s bank questioning a card payment, as a chargeback or an inquiry. You can contest it with evidence that the charge is legitimate, or accept the loss. A bank debit returned after it succeeded is also recorded as a dispute, which is lost and can’t be contested. The refunds and disputes guide covers dispute statuses and evidence.

The Dispute object

Name
object
Type
"dispute",
Description
The object's type.
Name
id
Type
string,
Description
Unique identifier for the object.
Name
live
Type
boolean,
Description
true if the object is live, or false if it's in a sandbox.
Name
created_at
Type
integer,
Description
When the object was created, in milliseconds since the Unix epoch.
Name
amount
Type
integer,
Description
The disputed amount, in cents.
Name
evidence
Type
object,
Description
Evidence you submit to contest the dispute.
Properties
Name
evidence_details
Type
object,
Description
When evidence is due and when it was submitted.
Properties
Name
loss_accepted
Type
boolean,
Description
Whether you accepted the loss. An accepted dispute takes no evidence, and accepting doesn't change status.
Name
metadata
Type
object,
Description
Your own key-value data on the object.
Name
payment
Type
string or Payment or null,
Description
Expandable. The disputed payment.
Name
payment_method_details
Type
object,
Description
Details for a card dispute or a returned bank debit.
Properties
Name
reason
Type
enum,
Description
Why the cardholder disputed the payment, or why the bank returned the debit.
Properties
Name
status
Type
enum,
Description
The status of the dispute.
Properties

The Dispute object

{
  "object": "dispute",
  "id": "du_iQ8bYlW1rHvDbKagXGTFj",
  "live": false,
  "created_at": 1750000000000,
  "amount": 1000,
  "evidence": {
    "access_activity_log": null,
    "billing_address": null,
    "cancellation_policy_disclosure": null,
    "cancellation_policy": null,
    "cancellation_rebuttal": null,
    "customer_communication": null,
    "customer_email": "john.doe@example.com",
    "customer_name": "John Doe",
    "customer_purchase_ip": null,
    "customer_signature": null,
    "duplicate_charge_documentation": null,
    "duplicate_charge_explanation": "The customer placed two separate orders for bindings, #1041 and #1042, and received both.",
    "duplicate_payment": null,
    "product_category": "physical",
    "product_description": "Snowboard bindings",
    "receipt": "file_nwjUEfzvIm7skTF9hlH4P2",
    "refund_policy_disclosure": null,
    "refund_policy": null,
    "refund_refusal_explanation": null,
    "service_date": null,
    "service_documentation": null,
    "shipping_address": null,
    "shipping_carrier": "UPS",
    "shipping_date": null,
    "shipping_documentation": null,
    "shipping_tracking_number": "1Z12345E0205271688",
    "terms_and_conditions": null,
    "uncategorized_file": null,
    "uncategorized_text": null,
    "win_reason": null
  },
  "evidence_details": {
    "due_by": 1752000000000,
    "submitted_at": null
  },
  "metadata": {},
  "payment_method_details": {
    "type": "card",
    "card": {
      "case_type": "chargeback",
      "network_reason_code": "12.6.1"
    },
    "us_bank_account": null
  },
  "payment": "pay_lUY2g0TuPzN9qi4couahd3",
  "reason": "duplicate",
  "status": "needs_response",
  "loss_accepted": false
}

Get a dispute

Retrieve a dispute by its ID.

Required parameters

Name
id
Type
string,
Description
The ID of the dispute to retrieve.

Optional parameters

Name
expand
Type
object,
Description
Related objects to expand in the response.
Properties

Returns

Returns the dispute object.

Retrieve a dispute

const dispute = await bias.disputes.get("id");

Response example

List all disputes

Retrieve a paginated list of disputes.

Optional parameters

Name
expand
Type
object,
Description
Related objects to expand in the response.
Properties
Name
ending_before
Type
string,
Description
The ID of the object to list before, for pagination.
Name
starting_after
Type
string,
Description
The ID of the object to list after, for pagination.
Name
limit
Type
integer, at least 1, at most 1000, default is 50
Description
The maximum number of objects to return, from 1 to 1000. Defaults to 50.
Name
filters
Type
object, object, or object,
Description
Filters for the list, combined with and and or.
Properties

Returns

Returns a list of dispute objects.

List all disputes

const dispute = await bias.disputes.list();

Response example

{
  "object": "list",
  "items": [],
  "has_more": true
}

Update a dispute

Updates save a dispute’s evidence as you gather it. With submit: true, the evidence goes to the cardholder’s bank and the dispute moves to under_review. Evidence is due by evidence_details.due_by and can’t change once it’s submitted.

Evidence documents are files uploaded with the purpose dispute_evidence.

With loss_accepted: true, you accept the loss and the dispute takes no evidence.

Required parameters

Name
id
Type
string,
Description
The ID of the dispute to update.

Optional parameters

Name
expand
Type
object,
Description
Related objects to expand in the response.
Properties
Name
evidence
Type
object,
Properties
Name
metadata
Type
object or null,
Description
Your own key-value data on the object.
Name
submit
Type
boolean, default is false
Description
Whether to submit the evidence to the cardholder's bank. Submitted evidence can't be changed.
Name
loss_accepted
Type
boolean,
Description
Whether to accept the loss instead of contesting the dispute. It can be changed while the dispute is needs_response or under_review.

Returns

Returns the dispute object.

Update a dispute

const dispute = await bias.disputes.update("id");

Response example