--- updatedAt: 2026-04-22T15:15:32.000Z agentTools: siteIndex: https://developers.pismo.io/llms.txt projectIndex: https://developers.pismo.io/pismo-docs/llms.txt --- # List disputes Get disputes with paging and filter options. # OpenAPI definition ```json { "openapi": "3.1.0", "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": { "accountIdQuery": { "name": "accountId", "in": "query", "description": "Account ID filter", "schema": { "type": "integer", "example": 123, "minimum": 1 }, "required": false }, "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 401 Unauthorized message.", "schema": { "type": "string", "example": "Bearer eyJhbGci...IUzUx" } }, "beginDateQuery": { "name": "beginDate", "in": "query", "description": "Beginning date filter, format= yyyy-mm-dd", "schema": { "type": "string", "example": "2020-01-31" }, "required": false }, "disputeStatusQuery": { "in": "query", "name": "status", "description": "Dispute status filter", "required": false, "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" ] }, "example": "OPENED" }, "endDateQuery": { "name": "endDate", "in": "query", "description": "End date filter, format= yyyy-mm-dd", "schema": { "type": "string", "example": "2020-01-31" }, "required": false }, "groupQuery": { "in": "query", "name": "group", "description": "Status group filter, i.e., `OPEN`.", "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" ] }, "required": false, "example": "WON" }, "isDisputeInvalidTransactionQuery": { "in": "query", "name": "isDisputeInvalidTransaction", "description": "Return only disputes with invalid transaction? Default is `false`.", "schema": { "type": "boolean", "default": false, "example": true }, "required": false }, "isDisputeMigratedQuery": { "in": "query", "name": "isDisputeMigrated", "description": "Return only migrated disputes? Default is `false`.", "schema": { "type": "boolean", "default": false, "example": true }, "required": false }, "isNetworkQuery": { "in": "query", "name": "isNetwork", "description": "Return only network disputes? Default is `false`.", "schema": { "type": "boolean", "example": true }, "required": false }, "pageQuery": { "name": "page", "in": "query", "description": "Page to return.", "schema": { "type": "integer", "default": 1, "example": 2, "minimum": 1 }, "required": false }, "perPageQuery": { "name": "perPage", "in": "query", "description": "Number of items per page", "schema": { "type": "integer", "default": 30, "example": 20, "minimum": 1 }, "required": false } }, "schemas": { "AccountID": { "type": "number", "description": "Pismo account ID", "example": 577830 }, "AuthorizationCode": { "type": "string", "description": "Authorization code", "example": "F0JR9H" }, "CreatedAtUTC": { "type": "string", "description": "Dispute created in UTC date/time.", "format": "date-time", "example": "2021-02-21T22:51:43.000000000Z" }, "DisputeID": { "type": "number", "description": "Dispute ID", "example": 48670 }, "OrgID": { "type": "string", "description": "Organization/tenant ID.", "example": "TN-34778262-f4f0-464d-b4c6-a14exxxxxxxx" }, "TransactionAmount": { "type": "number", "description": "Transaction amount", "example": 86753.09 }, "Comment": { "type": "string", "description": "Client custom dispute comment.\n\n**REQUIRED** for Visa partial dispute to explain why partial.\n", "nullable": true, "example": "Custom comment", "maxLength": 5000 }, "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": { "$ref": "#/components/schemas/DisputeID" }, "org_id": { "$ref": "#/components/schemas/OrgID" }, "account_id": { "$ref": "#/components/schemas/AccountID" }, "authorization_id": { "type": "integer", "example": 4352243, "description": "Authorization ID." }, "disputed_amount": { "$ref": "#/components/schemas/DisputedAmount" }, "comment": { "$ref": "#/components/schemas/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": { "$ref": "#/components/schemas/Protocol" }, "metadata": { "$ref": "#/components/schemas/Metadata" }, "created_at": { "$ref": "#/components/schemas/CreatedAt" }, "updated_at": { "$ref": "#/components/schemas/UpdatedAt2" }, "created_at_utc": { "$ref": "#/components/schemas/CreatedAtUTC" }, "updated_at_utc": { "$ref": "#/components/schemas/UpdatedAtUTC" }, "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 } } }, "DisputedAmount": { "type": "number", "example": 10, "description": "Disputed amount." }, "Metadata": { "type": "object", "description": "Can be used for caller's dispute information and process. Objects and name-value pairs.\n\n **Note**: This field must not be used to send Personally Identifiable Information (PII), Payment Card Industry (PCI) data, or any sensitive/regulated information. Metadata fields are intended for operational, non-sensitive data only. For sensitive data, use the specific parameters designed for that purpose. For more information, refer to [Get started with Pismo APIs](https://developers.pismo.io/pismo-docs/reference/get-started-with-pismo-apis#metadata).\n", "example": { "field1": "value", "field2": "value" } }, "Protocol": { "type": "string", "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", "maxLength": 500, "example": "20251128111532456" }, "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 }, "CreatedAt": { "type": "string", "description": "Created at datetime, format = yyyy-mm-dd hh:mm:ss\"", "example": "2024-10-18 11:21:45" }, "UpdatedAt2": { "type": "string", "description": "Dispute last updated date, format = yyyy-mm-dd.", "format": "date", "example": "2021-02-22" }, "UpdatedAtUTC": { "type": "string", "description": "When dispute updated in UTC date/time.", "example": "2022-10-13T19:56:010000000Z" } }, "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" }, { "$ref": "#/components/parameters/beginDateQuery" }, { "$ref": "#/components/parameters/endDateQuery" }, { "$ref": "#/components/parameters/pageQuery" }, { "$ref": "#/components/parameters/perPageQuery" }, { "$ref": "#/components/parameters/accountIdQuery" }, { "$ref": "#/components/parameters/isNetworkQuery" }, { "$ref": "#/components/parameters/isDisputeMigratedQuery" }, { "$ref": "#/components/parameters/isDisputeInvalidTransactionQuery" }, { "$ref": "#/components/parameters/groupQuery" }, { "$ref": "#/components/parameters/disputeStatusQuery" } ], "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" } } } } } } ```