Dispute Detail Custom Report Specification

DocsCurrentLast updated: October 12th 2021, @ 6:58:00 pm


The Dispute Detail Custom report provides merchants and partners with regular operational information of all claims made against the merchant or partner’s PayPal account, along with the status of each claim. This report, also known as a case report, is available to any approved merchant (business receiver of funds transmitted via PayPal), cart integration partner, and payment processing partner. Use this report to do the following:

  • Track status changes of claims within a specified reporting period
  • Access details of claims in an open or pending state for the previous 180 days

Know before you begin

  • You must have a PayPal secure file transfer protocol (SFTP) account to access reports.
  • You must be an approved merchant to use this report. Contact your PayPal account manager to request access to this report.
  • This report is generated and placed on SFTP on a 24-hour basis. The report format is TAB (tab-separated values) or CSV (comma-separated value).
  • Money amount fields are unsigned, with no currency symbol, decimal separator, or other punctuation. Amounts should be interpreted by the debit or credit column to ensure that the right direction of the amount is recorded. For instance, 100,00 yen and $100.00 USD are both represented as 10000.
  • The character encoding of this report is UTF-8 (8-bit UCS/Unicode Transformation Format).
  • Regardless of the field delimiter of the report, all fields of type varchar are surrounded with double quotation marks. Double quotation marks inside the field are represented as two double quotation marks in succession.
  • Some fields can contain spaces. In the descriptions of fields, this is indicated with the words: Blanks: Yes.

Terminology

The following terms are useful in understanding the report:

  • Win: A case closed with no reversal or money movement, either partial or full.
  • Loss: A case closed with either a partial or full reversal.
  • Refund: A case closed with a partial or full refund. Since refund is a seller-initiated process in lieu of the acceptance of the liability to the buyer, this cannot be a loss.
  • Cancelled: Any case that was closed with no further action after it was opened by the buyer. It is assumed that the case was amicably resolved between the two parties. Note: This type of case was previously called a Resolved Dispute. See the Version history for more details.
  • Represented by PayPal: In cases such as external chargebacks, the seller is represented by PayPal. If the external entity refunds the amount, the case is considered a win because the seller is represented by PayPal in the dispute discussion.

Report file name

The file naming convention depends on whether you are using Multiple Account Management (MAM).

Single account report

The filename of the Dispute Detail Custom report for a single account follows this naming convention: userSpecifiedName_YYYYMMDDHHMMSS_YYYYMMDDHHMMDD_executionType_fileCount.csv

FieldInformation
userSpecifiedNameName specified by the user while saving the template.
YYYYMMDDHHMMSSThe start date of the range used for filtering the data.
YYYYMMDDHHMMDDThe end date of the range used for filtering the data.
executionTypeSpecifies if this report output was generated by doing a Run Now feature or was scheduled and generated via batch, represented as one of the following values:
  • O–Run Now
  • S–scheduled run
fileCountThe sequence number of this file. Two characters, right-justified and zero filled. The sequence number begins with 01 and continues until all parts are recorded in files. The sequence number is always present in the report file name even if there is only one file.

Multiple account report

The filename of the Dispute Detail Custom report for a MAM account follows this naming convention: userSpecifiedName_YYYYMMDDHHMMSS_YYYYMMDDHHMMDD_windowName_executionType_fileCount.csv

FieldInformation
userSpecifiedNameName specified by the user while saving the template.
YYYYMMDDHHMMSSThe start date of the range used for filtering the data.
YYYYMMDDHHMMDDThe end date of the range used for filtering the data.
windowNameThe window of time when the report was generated, represented as one of the following values:
  • A–America/New York to America/Los Angeles
  • H–America/Los Angeles to Asia/Hong Kong
  • R–Asia/Hong Kong to Europe/London
  • X–Europe/London to America/New York
executionTypeSpecifies if this report output was generated by doing a Run Now feature or was scheduled and generated via batch. Values: • O–Run Now • S–Scheduled Run
fileCountThe sequence number of this file. Two characters, right-justified and zero filled. The sequence number begins with 01 and continues until all parts are recorded in files. The sequence number is always present in the report file name even if there is only one file.

