# Update dispute status
Change a dispute's status via an event. After creating a dispute and uploading all necessary forms, reports, and evidence files, send the event `OPEN` to officially begin the dispute process with the network.
For more information on events and statuses, refer to the Disputes state machine.
This endpoint generates a [Dispute status changed](https://developers.pismo.io/events/docs/disputes-dispute-installment-status-change-1) event.
# 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"
}
}
},
"Event": {
"type": "string",
"description": "Event enums. An event has to occur to change a dispute's status\n",
"example": "ISSUER_LOSS",
"enum": [
"ISSUER_WORKED",
"CANCEL",
"OPEN",
"FAILED_ON_CREATION",
"RESEND",
"REOPEN",
"REJECTS",
"FAILED_ON_CLOSE",
"CLOSED_PROCESSED",
"CLOSED",
"REJECTS_5000_5001",
"ISSUER_REPRESENTMENT_UNWORKED",
"ISSUER_LOSS",
"EXPIRE",
"SEND_PRE_ARBITRATION",
"ACCEPTED_PRE_ARBITRATION",
"REJECT_PRE_ARBITRATION",
"ACCEPT_PRE_ARBITRATION",
"DECLINE_PRE_ARBITRATION",
"RECALL_PRE_ARBITRATION",
"FAILED_ON_MIGRATION"
]
},
"NetworkBrand": {
"type": "string",
"example": "Visa",
"description": "Network brand",
"enum": [
"Visa",
"Mastercard",
"Elo"
]
}
},
"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"
},
"500InternalServerError": {
"description": "Internal server error"
}
}
},
"paths": {
"/v1/disputes/{disputeId}/event": {
"post": {
"summary": "Update dispute status",
"operationId": "post-v1-disputes-disputeId-event",
"description": "Change a dispute's status via an event. After creating a dispute and uploading all necessary forms, reports, and evidence files, send the event `OPEN` to officially begin the dispute process with the network.\n\nFor more information on events and statuses, refer to the Disputes state machine.\n\nThis endpoint generates a [Dispute status changed](https://developers.pismo.io/events/docs/disputes-dispute-installment-status-change-1) event.\n",
"tags": [
"Disputes"
],
"parameters": [
{
"$ref": "#/components/parameters/disputeId"
}
],
"requestBody": {
"description": "Event data.",
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"event": {
"$ref": "#/components/schemas/Event"
},
"reason": {
"type": "string",
"description": "Status change reason.",
"example": "Disputed by account holder."
},
"dispute_installment_id": {
"type": "number",
"description": "Dispute installment ID. If not passed, the first Installment is used.",
"example": 234
},
"memo": {
"type": "string",
"description": "Enter memo pertaining to the case. **REQUIRED** for ELO dispute. Also **REQUIRED** when `event` = `SEND_PRE_ARBITRATION` and network is Mastercard.\nMaximum length = 13000 chars.\n",
"maxLength": 13000,
"example": "Example memo"
},
"merchant_name": {
"type": "string",
"description": "Merchant name - 100 characters maximum.\n**REQUIRED** only for disputes without transaction and `event` = `SEND_PRE_ARBITRATION` and network is Mastercard.\n",
"maxLength": 100,
"example": "Acme Goods"
},
"updated_chargeback_reason_code": {
"$ref": "#/components/schemas/reasonCode"
},
"change_reason_code_reason": {
"type": "string",
"description": "Explanation for changing the reason code, if that's what you are doing - 1000 characters maximum.\n**REQUIRED** if `updated_chargeback_reason_code` is passed, `event` = `SEND_PRE_ARBITRATION` and network is Mastercard.\n",
"maxLength": 1000
},
"pre_arb_is_partial": {
"type": "boolean",
"description": "Pre-arbitration is for a partial amount and not the full amount?\nUsed when `event` = `SEND_PRE_ARBITRATION`.\n"
},
"pre_arb_currency_code": {
"type": "string",
"description": "ISO 4217 3-letter currency code, for example, `USD` (United States) or `BRL` (Brazilian Real).\n**REQUIRED** if `pre_arb_is_partial` = `true` and `event` = `SEND_PRE_ARBITRATION`.\n",
"example": "BRL",
"maxLength": 3
},
"justify_not_accepted_fully": {
"type": "string",
"description": "Explanation for asking for full or partial amount - 10000 characters maximum.\n**REQUIRED** if `pre_arb_is_partial` = `true` or `event` = DECLINE_PRE_ARBITRATION.\n",
"example": "Partial refund based on already being used",
"maxLength": 10000
},
"pre_arb_amount": {
"type": "number",
"description": "Pre-arbitration amount.\n**REQUIRED** if `pre_arb_is_partial` = `true` and `event` = `SEND_PRE_ARBITRATION`.\n",
"example": 18.36
},
"is_dispute_migrated": {
"type": "boolean",
"description": "Is dispute migrated? Default is `false`."
}
},
"required": [
"event",
"reason"
]
},
"examples": {
"Change a Dispute status with success": {
"value": {
"event": "OPEN",
"reason": "Disputed by account holder."
}
},
"Send Pre-arbitration to Mastercard network": {
"value": {
"event": "SEND_PRE_ARBITRATION",
"reason": "Disputed by account holder.",
"dispute_installment_id": 234,
"memo": "This is a test memo.",
"updated_chargeback_reason_code": 4859,
"change_reason_code_reason": "This is a test reason."
}
},
"Send Pre-arbitration to Mastercard network - Dispute without transaction": {
"value": {
"event": "SEND_PRE_ARBITRATION",
"reason": "Disputed by account holder.",
"dispute_installment_id": 234,
"memo": "This is a test memo.",
"merchant_name": "Acme Goods",
"updated_chargeback_reason_code": 4859,
"change_reason_code_reason": "This is a test reason."
}
},
"Send accept full pre-arbitration allocation Visa": {
"value": {
"event": "ACCEPT_PRE_ARBITRATION",
"reason": "Disputed by account holder.",
"dispute_installment_id": 234
}
},
"Send Pre-arbitration partial to Mastercard network": {
"value": {
"event": "SEND_PRE_ARBITRATION",
"reason": "Disputed by account holder.",
"dispute_installment_id": 234,
"memo": "This is a test memo.",
"updated_chargeback_reason_code": 4859,
"change_reason_code_reason": "This is a test reason.",
"pre_arb_is_partial": true,
"pre_arb_currency_code": "840",
"pre_arb_amount": 18.36
}
},
"Send Pre-arbitration partial to Mastercard network - Dispute without transaction": {
"value": {
"event": "SEND_PRE_ARBITRATION",
"reason": "Disputed by account holder.",
"dispute_installment_id": 234,
"memo": "This is a test memo.",
"merchant_name": "Acme Goods",
"updated_chargeback_reason_code": 4859,
"change_reason_code_reason": "This is a test reason.",
"pre_arb_is_partial": true,
"pre_arb_currency_code": "840",
"pre_arb_amount": 18.36
}
},
"Send accept partial pre-arbitration allocation Visa": {
"value": {
"event": "ACCEPT_PRE_ARBITRATION",
"reason": "Disputed by account holder.",
"dispute_installment_id": 234,
"pre_arb_is_partial": true,
"pre_arb_currency_code": "840",
"justify_not_accepted_fully": "Justification text",
"pre_arb_amount": 18.36
}
},
"Send decline pre-arbitration allocation Visa": {
"value": {
"event": "DECLINE_PRE_ARBITRATION",
"reason": "Disputed by account holder.",
"dispute_installment_id": 234,
"justify_not_accepted_fully": "Justification text"
}
}
}
}
}
},
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DisputeResponse"
},
"examples": {
"Updated status": {
"value": {
"id": 1009087,
"org_id": "TN-34778262-f4f0-464d-b4c6-a14exxxxxxxx",
"account_id": 30605,
"authorization_id": 4352243,
"comment": "Some comment",
"dispute_reason": 4855,
"modality": 4855,
"dispute_status": "OPENED",
"dispute_status_group": "ANALYSING",
"timeline": "{ \"data\": \"test\"}",
"protocol": "20190321L123456"
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/400BadRequest"
},
"401": {
"$ref": "#/components/responses/401Unauthorized"
},
"404": {
"$ref": "#/components/responses/404NotFound"
},
"500": {
"$ref": "#/components/responses/500InternalServerError"
}
}
}
}
}
}
```