# Update dispute

Update one or more dispute fields. Parameters that are not passed are not updated.

**Note:** You can only update a dispute if its group status is `OPEN`, `FAILED`, `DENIED` or `MIGRATION`. Refer to the [Dispute state machine](https://developers.pismo.io/pismo-docs/docs/disputes-state-machine) for more information.


# OpenAPI definition

```json
{
  "openapi": "3.0.1",
  "info": {
    "title": "Card issuing - Disputes",
    "version": "1.0.0",
    "description": "Disputes API endpoints",
    "contact": {
      "name": "API Support",
      "url": "https://developers.pismo.io/support/"
    },
    "license": {
      "name": "Copyright Pismo"
    }
  },
  "servers": [
    {
      "url": "https://sandbox.pismolabs.io/disputes",
      "description": "Sandbox API server for testing"
    }
  ],
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "tags": [
    {
      "name": "Disputes",
      "description": "Endpoints to create and manage disputes"
    }
  ],
  "components": {
    "parameters": {
      "disputeId": {
        "name": "disputeId",
        "in": "path",
        "description": "Dispute ID",
        "required": true,
        "schema": {
          "type": "number"
        }
      }
    },
    "schemas": {
      "AccountID": {
        "type": "number",
        "description": "Pismo account ID",
        "example": 577830
      },
      "OrgID": {
        "type": "string",
        "description": "Organization/tenant ID.",
        "example": "TN-34778262-f4f0-464d-b4c6-a14exxxxxxxx"
      },
      "TransactionAmount": {
        "type": "number",
        "description": "Transaction amount",
        "example": 86753.09
      },
      "reasonCode": {
        "type": "number",
        "description": "Each card network, such as Visa or Mastercard, defines and maintains their own unique set of reason codes, which banks that issue credit and debit cards under their brands apply to disputes. Here's a reason code [quick reference](https://www.chargebackgurus.com/blog/a-definitive-guide-to-chargeback-reason-codes-by-card-network#chargback-reason-code-quick-reference-guide) for the major credit card networks.\n\nFor Visa, this would be either `10` (fraud - card present), `11` (authorization), `12` (processing error), or `13` (consumer dispute).\n\nFor more infomation, refer to the [Visa](https://usa.visa.com/dam/VCOM/global/support-legal/documents/chargeback-management-guidelines-for-visa-merchants-vbs-19-may-16-%20v2.pdf) or [Mastercard](https://www.mastercard.us/content/dam/public/mastercardcom/na/global-site/documents/chargeback-guide.pdf) chargeback quides.\n\nFor example - `4853` (Mastercard - cardholder dispute), `12` (Visa - processing error) or `72` (ELO - denied authorization)\n",
        "example": 4853
      },
      "DisputeGroupStatus": {
        "description": "Group status enums\n",
        "type": "string",
        "example": "OPEN",
        "enum": [
          "OPEN",
          "APPROVED",
          "DENIED",
          "CARDNETWORK_CHARGEBACK",
          "ANALYSING",
          "CARDNETWORK_SECOND_PRESENTMENT",
          "FAILED",
          "CARDNETWORK_PREARBITRATION",
          "RESEND",
          "LOSS",
          "WON",
          "REJECTED",
          "FAILED_PROCESSED"
        ]
      },
      "DisputeStatus": {
        "type": "string",
        "description": "Dispute status enums.\n",
        "example": "PENDING",
        "enum": [
          "OPENED",
          "PENDING",
          "CANCELED",
          "FAILED",
          "CHARGEBACK_REJECTED",
          "CHARGEBACK_CREATED",
          "CHARGEBACK_ACCEPTED",
          "CHARGEBACK_CLOSED",
          "SECOND_PRESENTMENT",
          "PRE_ARBITRATION_OPENED",
          "PRE_ARBITRATION_ACCEPTED",
          "PRE_ARBITRATION_DECLINED",
          "PRE_ARBITRATION_RECALL",
          "PRE_ARB_ALLOCATION_OPENED",
          "FAILED_PRE_ARBITRATION",
          "PRE_ARB_ALLOCATION_ACCEPTED",
          "PRE_ARB_ALLOCATION_DECLINED",
          "PRE_ARB_ALLOCATION_RECALLED",
          "FAILED_DECLINE_PRE_ARB",
          "FAILED_ACCEPT_PRE_ARB",
          "FAILED_ON_CLOSE",
          "EXPIRED",
          "ISSUER_LOSS",
          "MIGRATION",
          "FAILED_MIGRATION"
        ]
      },
      "DisputeResponse": {
        "type": "object",
        "properties": {
          "id": {
            "type": "number",
            "example": 1,
            "description": "Dispute ID."
          },
          "org_id": {
            "$ref": "#/components/schemas/OrgID"
          },
          "account_id": {
            "$ref": "#/components/schemas/AccountID"
          },
          "authorization_id": {
            "type": "number",
            "example": 4352243,
            "description": "Authorization ID."
          },
          "comment": {
            "type": "string",
            "example": "Some comment",
            "description": "Custom client comment.",
            "nullable": true
          },
          "dispute_reason": {
            "$ref": "#/components/schemas/reasonCode"
          },
          "modality": {
            "type": "number",
            "example": 4855,
            "description": "Dispute *modality* - legacy term for reason code to file the dispute."
          },
          "dispute_status": {
            "$ref": "#/components/schemas/DisputeStatus"
          },
          "dispute_status_group": {
            "$ref": "#/components/schemas/DisputeGroupStatus"
          },
          "created_at": {
            "type": "string",
            "example": "2021-02-21",
            "description": "Dispute created date, format = yyyy-mm-dd.",
            "format": "date"
          },
          "updated_at": {
            "type": "string",
            "example": "2021-02-22",
            "description": "Dispute last updated date, format = yyyy-mm-dd.",
            "format": "date"
          },
          "created_at_utc": {
            "type": "string",
            "example": "2021-02-21T22:51:43.000000000Z",
            "description": "Dispute created as UTC date (ISO-8601).",
            "format": "date-time"
          },
          "updated_at_utc": {
            "type": "string",
            "description": "Dispute last updated as UTC date (ISO-8601).",
            "example": "2021-02-25T01:43:06.000000000Z",
            "format": "date-time"
          },
          "timeline": {
            "type": "string",
            "example": "{ \"data\": \"test\"}",
            "description": "Client custom timeline information.",
            "nullable": true
          },
          "protocol": {
            "type": "string",
            "example": "20190321L123456",
            "description": "Client custom protocol ID. This is primarily for you to internally identify a request. If not provided, Pismo creates a CID (correlation ID) field for this purpose.\n"
          },
          "metadata": {
            "type": "object",
            "description": "Can be used for caller's dispute information and process. Objects and name-value pairs."
          },
          "disputed_amount": {
            "type": "number",
            "example": 10,
            "description": "Disputed amount."
          },
          "is_network": {
            "type": "boolean",
            "example": true,
            "description": "Does dispute have a network authorization?"
          },
          "is_dispute_migrated": {
            "type": "boolean",
            "description": "Has this dispute been migrated to the Pismo platform?",
            "example": false
          },
          "reversal_id": {
            "type": "number",
            "description": "Event-generated reversal ID",
            "example": 123
          },
          "network_return_reason_code": {
            "type": "string",
            "description": "Network reason code.",
            "example": "4853"
          },
          "network_brand_type": {
            "$ref": "#/components/schemas/NetworkBrand"
          },
          "transaction_date": {
            "type": "string",
            "description": "Transaction date, format = yyyy-mm-dd hh:mm:ss",
            "example": "2022-08-04 14:26:20"
          },
          "transaction_amount": {
            "$ref": "#/components/schemas/TransactionAmount"
          },
          "currency_code": {
            "type": "string",
            "description": "ISO-4217 code for transaction currency. For example, `986` = Brazilian real.  \n",
            "example": "986"
          }
        }
      },
      "NetworkBrand": {
        "type": "string",
        "example": "Visa",
        "description": "Network brand",
        "enum": [
          "Visa",
          "Mastercard",
          "Elo"
        ]
      },
      "UpdateDisputeRequest": {
        "type": "object",
        "properties": {
          "disputed_amount": {
            "type": "number",
            "description": "Amount under dispute.",
            "example": 215
          },
          "currency_code": {
            "type": "string",
            "description": "ISO-4217 code for transaction currency. For example, 986 = Brazilian real.  \n\n**Note:** Only allowed if you are updating a dispute in a Zero balance program.\n",
            "example": "986"
          },
          "reason_code": {
            "$ref": "#/components/schemas/reasonCode"
          },
          "comment": {
            "type": "string",
            "example": "Some comment",
            "maxLength": 5000,
            "description": "Updated dispute comment."
          },
          "first_installment_amount": {
            "type": "number",
            "description": "Amount to be updated on first installment chargeback.",
            "example": 86753.09
          },
          "stop_automated_installment": {
            "type": "boolean",
            "description": "Stop automated dispute installment control. If an issuer opens a dispute for a transaction that has more than one installment, with installments that can still be posted, the issuer will need to open a dispute for subsequent installments as well. With automated dispute installment control, once you open a chargeback for the first installment, the same information can be used for subsequent transaction installments. Default = `false`.\n",
            "example": true
          },
          "transaction_amount": {
            "type": "number",
            "description": "Transaction amount.\n\n**Note:** Only allowed if you are updating a dispute in a Zero balance program.\n",
            "example": 86753.09
          },
          "arn": {
            "type": "string",
            "description": "Acquirer reference number for first installment\n\n**Note:** Only allowed if you are updating a dispute in a Zero balance program.\n",
            "maxLength": 255,
            "example": "73669599903"
          },
          "transaction_date": {
            "type": "string",
            "description": "Transaction date. Format = yyyy-mm-dd\n\n **Note:** Only allowed if you are updating a dispute in a Zero balance program.\n",
            "example": "2025-09-23"
          }
        }
      }
    },
    "securitySchemes": {
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "Account access token. Tokens can expire quickly, which can result in an \"Unauthorized\" error.",
        "bearerFormat": "JWT"
      }
    },
    "responses": {
      "400BadRequest": {
        "description": "Bad Request"
      },
      "401Unauthorized": {
        "description": "Unauthorized. Invalid or missing access token."
      },
      "404NotFound": {
        "description": "Not found"
      },
      "422UnprocessableEntity": {
        "description": "Unprocessable entity"
      },
      "500InternalServerError": {
        "description": "Internal server error"
      }
    }
  },
  "paths": {
    "/v1/disputes/{disputeId}": {
      "put": {
        "summary": "Update dispute",
        "description": "Update one or more dispute fields. Parameters that are not passed are not updated.\n\n**Note:** You can only update a dispute if its group status is `OPEN`, `FAILED`, `DENIED` or `MIGRATION`. Refer to the [Dispute state machine](https://developers.pismo.io/pismo-docs/docs/disputes-state-machine) for more information.\n",
        "operationId": "put-v1-disputes-disputeId",
        "tags": [
          "Disputes"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/disputeId"
          }
        ],
        "requestBody": {
          "description": "New Dispute reason code and comment.",
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UpdateDisputeRequest"
              },
              "examples": {
                "Update a Dispute with success": {
                  "value": {
                    "reason_code": 42,
                    "comment": "Some comment",
                    "stop_automated_installment": true
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DisputeResponse"
                },
                "examples": {
                  "Updated Dispute": {
                    "value": {
                      "id": 1,
                      "org_id": "123456789",
                      "account_id": 30605,
                      "authorization_id": 4352243,
                      "comment": "Some comment",
                      "dispute_reason": 4855,
                      "modality": 4855,
                      "dispute_status": "PENDING",
                      "timeline": "{ \"data\": \"test\"}",
                      "protocol": "20190321L123456"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/400BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/401Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/404NotFound"
          },
          "422": {
            "$ref": "#/components/responses/422UnprocessableEntity"
          },
          "500": {
            "$ref": "#/components/responses/500InternalServerError"
          }
        }
      }
    }
  }
}
```