Settlement Report Specification

The Settlement Report is for use by merchants or payment processing partner. This report gives merchants and processing partners detailed information about each transaction that affects the settlement of funds to their accounts. The report also summarizes, for each currency held by the accounts, total debits and credits and the beginning and ending balance.

The Settlement Report is available through PayPal’s website and the Secure FTP Server, which is defined and described in the Secure FTP Server Specification.

On this page

• Know before you begin
• Creating a secure FTP server User
• Schedule, distribution, archiving, and versioning
• Report file name
• Retention
• Versioning
• Settlement withdrawal and effective time zones
• Operational notification and monitoring
• Report format
• File structure
• Report data
• File data
• Section data
• Reference IDs
• Version history

Know before you begin

• 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 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.
• See PayPal Supported Currencies for a list of all ISO-4217 currency codes that PayPal supports for use with payments and balances.
• See T-Codes for a list of transaction event codes.

Creating a secure FTP server user

Account owners must generate their own usernames for the Secure Dropbox at paypal.com.

Schedule, distribution, archiving, and versioning

The Settlement Report is generated and put on PayPal's website or the Secure FTP server by no later than 12:00PM daily in the leading timezone of the reporting window. The report is available on the Secure FTP Server in the /ppreports/outgoingdirectory. See Access SFTP reports for instructions.

Report file name

The filename naming convention depends on whether or not you are using Multiple Account Management.

Single account report

The filename of the Settlement Report for a single account follows this naming convention: STL-yyyymmdd.sequenceNumber.version.format

Multiple account report

When using Multiple Account Management, the filename of the Settlement Report follows this naming convention: STL-yyyymmdd.reportingWindow.sequenceNumber.totalFiles.version.format

Retention

The Settlement Report will be available via Paypal's website and the Secure FTP Server for one year after the date of its delivery to the Secure FTP Server.

Versioning

In the future, the Settlement Report will be available in multiple versions. PayPal will communicate the creation of any new version and any deprecation of older versions. Users that wish to take advantage of new versions will be able to receive two versions of the same report concurrently for the purposes of testing and integration. Users can also receive nonconsecutive versions of the same report concurrently for the purposes of testing and integration. Users must contact their account manager to enable different versions and request any changes in report distribution.

Settlement withdrawal and effective time zones

The Settlement Report reconciles to the Settlement Withdrawal for any time zone from Pacific Standard Time (PST, which is GMT minus seven hours or eight hours, depending on daylight savings time) to nine hours ahead of PST.

Operational notification and monitoring

Around-the-clock every day of the year, PayPal operationally monitors the generation and delivery of the Settlement Report. PayPal notifies merchant-specified users of the following:

Advance notification

• System update and maintenance
• New feature releases
• New version availability

Problems

• Delays in report delivery
• Errors in processing
• System outage

Report format

The user must choose the desired format for the report. The Settlement Report is available in two formats:

• Comma-separated value (CSV): Opens or saves the report in CSV file format, where the data is separated by the comma character and records/rows are separated by new lines.
• Tab-delimited (TAB): Opens and saves the report in .TAB format, where data is separated by a tab.

Character encoding: UTF-8

The report’s character encoding is UTF-8 (8-bit UCS/Unicode Transformation Format). Note: Any report encoded with UTF-8 files will have the BOM (Byte Order Mark) character in the beginning of the report.

Field characteristics

Fields in lines and records can be separated by one of two delimiters, as specified by the report recipient when signing up for the report:

• Comma
• Tab

Money fields

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 example, 100 Yen and $100.00 are both represented as 10000.

Internal punctuation in fields

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.

Spaces or blanks

Some fields can contain spaces. In the descriptions of fields, this is indicated with the words: Blanks: Yes

File structure

The report can be delivered as either a comma-separated values or tab-delimited file. This section describes the structure of the data file.

A report file can contain a maximum of 1 million records. If the report contains more than 1 million records, the report is split across multiple files. The report is also organized by section, where each section represents a single PayPal account. If you are not using PayPal Multiple Account Management, the report contains only a single section.

Report row types

Each row of the report consists of a two letter row type, followed by the details specific to that row type.

A report file with fewer than 1 million records (a single file) with only one section is organized as follows:

1Report Header (RH)
2File Header (FH)
3Section Header (SH)
4Column Header (CH)
5Row Data (SB)
6...
7Row Data (SB)
8Section Footer (SF)
9Section Record Count (SC)
10Report Footer (RF)
11Report Record Count (RC)
12File Footer (FF)

Note: The FH, SC, RC, and RF rows are not available in the Settlement Report, version 001.

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 report footer and a report record count record. A report with two sections split over two files might be organized as follows:

Report data

This section details the columns and related data that is delivered in the report header, report footer, and report record count records.

Report header data

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.

Report footer data

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

Report record count data

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.

File data

This section details the columns and related data that is delivered in the file header, file footer, and file record count records.

File header data

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.

File footer data

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.

Section data

This section details the columns and related data that is delivered in the section header, section footer, and section record count records.

Section header data

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.

Section body data

The records in the Section Body are preceded by a single line of literal column headings that identify the fields in the records that follow. The column heading line is identified by the line type identifier CH.

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.

For transactions with disputes associated with them, claimant information is displayed only in the dispute report. It is not included in the settlement report or the transaction detail report.

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

Section footer data

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.

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.

Reference IDs

Certain transaction types have a pre-existing or originating transaction or event from which they derive or to which they are related. These PayPal reference transactions or events have a unique PayPal reference ID.

• 1:n relationship: A reference transaction or event always has a one-to-one relationship to a single referred transaction or event. Although one reference transaction can have multiple referred transactions, a referred transaction has only reference transaction.
• Event: Reference transactions are only transactions that move money or are related to a future money movement, such as an order, an authorization, a subscription, or a preapproved payment.

Troubleshooting

Important: PayPal updated the settlement functionality to eliminate the occasional mismatch between the balance on your settlement report and the amount settled into your bank account. We are currently onboarding merchants to the updated settlement functionality. This section of the specification is only applicable to those merchants who have been onboarded to the updated settlement functionality. Please contact your account manager for more information.

Refer to the following tips when troubleshooting issues with the settlement report.

Version history

See also

T-codes