Field specifications

The following sections reflect fields that you can select to include in the report. The categorization of the fields is provided for ease-of-use in understanding report fields but does not output in the report itself.

Case fields

This has the list of columns that are a part of the actual case. These are data that are either generated by PayPal internal systems and passed on to the merchant via the response or data that is passed by merchant itself to identify the case.

Field NameData TypeDescription
Case IdVarcharUnique ID generated by PayPal. It can be used to refer to a case when discussing your cases with PayPal service representatives. Details:
  • Unique: Yes
  • Blank: No
  • Max length: 18 characters
Case TypeTextThe type of case made against the transaction. The case type must be one of the following values:
  • Bank Return
  • Chargeback
  • Claim
  • Dispute
  • Reversal/Temporary Hold
  • Unauthorized
Case ReasonTextOne of the following systematic reasons for the case:
  • Credit not processed
  • Charge not recognized
  • Defective or incorrect merchandise
  • Defective or item not as defined
  • Duplicate payment
  • Funding decline
  • Inquiry
  • Inquiry by PayPal
  • Item not received
  • Merchandise
  • Not as described
  • Non-receipt
  • Other
  • Processing error
  • Recurring payment cancelled
  • Special
  • Unauthorized unwanted merchandise
  • Unauthorized payment
Case Filing DateDate timeDate that the case was original filed with PayPal. Keep track of this date to ensure that you understand how much time remains for them to respond. The datetime that represents the beginning time period of the report in the following format: YYYY/MM/DD HH:MM:SS offset.
Case StatusTextOne of the following states or statuses of the case:
  • Being reviewed by PayPal
  • Case closed
  • Eligible for appeal
  • Open
  • Waiting for buyer’s response
  • Waiting for seller’s response
Disputed AmountNumericAmount being disputed by the buyer in the original transaction. Because buyers may sometimes dispute only part of the payment, the disputed amount may be different than the total gross or net amount of the original transaction. There is no specific maximum limit. Pay close attention to this amount, even if you pull the transaction details using the Invoice ID or Transaction ID.
Disputed CurrencyCurrency CodeCurrency of the disputed amount. The currency of the dispute is always the same as the amount of the original payment. Buyers are not allowed to request refunds or reversal in a different currency.
Disputed Transaction IDVarcharTransaction ID generated at the time of the money movement event. This unique 17-character ID is generated by PayPal and cannot be altered. If the transition for the case in the specified timeframe doesn’t have a money movement associated with it, all previous money movement transaction IDs will be reported as comma-separated values. Details:
  • Unique: Yes
  • Blank: No
  • Max length: 24 characters
Money MovementTextIndicated whether PayPal moved money into or out of your account as a result of the outcome of the case.
  • Credit
  • Debit
  • On temporary hold
  • No impact
  • Temporary hold released
Settlement TypeTextMode used to return the money to the buyer:
  • Adjustment
  • Refund
  • Partial Refund
  • Reversal
OutcomeStringOutcome description of the case entered by PayPal customer support or the comment provided by the buyer or seller. Details:
  • Unique: No
  • Blanks: Yes
  • Max length: 3000 characters
Response Due DateDate timeDate by which you should respond to the case filed against you. The date time that represents the beginning time period of the report in the following format: YYYY/MM/DD HH:MM:SS offset.
Seller ProtectionTextSpecifies the Seller Protection status:
  • Eligible: Seller is eligible to be protected by PayPal’s Seller Protection Policy for Unauthorized payments and Item Not Received.
  • Partially Eligible Unauth Only: Seller is eligible to be protected by PayPal’s Seller Protection Policy for Unauthorized Payment Only.
  • Ineligible: Seller is not protected under the Seller Protection Policy.
