# List disputes

Get disputes with paging and filter options.

# 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": {
      "AuthHeader": {
        "in": "header",
        "name": "Authorization",
        "required": true,
        "description": "Account token - an access token encoded with a Pismo account ID. Tokens can expire quickly, which can result in a <b>401 Unauthorized</b> message.",
        "schema": {
          "type": "string",
          "example": "Bearer eyJhbGci...IUzUx"
        }
      }
    },
    "schemas": {
      "AccountID": {
        "type": "number",
        "description": "Pismo account ID",
        "example": 577830
      },
      "AuthorizationCode": {
        "type": "string",
        "description": "Authorization code",
        "example": "F0JR9H"
      },
      "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"
        ]
      },
      "NetworkBrand": {
        "type": "string",
        "example": "Visa",
        "description": "Network brand",
        "enum": [
          "Visa",
          "Mastercard",
          "Elo"
        ]
      },
      "FullDisputeResponse": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer",
            "example": 1,
            "description": "Dispute ID."
          },
          "org_id": {
            "$ref": "#/components/schemas/OrgID"
          },
          "account_id": {
            "$ref": "#/components/schemas/AccountID"
          },
          "authorization_id": {
            "type": "integer",
            "example": 4352243,
            "description": "Authorization ID."
          },
          "disputed_amount": {
            "type": "number",
            "example": 10.5,
            "description": "Disputed amount."
          },
          "comment": {
            "type": "string",
            "example": "Some comment",
            "description": "Client custom comment."
          },
          "airport_tax": {
            "type": "boolean",
            "description": "For ELO card network, should dispute for airport tax be created? Default is `true` for ELO.",
            "example": false
          },
          "airport_tax_partial": {
            "type": "boolean",
            "description": "For ELO card network, should airport tax be partially disputed? Default is `false`.",
            "default": false,
            "example": false
          },
          "airport_tax_amount": {
            "type": "number",
            "description": "Airport tax amount to be disputed. **REQUIRED** if `airport_tax_partial` is `true`.",
            "example": 25
          },
          "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_group_status": {
            "$ref": "#/components/schemas/DisputeGroupStatus"
          },
          "timeline": {
            "type": "string",
            "example": "{ \"data\": \"test\"}",
            "description": "Client custom timeline information."
          },
          "protocol": {
            "type": "string",
            "example": "20190321L123456",
            "description": "Client custom protocol ID."
          },
          "metadata": {
            "type": "object",
            "description": "Can be used for caller's dispute information and process. Objects and name-value pairs."
          },
          "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"
          },
          "is_network": {
            "type": "boolean",
            "example": true,
            "description": "Open a dispute over a network authorization."
          },
          "is_dispute_migrated": {
            "type": "boolean",
            "example": false,
            "description": "Has this dispute been migrated to the Pismo platform?"
          },
          "reversal_id": {
            "type": "number",
            "example": 10042,
            "description": "Dispute credit reversal ID."
          },
          "network_return_reason_code": {
            "type": "string",
            "example": "2833",
            "description": "Network reason code response."
          },
          "network_brand_type": {
            "$ref": "#/components/schemas/NetworkBrand"
          },
          "transaction_date": {
            "type": "string",
            "example": "2021-02-02",
            "description": "Transaction date related to authorization, format = yyyy-mm-dd"
          },
          "stop_automated_installment": {
            "$ref": "#/components/schemas/stopAutomatedInstallment"
          },
          "card_hash": {
            "type": "string",
            "description": "Card number hash.",
            "example": "XYZddue74kd8"
          },
          "authorization_code": {
            "$ref": "#/components/schemas/AuthorizationCode"
          },
          "transaction_amount": {
            "$ref": "#/components/schemas/TransactionAmount"
          },
          "is_dispute_invalid_transaction": {
            "type": "boolean",
            "description": "Is this an invalid authorization dispute?",
            "example": false
          }
        },
        "x-examples": {
          "disputeResponse": {
            "id": 1,
            "org_id": "123456789",
            "account_id": 30605,
            "authorization_id": 4352243,
            "disputed_amount": 10.5,
            "comment": "Some comment",
            "dispute_reason": 4855,
            "modality": 4855,
            "dispute_status": "ANALYSING",
            "timeline": "{ \"data\": \"test\"}",
            "protocol": "20190321L123456",
            "created_at": "2021-02-21",
            "updated_at": "2021-02-22",
            "created_at_utc": "2021-02-21T22:51:43.000000000Z",
            "updated_at_utc": "2021-02-25T01:43:06.000000000Z",
            "is_network": true,
            "is_dispute_migrated": false,
            "reversal_id": 10042,
            "network_return_reason_code": "2833",
            "network_brand_type": "Mastercard",
            "transaction_date": "2021-02-02",
            "stop_automated_installment": true,
            "card_hash": "XYZ",
            "authorization_code": "123456",
            "transaction_amount": 10.5,
            "is_dispute_invalid_transaction": false
          }
        }
      },
      "stopAutomatedInstallment": {
        "type": "boolean",
        "description": "Automated dispute installment control flag. 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.\n",
        "example": true
      }
    },
    "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."
      },
      "500InternalServerError": {
        "description": "Internal server error"
      }
    }
  },
  "paths": {
    "/v1/disputes": {
      "get": {
        "summary": "List disputes",
        "operationId": "get-v1-disputes",
        "description": "Get disputes with paging and filter options.",
        "tags": [
          "Disputes"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/AuthHeader"
          },
          {
            "in": "query",
            "name": "beginDate",
            "description": "Beginning date filter, format= yyyy-mm-dd",
            "schema": {
              "type": "string",
              "example": "2020-01-31"
            },
            "required": false
          },
          {
            "in": "query",
            "name": "endDate",
            "schema": {
              "type": "string",
              "example": "2020-02-15"
            },
            "required": false,
            "description": "End date filter, format= yyyy-mm-dd."
          },
          {
            "in": "query",
            "name": "page",
            "schema": {
              "type": "integer",
              "default": 1,
              "example": 2,
              "minimum": 1
            },
            "required": false,
            "description": "Page to return."
          },
          {
            "in": "query",
            "name": "perPage",
            "schema": {
              "type": "integer",
              "default": 30,
              "example": 20,
              "minimum": 1
            },
            "required": false,
            "description": "Number of items per page"
          },
          {
            "in": "query",
            "name": "accountId",
            "schema": {
              "type": "integer",
              "example": 123,
              "minimum": 1
            },
            "required": false,
            "description": "Account ID filter"
          },
          {
            "in": "query",
            "name": "isNetwork",
            "schema": {
              "type": "boolean",
              "example": true
            },
            "required": false,
            "description": "Return only network disputes? Default is `false`."
          },
          {
            "in": "query",
            "name": "isDisputeMigrated",
            "schema": {
              "type": "boolean",
              "default": false,
              "example": true
            },
            "required": false,
            "description": "Return only migrated disputes? Default is `false`."
          },
          {
            "in": "query",
            "name": "isDisputeInvalidTransaction",
            "schema": {
              "type": "boolean",
              "example": true
            },
            "required": false,
            "description": "Return only disputes with invalid transaction? Default is `false`."
          },
          {
            "schema": {
              "type": "string",
              "example": "CARDNETWORK_CHARGEBACK",
              "enum": [
                "OPEN",
                "APPROVED",
                "DENIED",
                "CARDNETWORK_CHARGEBACK",
                "ANALYSING",
                "CARDNETWORK_SECOND_PRESENTMENT",
                "FAILED",
                "CARDNETWORK_PREARBITRATION",
                "RESEND",
                "LOSS",
                "WON",
                "REJECTED",
                "FAILED_PROCESSED"
              ]
            },
            "in": "query",
            "name": "group",
            "required": false,
            "description": "Status group filter, i.e., `OPEN`.",
            "example": "WON"
          },
          {
            "schema": {
              "type": "string",
              "example": "OPENED",
              "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"
              ]
            },
            "in": "query",
            "name": "status",
            "required": false,
            "description": "Status filter",
            "example": "OPENED"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/FullDisputeResponse"
                  }
                },
                "examples": {
                  "List Disputes": {
                    "value": [
                      {
                        "id": 1,
                        "org_id": "123456789",
                        "account_id": 30605,
                        "authorization_id": 4352243,
                        "disputed_amount": 10.5,
                        "comment": "Some comment",
                        "dispute_reason": 4855,
                        "modality": 4855,
                        "dispute_status": "PENDING",
                        "timeline": "{ \"data\": \"test\"}",
                        "protocol": "20190321L123456",
                        "created_at": "2021-02-21",
                        "updated_at": "2021-02-22",
                        "created_at_utc": "2021-02-21T22:51:43.000000000Z",
                        "updated_at_utc": "2021-02-25T01:43:06.000000000Z",
                        "is_network": true,
                        "is_dispute_migrated": false,
                        "reversal_id": 10042,
                        "network_return_reason_code": "2833",
                        "network_brand_type": "Mastercard",
                        "transaction_date": "2021-02-21",
                        "stop_automated_installment": true,
                        "card_hash": "XYZ",
                        "authorization_code": "123456",
                        "is_dispute_invalid_transaction": true,
                        "transaction_amount": 10.5
                      }
                    ]
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/400BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/401Unauthorized"
          },
          "500": {
            "$ref": "#/components/responses/500InternalServerError"
          }
        }
      }
    }
  }
}
```