Technical GuidesPayment ProcessingDisputes

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.

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_<clientID>_batch_<batchToken>_chunk_<chunkID>.csv

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.

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 NameTypeDescription
dispute_idStringUnique identifier for this dispute assigned by Cash App
dispute_created_atString
(datetime using RFC 3339 standard in UTC)		The time at which the dispute was created
dispute_updated_atString
(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_idStringUnique identifier of the merchant (assigned by Cash App) that received this payment
merchant_reference_idStringUnique identifier for the merchant, as provided by the PSP
dispute_reasonString4-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_currencyStringIndicates the currency associated with the dispute. Values are from the ISO-4217 Alpha-3 specification.

Current values:
USD: United States Dollar
payment_idStringUnique identifier for this payment issued by Cash App
payment_reference_idString
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_amountNumber(Integer)Amount of disputed money, in the lowest denomination of currency on the associated payment
settlement_amountNumber(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_stateStringThe step in the Dispute Life Cycle that this dispute is currently at:
RESPONSE_REQUIRED
NO_RESPONSE_REQUIRED
PROCESSING
ACCEPTED
WON
PARTIALLY_WON
LOST
dispute_response_due_atString
(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).
This field will be empty if no action is required by the PSP

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.

Credit Disputes

1dispute_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

1dispute_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

1dispute_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

1dispute_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.