Seller Protection Payout AmountNumericAmount PayPal paid on the behalf of the seller to the buyer as a result of the Seller Protection coverage.
Seller Protection CurrencyCurrency CodeCurrency of the amount PayPal paid on the behalf of the seller to the buyer as a result of the Seller Protection coverage.
Buyer CommentsTextComments provided by the buyer while filing the case in the Resolution Center.
Chargeback Reason CodeVarcharMax length: 32 characters. Unique identifier which distinguishes the nature or reason of credit card chargeback reported. Each card issuer follows their own standards for defining reason type, code, and its format.
Final Case OutcomeTextCase closed as a Win or Loss to the merchant. The possible values could be one of the following:
  • Win – A case closed with no reversal or money movement, either partial or full.
  • Loss – A case closed with either a partial or full reversal.
  • Refund – A case closed with a partial or full refund. Since refund is a seller-initiated process in lieu of the acceptance of the liability to the buyer, this cannot be a loss.
  • Cancelled – Any case that was closed with no further action after it was opened by the buyer. It is assumed that the case was amicably resolved between the two parties.
Final Outcome ReasonTextReason for the final outcome. See Outcome reasons for a complete list.
Final Settled AmountNumericThe final amount that was settled in case of a money movement when the case was closed. If the case did not involve money movement, this field displays 0.

Transaction fields

Field NameData TypeDescription
Transaction IDVarcharTransaction ID of the money moving event. This ID is generated by PayPal exclusively and cannot be altered by the merchant. Note: If the case is not associated with a money movement, this field is empty. (Encrypted Value)
Details:
  • Unique: Yes
  • Blank: Yes
  • Max Length: 24 characters
Invoice IDTextInvoice ID is set by merchant with transaction. If an invoice ID was sent with the capture request, this value is reported here. If NO Invoice ID was sent with the capture request, the value of the invoice ID from the authorizing transaction is reported here.
Details:
  • Unique: No
  • Blank: Yes
  • Max Length: 127 characters
PayPal Reference ID (Same as Reference Txn ID, Transaction Parent ID)VarcharA PayPal reference ID is defined as a related, pre-existing transaction or event. (Encrypted Value)
Details:
  • Unique: Yes
  • Blank: Yes
  • Max Length: 24 characters
PayPal Reference ID TypeTextOne of the following 3-character codes:
  • ODR: Order ID
  • TXN: Transaction ID
  • SUB: Subscription ID
  • PAP: Preapproved payment ID
Details:
  • Unique: Yes
  • Blank: Yes
  • Max Length: 24 characters
Transaction Initiation DateDate/timeDate and time that transaction was initiated, in the following format: YYYY/MM/DD HH:MM:SS Offset where: YYYY is the four-digit year. MM is two-digit month of the year DD is the two-digit day of the month. HH is the hour in 24-hour notation. MM is minutes. SS is seconds. offset is the five-character signed offset from GMT. For example, +0800.
Details:
  • Unique: No
  • Blank: Yes
  • Max Length: 25 characters
Transaction Completion DateDate/timeDate and time that transaction was completed, in the following format: YYYY/MM/DD HH:MM:SS Offset where: YYYY is the four-digit year. MM is two-digit month of the year DD is the two-digit day of the month. HH is the hour in 24-hour notation. MM is minutes. SS is seconds. offset is the five-character signed offset from GMT. For example, +0800. Details:
  • Unique: No
  • Blank: Yes
  • Max Length: 25 characters
Transaction Debit or CreditTextDirection of money movement of gross amount, as one of the two literal strings: CR: Credit DR: Debit. Details:
  • Unique: No
  • Blank: No
  • Max Length: 2 characters
Gross Transaction AmountCurrency/moneyThe amount of payment – before fees – between the two parties. This field contains the gross transaction value for all transactions. Note: There are handling fees and other non- transactional fees that will be reported as gross amounts without fees reported in the fee column. Details:
  • Unique: No
  • Blank: Yes
  • Max Length: 26 characters
Gross Transaction CurrencyCHARCharacters Currency of transaction. Details:
  • Unique: No
  • Blank: No
  • Max Length: 3 characters
Fee Debit or CreditCHARDirection of money movement for fee, as one of the two literal strings: CR: Credit or DR: Debit. Details:
  • Unique: No
  • Blank: Yes
  • Max Length: 2 characters
