Sign in

v1

latestOpenAPI 3.0.22026-08-061303782.1 MB
Disputes

Update Dispute

Update tags on a Dispute.

put/disputes/{dispute_id}

Request body

tagsTags nullable

Include up to 50 key: value pairs to annotate requests with custom metadata.

  • Maximum character length for individual keys is 40.
  • Maximum character length for individual values is 500. (For example, order_number: 25, item_type: produce, department: sales)

Response

A single Dispute

idstring

The ID of the resource.

created_atstring date-time

Timestamp of when the object was created.

updated_atstring date-time

Timestamp of when the object was last updated.

actionstring nullable

The next action required to move forward with the Dispute.

amountinteger nullable

The total amount of the Dispute (in cents).

applicationstring

ID of the Application the resource was created under.

evidence_submitted'INQUIRY' | 'CHARGEBACK' | 'NONE' | 'NOT_SUPPORTED' | 'UNKNOWN'

The status of the uploaded evidence after it has been submitted to the issuing bank. This field reflects how the Dispute is moving forward following the submission of dispute evidence. For more information on challenging a Dispute, see Responding to Disputes.

Possible values are:

  • INQUIRY: Updated to this value if Dispute#state is INQUIRY at the time of submission.
  • CHARGEBACK: Updated to this value if Dispute#state is PENDING at the time of submission.
  • NONE: No evidence has been uploaded or submitted yet.
  • NOT_SUPPORTED: The processor or dispute type (Dispute#reason) does not support evidence submission.
  • UNKNOWN: Occurs if evidence details couldn't be successfully processed or retrieved.
identitystring

The ID of the seller's Identity resource. This is the Identity resource that was used to create the seller's Merchant.

merchantstring

The ID of the seller's Merchant resource. This is the Merchant account the Dispute was filed against.

messagestring nullable

Additional dispute details. This field is typically null.

occurred_atstring date-time nullable

A timestamp of when the disputed Transfer was created.

reason'CLERICAL' | 'FRAUD' | 'INQUIRY' | 'QUALITY' | 'TECHNICAL'

The system-defined reason for the Dispute. Available values include:

  • CLERICAL: An error occurred while processing the sale, or the cardholder has an issue with the transaction and refuses the goods.
  • FRAUD: The cardholder claims they didn't approve or authorize the transaction. FRAUD is the primary reason disputes get created.
  • INQUIRY: The issuing bank requests more information to determine if a transaction was legitimate.
  • QUALITY: The cardholder has issues with the quality of the goods or services received. Reasons can include receiving damaged goods or a service that doesn't match what's promised.
  • TECHNICAL: A technical issued caused the transaction to process funds incorrectly.
respond_bystring date-time nullable

A timestamp of when the Merchant must respond to the Dispute.

response_state'NEEDS_RESPONSE' | 'RESPONDED' | 'ACCEPTED' | 'NO_RESPONSE_ALLOWED' | 'UNKNOWN'

Details the state of the Dispute and what action the Merchant needs to take. Possible values are:

  • NEEDS_RESPONSE: The Merchant needs to respond to the Dispute by the Dispute#respond_by timestamp. For details on how to respond to a Dispute, see Responding to Disputes.
  • RESPONDED: The issuing bank has received the evidence and actively reviewing it. No action needed from the Merchant.
  • ACCEPTED: The Merchant has accepted the Dispute. When a Dispute is accepted, you concede that the Dispute is not worth challenging or representing. For details on how to accept a Dispute, see Accepting a Dispute.
  • NO_RESPONSE_ALLOWED: The final Dispute#response_state when a Dispute is either WON or LOST.
  • UNKNOWN: Occurs when testing Disputes in the sandbox on the DUMMY_V1 processor or in production on the VANTIV_V1 processor.
state'INQUIRY' | 'PENDING' | 'LOST' | 'WON'

The current overall state of the Dispute. Disputes are initially created with a PENDING state. The decision of the issuing bank is final for all parties. Possible values include:

  • INQUIRY: The Dispute is being reviewed by the buyer's issuing bank. No changes can be made while in this state. If a Dispute reaches this state, the bank is requesting additional information from the seller to prove the transaction was legitimate.
  • PENDING: The default initial state of a Dispute. It also acts as a transitional state after an accept request is submitted. The state will eventually change based on the transaction type:
    • For a dispute on a sale: Changes to LOST when accepted.
    • For a dispute on a refund: Changes to WON when accepted.
  • LOST: The Dispute is lost, and the cardholder keeps the credit. No further changes can be made.
  • WON: The Dispute is won, the credit is reversed, and funds are returned to the Merchant. No further changes can be made. For more details, see Dispute States.
transferstring

ID of the Transfer resource.

tagsTags nullable

Include up to 50 key: value pairs to annotate requests with custom metadata.

  • Maximum character length for individual keys is 40.
  • Maximum character length for individual values is 500. (For example, order_number: 25, item_type: produce, department: sales)

Example response

{
  "transfer": "TRxxxxxxxxxxxxxxxxxx"
}