> This page is for Cash App Pay Partner API. > For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://developers.cash.app/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developers.cash.app/_mcp/server. # Dispute Reports Dispute reports provide an easy-to-read document to see the current status of all disputes listed by merchant. These reports are available in CSV format and are automatically generated and uploaded securely to your server according to the configuration set up during your integration onboarding process. > **Note** > > We strongly recommend that Payment Service Providers monitor these dispute reports on a regular schedule. Use the information gathered as a failsafe mechanism to ensure that merchants are aware of all Cash App Pay disputes. > > This is useful if your normal method of informing merchants about disputes ever fails. You can use the information in the report to ensure disputes information is correctly captured and merchants are aware of these disputes. For more details on configuring your dispute reporting integration, contact your Cash App engineering partner. ## Configuring Dispute Reports Reports are uploaded by Cash App to a client-provided SFTP server. The following information is required. * SFTP hostname * SFTP port * username * SFTP user's private key * SFTP server host's public key (optional) * filepath (for uploading the reports) Reports are in CSV format and use a utf-8 encoding. Each dispute report is given a unique filename to avoid upload collisions using the following convention: `yyyyMMdd_dispute_report_client__batch__chunk_.csv` > **Note** > > As an additional security benefit, Cash App Pay can optionally PGP encrypt disputes files before they’re uploaded to the client SFTP server. In order to enable this feature, please contact [Cash App Partner Engineering](mailto:cash-app-partner-engineering@squareup.com). ## CSV Schema Dispute report files can contain up to 9,999 records. Each file will contain headers in the top row, and then each subsequent row will have the following schema: | Column Name | Type | Description | | :----------------------------- | :-------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | dispute_id | String | Unique identifier for this dispute assigned by Cash App | | dispute_created_at | String (datetime using RFC 3339 standard in UTC) | The time at which the dispute was created | | dispute_updated_at | String (datetime using RFC 3339 standard in UTC) Note: This field is optional, so it may not be present | The time at which the dispute was updated | | merchant_id | String | Unique identifier of the merchant (assigned by Cash App) that received this payment | | merchant_reference_id | String | Unique identifier for the merchant, as provided by the PSP | | dispute_reason | String | 4-digit code consisting of 2 letters followed by 2 numbers that indicates why the dispute was created, at a high level. **Current values:** FR10: Customer has no knowledge of the payment. FR11: Customer has no knowledge of the payment and liability has shifted to the merchant due to collusion, fraud monitoring program thresholds, or any other reason. PE10: Payment was processed twice. PE11: Payment amount differs from agreed amount. PE12: Payment was paid for by another means. CD10: Cancelled services. CD11: Goods or services differ from what was agreed upon for the payment. CD12: The goods or services were not received. CD13: The purchase was cancelled or returned, but the refund has not been processed. | | dispute_currency | String | Indicates the currency associated with the dispute. Values are from the ISO-4217 Alpha-3 specification. **Current values:** USD: United States Dollar | | payment_id | String | Unique identifier for this payment issued by Cash App | | payment_reference_id | String Note: This field is optional, so it may not be present | A user-defined identifier for this payment, typically used to associate the payment with a record in an external system. | | dispute_amount | Number(Integer) | Amount of disputed money, in the lowest denomination of currency on the associated payment | | settlement_amount | Number(Integer) | Signed amount that will be settled as a side effect of this dispute update, in the lowest denomination of currency for the dispute. Positive amounts denote funds being withheld from the PSP. Negative amounts denote previously withheld funds being returned to the PSP (in cases where the merchant at least partially won the dispute) | | dispute_state | String | The step in the [Dispute Life Cycle](/cash-app-pay-partner-api/guides/technical-guides/payment-processing/disputes/dispute-life-cycle) that this dispute is currently at: RESPONSE_REQUIRED NO_RESPONSE_REQUIRED PROCESSING ACCEPTED WON PARTIALLY_WON LOST | | dispute_response_due_at | String (datetime using RFC 3339 standard in UTC) Note: This field is optional, so it may not be present | The time at which the dispute must be challenged by, after which it will be automatically accepted (read more about the [Dispute Life Cycle](/cash-app-pay-partner-api/guides/technical-guides/payment-processing/disputes/dispute-life-cycle)). This field will be empty if no action is required by the PSP | | dispute_additional_information | String Note: This field is optional, so it may not be present | Additional context or comments associated with the dispute. This field will be empty when there is no additional information. | ## Example Data The following snippets present example data for different dispute-related scenarios. For more details on the different dispute states and flows, please refer to the [Dispute Life Cycle](/cash-app-pay-partner-api/guides/technical-guides/payment-processing/disputes/dispute-life-cycle). ### Credit Disputes ```CSV dispute_id,dispute_created_at,dispute_updated_at,merchant_id,merchant_reference_id,dispute_reason,dispute_currency,payment_id,payment_reference_id,dispute_amount,settlement_amount,dispute_state,dispute_response_due_at\nDSPT_n4peyrdrbrqn2jdrh9c0gdfsm,2021-10-25T22:05:34.925Z,2021-10-25T22:05:41Z,MMI_lwcxxixn,LC5KZGJ20RKQ5,PE10,USD,PWC_zw52d1jy9cj9w1cx803qjjrkl,PXJT_347,4600,4600,RESPONSE_REQUIRED,2021-11-25T22:05:34.925Z\nDSPT_n4peyrdrbrqn2jdrh9c0gdfsm,2021-10-25T22:05:34.925Z,2021-10-25T22:05:41Z,MMI_lwcxxixn,LC5KZGJ20RKQ5,PE10,USD,PWC_zw52d1jy9cj9w1cx803qjjrkl,PXJT_347,4600,0,PROCESSING,2021-11-25T22:05:34.925Z\nDSPT_n4peyrdrbrqn2jdrh9c0gdfsm,2021-10-25T22:05:34.925Z,2021-10-25T22:05:41Z,MMI_lwcxxixn,LC5KZGJ20RKQ5,PE10,USD,PWC_zw52d1jy9cj9w1cx803qjjrkl,PXJT_347,4600,0,LOST ``` ### Dispute ruled in favour of merchant ```CSV dispute_id,dispute_created_at,dispute_updated_at,merchant_id,merchant_reference_id,dispute_reason,dispute_currency,payment_id,payment_reference_id,dispute_amount,settlement_amount,dispute_state,dispute_response_due_at\nDSPT_n4peyrdrbrqn2jdrh9c0gagdq,2021-10-25T22:05:34.925Z,2021-10-25T22:05:41Z,MMI_lwcxxixn,LC5KZGJ20RKQ5,PE11,USD,PWC_zw52d1jy9cj9w1cx803qjwrck,XJ9_42,3797,3797,RESPONSE_REQUIRED,2021-11-25T22:05:34.925Z\nDSPT_n4peyrdrbrqn2jdrh9c0gagdq,2021-10-25T22:05:34.925Z,2021-10-26T10:35:21Z,MMI_lwcxxixn,LC5KZGJ20RKQ5,PE11,USD,PWC_zw52d1jy9cj9w1cx803qjwrck,XJ9_42,3797,0,PROCESSING,2021-11-25T22:05:34.925Z\nDSPT_n4peyrdrbrqn2jdrh9c0gagdq,2021-10-25T22:05:34.925Z,2021-10-27T15:27:01Z,MMI_lwcxxixn,LC5KZGJ20RKQ5,PE11,USD,PWC_zw52d1jy9cj9w1cx803qjwrck,XJ9_42,3797,-3797,WON ``` ### Dispute ruled in favour of merchant for less than total dispute amount ```CSV dispute_id,dispute_created_at,dispute_updated_at,merchant_id,merchant_reference_id,dispute_reason,dispute_currency,payment_id,payment_reference_id,dispute_amount,settlement_amount,dispute_state,dispute_response_due_at\nDSPT_n4peyrdrbrqn2jdrh9c0gwwjd,2021-10-25T22:05:34.925Z,2021-10-25T22:05:41Z,MMI_lwcxxixn,LC5KZGJ20RKQ5,CD11,USD,PWC_zw52d1jy9cj9w1cx803qjbeck,1299,1299,RESPONSE_REQUIRED,2021-11-25T22:05:34.925Z\nDSPT_n4peyrdrbrqn2jdrh9c0gwwjd,2021-10-25T22:05:34.925Z,2021-10-26T12:37:52Z,MMI_lwcxxixn,LC5KZGJ20RKQ5,CD11,USD,PWC_zw52d1jy9cj9w1cx803qjbeck,1299,0,PROCESSING,2021-11-25T22:05:34.925Z\nDSPT_n4peyrdrbrqn2jdrh9c0gwwjd,2021-10-25T22:05:34.925Z,2021-10-30T17:57:02Z,MMI_lwcxxixn,LC5KZGJ20RKQ5,CD11,USD,PWC_zw52d1jy9cj9w1cx803qjbeck,1299,-200,PARTIALLY_WON ``` ### Fraud Disputes ```CSV dispute_id,dispute_created_at,dispute_updated_at,merchant_id,merchant_reference_id,dispute_reason,dispute_currency,payment_id,payment_reference_id,dispute_amount,settlement_amount,dispute_state,dispute_response_due_at\nDSPT_n4peyrdrbrqn2jdrh9c0gwgdq,2021-10-25T22:05:34.925Z,2021-10-25T22:05:41Z,MMI_lwcxxixn,LC5KZGJ20RKQ5,FR10,USD,PWC_zw52d1jy9cj9w1cx803qjattk,T1000_azerty,4600,0,NO_RESPONSE_REQUIRED ``` > Fraud disputes where Cash App Pay takes on liability are included here for informational purposes only and do not impact settlement.