Fee AmountNumberThe record of fees associated with the settlement. All transactional fees are included in this amount. Fees are never amortized across several transactions. This field contains the fee amount values for all transactions where a transactional fee has been processed. Details:
  • Unique: No
  • Blank: Yes
  • Max Length: 26 characters
Fee CurrencyCHARCurrency of fee. Details:
  • Unique: No
  • Blank: Yes
  • Max Length: 3 characters
Payment Tracking IDVarcharUnique ID specified by partners to obtain information about a payment or to request a refund.
Details:
  • Unique: No
  • Blank: Yes
  • Max Length: 127 characters

Buyer fields

Field NameData TypeDescription
Buyer Email AddressAlphanumericThe email address of the payer in the payment transaction. If there is no payer, this value is blank.
Details:
  • Unique: No
  • Blank: Yes
  • Max Length: 127 characters
Buyer Phone NumberAlphanumericThe phone number of the payer in the payment transaction. If there is no payer, this value is blank.
Details:
  • Unique: No
  • Blank: Yes
  • Max Length: 127 characters
Buyer First NameVarcharConsumer’s given name (first name) as recorded in their PayPal account.
Details:
  • Unique: No
  • Blank: Yes
  • Max Length: 127 characters
Buyer Last NameVarcharConsumer’s given name (last name) as recorded in their PayPal account.
Details:
  • Unique: No
  • Blank: Yes
  • Max Length: 127 characters

Retail fields

Field NameData TypeDescription
Store IDVarcharThe ID of the store where the offer was used.
Details:
  • Unique: No
  • Blank: Yes
  • Max Length: 50 characters
Terminal IDVarcharThe ID of the terminal where the transaction occurred. This is applicable to point of sale transactions only.
Details:
  • Unique: No
  • Blank: Yes
  • Max Length: 50 characters

Report format

Each row of the report consists of a two-letter row type, followed by the details specific to that row type. The following table lists the valid row types and the sections that describe the data for that row type.

CodeDescription
RHReport header
FHFile header
SHSection header
CHColumn header
SBRow data
SFSection footer
SCSection record count
RFReport footer
RCReport record count
FFFile footer

A report file with less than 100,000 records (a single file) with only one section is organized as follows:

Report Header(RH) File Header (FH) Section Header(SH) Column Header (CH) Row Data (SB) ... Row Data (SB) Section Footer (SF) Section Record Count (SC) Report Footer (RF) Report Record Count (RC) File Footer (FF)

For report files that are split over multiple files, only the first file has a report header record and only the last file has a footer and a report record count. A report with two sections split over two files might be organized as follows:

File 1File 2
Report Header (RH)File Header (FH) Row Data (SB)
File Header (FH) Section Header (SH)...
Column Header (CH)Row Data (SB) Section Footer (SF)
Row Data (SB)Section Record Count (SC) Report Footer (RF)
...Report Record Count (RC) File Footer (FF)
Row Data (SB)
Section Footer (SF)
Section Record Count (SC) Section Header (SH)
Column Header (CH)
Row Data (SB)
...
File Footer (FF)

Report header

Report header data exists in one row with each element being separated by the file delimiter. All report fields are non-blank unless otherwise noted.

File header data

Position Column name Data type Description
1 Column Type Literal RH
2 Report Generation Date Date-time The date and time when the report file was generated, in the following format: YYYY/MM/DDHH:MM:SS offset, where offset is the five-character signed offset from GMT, such as +0800.
3 Reporting Window Varchar The window of time when the report was generated, as follows:
  • A: America/New York to America/Los Angeles.
  • H: America/Los Angeles to Asia/Hong Kong.
  • R: Asia/Hong Kong to Europe/London.
  • X: Europe/London to America/New York.
4Account IDVarcharAccount number receiving the report (Payer ID – encrypted hash of PayPal account).

Report footer data exists in one row with each element being separated by the file delimiter.All report fields are non- blank unless otherwise noted.

Position Column name Data type Description
1 Column type Literal "RF"
2 Row count NumberThe total number of section body records in the entire report. Max length: no limit.

Report record count

Report record count data exists in one row with each element being separated by the file delimiter. All report fields are non-blank unless otherwise noted.

