Update Dispute

Update tags on a Dispute.

Endpoint: PUT /disputes/{dispute_id} Security: BasicAuth

Path parameters:

• dispute_id (string, required)
  The ID of Dispute.
  Example: "DIgDv9764vkkEVu1suZNCDbR"

Request fields (application/json):

• tags (object,null)
  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 200 fields (application/json):

• id (string)
  The ID of the resource.

• created_at (string)
  Timestamp of when the object was created.

• updated_at (string)
  Timestamp of when the object was last updated.

• action (string,null)
  The next action required to move forward with the Dispute.

• amount (integer,null)
  The total amount of the Dispute (in cents).

• application (string)
  ID of the Application the resource was created under.

• dispute_details (object)
  Details about the Dispute received by the processor. Any data from the processor can get included.

• dispute_details.case_id (string,null)
  The case number the processor has given the Dispute in their internal database.

• dispute_details.pin_debit_adjustment_number (string,null)
  A number used by the processor to identify the funds that are getting disputed.

• dispute_details.reason_code (string,null)
  A code used by the processor and card networks to identify why the Dispute got filed.

• evidence_submitted (string)
  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.
    Enum: "INQUIRY", "CHARGEBACK", "NONE", "NOT_SUPPORTED", "UNKNOWN"

• identity (string)
  The ID of the seller's Identity resource. This is the Identity resource that was used to create the seller's Merchant.

• merchant (string)
  The ID of the seller's Merchant resource. This is the Merchant account the Dispute was filed against.

• message (string,null)
  Additional dispute details. This field is typically null.

• occurred_at (string,null)
  A timestamp of when the disputed Transfer was created.

• reason (string)
  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.
    Enum: "CLERICAL", "FRAUD", "INQUIRY", "QUALITY", "TECHNICAL"

• respond_by (string,null)
  A timestamp of when the Merchant must respond to the Dispute.

• response_state (string)
  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. Enum: "NEEDS_RESPONSE", "RESPONDED", "ACCEPTED", "NO_RESPONSE_ALLOWED", "UNKNOWN"

• state (string)
  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. Enum: "INQUIRY", "PENDING", "LOST", "WON"

• transfer (string)
  ID of the Transfer resource.
  Example: "TRxxxxxxxxxxxxxxxxxx"

• _links (object)
  For your convenience, every response includes several URLs which link to resources relevant to the request. You can use these _links to make your follow-up requests and quickly access relevant IDs.

• _links.adjustment_transfers (object)

• _links.adjustment_transfers.href (string)

• _links.application (object)
  Link to the Application the resource was created under.

• _links.application.href (string)

• _links.evidence (object)

• _links.evidence.href (string)

• _links.self (object)
  Link to the resource that was used in the request.

• _links.self.href (string)

• _links.transfer (object)
  Link to the Transfers related to the Dispute.

• _links.transfer.href (string)

Response 400 fields (application/json):

• total (integer, required)
  Total number of errors returned.

• _embedded (object, required)
  Container for embedded error objects.

• _embedded.errors (array)
  List of individual error objects.

• _embedded.errors.code (string)
  The error code. The UNKNOWN error code is returned for a 401 Unauthorized or 403 Forbidden request.

• _embedded.errors.logref (string)
  A log reference identifier for the error, useful for debugging and support purposes.

• _embedded.errors.message (string)
  A human-friendly error message.

• _embedded.errors._links (object)
  Links related to this error.

• _embedded.errors._links.self (object)
  Link to the resource related to the error.

• _embedded.errors._links.self.href (string)
  URL of the related resource.

Response 401 fields (application/json):

• total (integer, required)
  Total number of errors returned.

• _embedded (object, required)
  Container for embedded error objects.

• _embedded.errors (array)
  List of individual error objects.

• _embedded.errors.code (string)
  The error code. The UNKNOWN error code is returned for a 401 Unauthorized or 403 Forbidden request.

• _embedded.errors.logref (string)
  A log reference identifier for the error, useful for debugging and support purposes.

• _embedded.errors.message (string)
  A human-friendly error message.

• _embedded.errors._links (object)
  Links related to this error.

• _embedded.errors._links.self (object)
  Link to the resource related to the error.

• _embedded.errors._links.self.href (string)
  URL of the related resource.

Response 403 fields (application/json):

• total (integer, required)
  Total number of errors returned.

• _embedded (object, required)
  Container for embedded error objects.

• _embedded.errors (array)
  List of individual error objects.

• _embedded.errors.code (string)
  The error code. The UNKNOWN error code is returned for a 401 Unauthorized or 403 Forbidden request.

• _embedded.errors.logref (string)
  A log reference identifier for the error, useful for debugging and support purposes.

• _embedded.errors.message (string)
  A human-friendly error message.

• _embedded.errors._links (object)
  Links related to this error.

• _embedded.errors._links.self (object)
  Link to the resource related to the error.

• _embedded.errors._links.self.href (string)
  URL of the related resource.

Response 404 fields (application/json):

• total (integer, required)
  Total number of errors returned.

• _embedded (object, required)
  Container for embedded error objects.

• _embedded.errors (array)
  List of individual error objects.

• _embedded.errors.code (string)
  The error code. The UNKNOWN error code is returned for a 401 Unauthorized or 403 Forbidden request.

• _embedded.errors.logref (string)
  A log reference identifier for the error, useful for debugging and support purposes.

• _embedded.errors.message (string)
  A human-friendly error message.

• _embedded.errors._links (object)
  Links related to this error.

• _embedded.errors._links.self (object)
  Link to the resource related to the error.

• _embedded.errors._links.self.href (string)
  URL of the related resource.

Response 406 fields (application/json):

• total (integer, required)
  Total number of errors returned.

• _embedded (object, required)
  Container for embedded error objects.

• _embedded.errors (array)
  List of individual error objects.

• _embedded.errors.code (string)
  The error code. The UNKNOWN error code is returned for a 401 Unauthorized or 403 Forbidden request.

• _embedded.errors.logref (string)
  A log reference identifier for the error, useful for debugging and support purposes.

• _embedded.errors.message (string)
  A human-friendly error message.

• _embedded.errors._links (object)
  Links related to this error.

• _embedded.errors._links.self (object)
  Link to the resource related to the error.

• _embedded.errors._links.self.href (string)
  URL of the related resource.