Position Column name Type Description
1 Column Type Literal "RC"
2 Row count NumberThe number of body data rows in the report (used for reconciliation). Note that the report may span multiple files.

File header

File header data exists in one row with each element being separated by the file delimiter. All report fields are non-blank unless otherwise noted.

Position Column name Type Description
1 Column Type Literal "FH"
2 File count Number The sequence number of the file in the report (used for reconciliation).

File footer data exists in one row with each element being separated by the file delimiter. All report fields are non-blank unless otherwise noted.

Position Column name Data type Description
1 Column Type Literal "FF"
2 Row count Number The number of body data rows in the file (used for reconciliation).

Section header

All section header data exists in one row with each element being separated by the file delimiter. All report fields are non-blank unless otherwise noted.

Position Column name Data type Description
1 Column Type Literal "FF"
2 Reporting period start date Date/time The date and time when the report file was generated, in the following format: YYYY/MM/DDHH:MM:SS offset, where offset is the five-character signed offset from GMT, such as +0800. YYYY is the four-digit year. MM is the two-digit month of hte year. DD is the two-digit day of the month. HH is the hour in 24-hour notation. MM is minutes. SS is seconds.
3 Reporting period end date Date/time The date and time when the report file was generated, in the following format: YYYY/MM/DDHH:MM:SS offset, where offset is the five-character signed offset from GMT, such as +0800. YYYY is the four-digit year. MM is the two-digit month of hte year. DD is the two-digit day of the month. HH is the hour in 24-hour notation. MM is minutes. SS is seconds.
4 Account ID Varchar Encrypted account number generated by

Section body

Body data exists in one row with each element separated by the file delimiter. All report fields are non-blank unless otherwise noted. Before any rows of body data in the report, a column header row lists the name of each of the fields in each body data row. The column header column starts with CH, followed by the Column Name for each body data field.

The section body contains multiple records, one per balance-affecting transaction. The section body fields are on a single row for each transaction. The data elements are separated by the report recipient’s desired field delimiter.

The gross amount is always shown for transactions processed in any currency. In cases where there are no fees involved, the fees will not be shown and the net amount is same as gross amount.

Position Column name Data type Description
1 Column Type Literal "SB"

For the rest of the columns that appear in the section body, see Field specifications.

Section footer data exists in one row with each element being separated by the file delimiter. All report fields are non-blank unless otherwise noted.

Position Column name Data type Description
1 Column Type Literal "SF"
2 Row count NumberTotal number of section body records in this section. Max length: no limit.

Section record count

Section record count data exists in one row with each element being separated by the file delimiter. All report fields are non-blank unless otherwise noted.

Position Column name Data type Description
1 Column Type Literal "SC"
2 Row count NumberTotal number of section body data rows in this section (used for reconciliation).

Outcome reasons

The following is a list of possible outcome reasons.

Win

  • The case was closed in your favor.
  • The case was closed in your favor as no duplicate transaction was found.
  • The case was closed in your favor based on the info provided.
  • The case was closed in your favor as the transaction was covered under PayPal Seller Protection.
  • The case was closed in your favor as the transaction was previously refunded or reversed.
  • The case was closed in your favor as you've already issued a credit to the buyer.

Refund

  • The buyer has received a partial refund. The amount has been withdrawn from your PayPal account. This case is closed.
  • This case is closed as you confirmed that you received the item. A refund has been withdrawn from your PayPal account and sent to the buyer.
  • This case is closed as the buyer has received the replacement item.
  • You issued a refund.

Cancelled

  • The buyer cancelled the case.

Loss

  • The case was closed in the buyer's favor as the change in installment charges for the billing agreement wasn't disclosed to the buyer.
  • The case was closed in the buyer's favor as the change in the start date for the billing agreement wasn't disclosed.
  • The case was closed in the buyer's favor as they attempted to return the item.
  • The case was closed in the buyer's favor as the service or recurring transaction was cancelled.
  • The case was closed in the buyer's favor as a credit receipt or relevant documentation was provided.
  • The case was closed in the buyer's favor as the billing agreement was cancelled as per the terms of the signed contract.
  • The decision was taken based on the info provided.
  • The case was closed in the buyer's favor as the item or service was delivered after the expected delivery date had passed.
  • The case was closed in the buyer's favor since duplicate funds were added due to an add funds issue.
  • The case was closed in the buyer's favor as you delivered the item in person.
  • The case was closed in the buyer's favor based on the info provided.
  • This case is closed as the buyer has received the replacement item.
  • This case was closed as you can't appeal for the same reason twice.
  • The case was closed in the buyer's favor as the proof of delivery you provided was invalid.
  • The case was closed in the buyer's favor as the proof of delivery/shipment was missing the signature confirmation.
  • The case was closed in the buyer's favor as the proof of shipment you provided was invalid.
  • The case was closed in the buyer's favor as the proof of return you provided was invalid.
  • This case was closed in the buyer's favor as the tracking info you provided was invalid.
  • The case was closed in the buyer's favor as the item doesn't work as advertised.
  • The case was closed in the buyer's favor as the item or service provided didn’t match the given description.
  • The case was closed in the buyer's favor as you didn't send the item to the buyer.
  • The case was closed in the buyer's favor as we didn’t receive verified proof of shipment or delivery.
  • The case was closed in the buyer's favor as the item sent to the buyer was of different quality, quantity, color, or size.
  • The case was closed in the buyer's favor as the item wasn't delivered because it is no longer in stock.
  • The case was closed in the buyer's favor as the item was returned.
  • The case was closed in the buyer's favor as your listing misrepresented the item.
  • The case was closed as you made multiple appeals with the same reason.
  • The case was closed in the buyer's favor as we didn't receive the proof of delivery.
  • The case was closed in the buyer's favor as we didn't receive the proof of delivery for a service or digital good.
  • The case was closed as the digital good you're selling isn't covered under PayPal Seller Protection.
  • The case was closed in the buyer's favor as we didn't receive a response from you.
  • The case was closed in the buyer's favor as we didn't receive a response to our request for additional info.
  • The case was closed in the buyer's favor as a valid proof of shipment wasn't given.
  • The case was closed in the buyer's favor as the item wasn't shipped to the correct address.
  • The case was closed as you issued a refund for the missing items.
  • The case was closed as the buyer accepted the partial refund offer.
  • The case was closed in the buyer's favor as the proof of shipment was submitted instead of proof of delivery.
  • The case was closed in the buyer's favor as they were billed after the billing agreement was cancelled.
  • The case was closed in the buyer's favor as they provided proof showing this purchase was paid using another payment method.
  • The case was closed in the buyer's favor since the credit does not match the withdrawal amount.
  • The case was closed in the buyer's favor as you received multiple payments.
  • The case was closed in the buyer's favor as you chose to issue a refund without item return.
  • The case was closed in the buyer's favor as you agreed to refund the buyer.
  • The case was closed in the buyer's favor as you weren't reachable to resolve this case.
  • The case was closed as you received the payment twice or for a replacement.
  • The case was closed in the buyer's favor as you declined to issue a refund.
  • The case was closed in the buyer's favor as you declined to accept the return of the item.
  • This case was closed as a surcharge was assessed to the buyer.
  • The case was closed in the buyer's favor as the service wasn't completed as described in the agreement.
  • The case was closed in the buyer's favor as the shipping company refused to ship the item.
  • This case was closed as you can't appeal with tracking info for this case reason.
  • The case was closed in the buyer's favor as the transaction was cancelled before the shipment or service date.
  • The case was closed in the buyer's favor as they provided valid documents.
  • The case was closed in the buyer's favor as valid proof of return delivery was provided.
  • The case was closed in the buyer's favor as valid proof of return delivery with signature confirmation was provided.
  • The case was closed in the buyer's favor as the item's value or usability was affected significantly.

Version history

Publication dateVersionChanges
September 20201.04Converted this report specification documentation from PDF to HTML.
August 20201.03Replaced Resolved Dispute with Cancelled to be consistent with the Disputes API and Disputes Report. This change was effective August 14, 2020.
January 20201.02Corrected final outcome reason value inconsistencies
July 20191.01Updates
December 20181.0Initial release

See also