Preapproved Payments Agreement Report Specification

DOCSCurrent

Last updated: Sept 24th, 4:21pm

The Preapproved Payments Agreement Report is for use by merchants or payment processing partners, who have integrated the Preapproved Payments Product. The Preapproved Payments Agreement Report gives merchants and processing partners detailed information about outstanding Preapproved Payments billing agreements.

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. This report is generated and distributed by 9:00 AM daily in the leading timezone of the reporting window.
  • The character encoding of this report is UTF-16 (16-bit UCS/Unicode Transformation Format).
  • This report is available via the Secure FTP Server for 45 days after the date of its delivery.

Notifications

In the future, PayPal will support multiple versions of this report. PayPal will notify you regarding the creation of any new version as well as any deprecation of older versions of the report. If you wish to take advantage of a new version, you can receive two versions of the same report concurrently in order to test and integrate the new version. You can also receive nonconsecutive versions of the same report concurrently in order to test and integrate the new version. Contact your PayPal Account Manager to enable different versions and request any changes in report distribution.

PayPal operationally monitors the generation and delivery of this report on a 24/7 365 basis. PayPal maintains two different user contact points for report notifications:

  • A business contact point for all notifications related to data integrity, data delivery, and new reporting features
  • A technical contact for all notifications related to data integrity, data delivery, system outages, system updates, and new features.

PayPal will notify you of the following events related to reporting.

  • Delays in report delivery
  • Errors in report generation
  • New version availability
  • System outage
  • System update/maintenance (pre-announcement)
  • New reporting feature releases

Contact your PayPal Account Manager to provide PayPal with the appropriate notification email alias. PayPal strongly recommends that you create a distribution list or email alias that allows multiple parties to receive communication about this report.

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:

PPA-yyyymmdd.sequenceNumber.version.format

Field Information
PPA An abbreviation for Downloadable Preapproved Payments Agreement Report.
yyyymmdd The date on the data in the report. This date stamp represents the latest, or ending date, of the data.
sequenceNumber The 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.
version The version of the report. Three characters, right-justified and zero-filled.
format The report format is TAB (tab-separated values) or CSV (comma-separated value).

Multiple account report

When using Multiple Account Management, the filename of the report follows this naming convention:

PPA-yyyymmdd.reportingWindow.sequenceNumber.totalFiles.version.format

Field Information
PPA An abbreviation for Downloadable Preapproved Payments Agreement Report.
yyyymmdd The date on the data in the report. This date stamp represents the latest, or ending date, of the data.
reportingWindow The window of time when the report was generated, as follows:
X: GMT 00:00 to GMT -0500
A: GMT -0500 to GMT-0800
H: GMT-0800 to GMT +0800
R: GMT +0800 to GMT 00:00
sequenceNumber The 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.
totalFiles The total number of files of the report ofr this date. The number of files is always two digits and zero-padded. For example, for two total files, totalFiles is 02.
version The version of the report: three characters, right-justified and zero-filled.
format The report format is TAB (tab-separated values) or CSV (comma-separated value).

Report 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.

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

Report row types

This table lists the valid row types, along with the sections that describe the data for that row type.

Code Description Section
RH Report header Report Header Data
FH File header File Header Data
SH Section header Section Header Data
CH Column header Section Body Data
SB Row data Section Body Data
SF Section footer Section Footer Data
SC Second record count Section Footer Data
RF Report footer Report Footer Data
RC Report record count Report Record Count Data
FF File footer File Footer Data

A report file with fewer than 1 million 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 1 File 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 data

This section details the columns and related data that is delivered in the report header, report footer, and report record count records. If the report is split over multiple files, only the last file contains the 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.

Position Column name Data type Data 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/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.
3 Reporting window Varchar The window of time when the reoprt was generated as follows:
X: GMT 00:00 to GMT -0500
A: GMT -0500 to GMT-0800
H: GMT-0800 to GMT +0800
R: GMT +0800 to GMT 00:00
4 Account ID Varchar Account number receiving the report (Payer ID - encrypted hash of PayPal account)
5 Report version Varchar The version of the report

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 Data Description
1 Column type Literal RF
2 Row count Number The number of body data rows in the report (used for reconciliation). The report may span multiple files.

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.

Position Column name Data type Data Description
1 Column type Literal RC
2 Row count Number The number of body data rows in the report (used for reconciliation). The report may span multiple files.

File data

This section details the columns and related data that is delivered in the file header and file footer records. Each file in the report has a file header and a file footer, even if the number of files in the report is one.

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.

Position Column name Data type Data 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 Data Description
1 Column type Literal FF
2 Row count Number The number of body data rows in the file (used for reconciliation).

Section data

This section details the columns and related data that is delivered in the section header, section footer, and section record count records. If you are not using Multiple Account Management, the report contains only one section.

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.

Position Column name Data type Data Description
1 Column type Literal SH
2 Reporting period start date Date/time The date and time that represents the beginning time period of the report 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.
3 Reporting period end date Date/time The date and time that represents the ending time period of the report 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.
4 Account ID Varchar Account number generated by PayPal

Section body data

Body data exists in one row with each element being 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 (except for the column type field). For example:

    1"CH","Agreement Id","Agreement Action Type","Agreement Payment
    2        Type",

      1"Agreement Max Amount","Total Bill to Date","Agreement
      2        Currency",

        1"Agreement Modification Date","Agreement Description","Agreement
        2        Payer PayPal Account ID",

          1"Agreement Payer Email Address","Agreement Payer
          2        Name","Agreement Payer Business Name","Agreement Custom Field"

          Section body field definitions

          Field name Data characteristics Description
          1 Column type Literal SB
          2 Agreement ID Varchar
          Blanks: Yes
          Max length: 24 characters          		 The billing agreement identification number as returned to you by PayPal when a billing agreement is created.
          3 Agreement action type Alphanumeric
          Max length: 5 characters          		 One of the following values:
          P00000: Billing agreement created: general
          P0100: Billing agreement canceled: general
          P0200: Billing agreement update: general
          P0110: Billing agreement canceled: Due to non-activity
          4 Agreement payment type Alphanumeric
          Max length: 5 characters          		 Type of payment the payer's account is capable of, as indicated by one of the following values:
          X: The payer's account does not have a valid or current funding source. Possible reasons: the payer has not verified his bank account or has not completed enrollment with PayPal.
          E: Capable of paying with eCheck
          I: Capable of paying instantaneously
          5 Agreement maximum monthly amount Currency/amount
          Max length: 20 characters          		 Maximum monthly amount the payer agrees that the merchant can charge against the payer's PayPal account.
          6 Total billed-to-date Currency/amount
          Max length: 25 characters          		 Current sum of all amounts charged against the agreement ID made with the BillUser API.
          7 Agreement currency Three-character currency code
          Max length: 3 characters          		 Currency of transaction. See currencies for possible values.
          8 Agreement modification date Date/time
          Max length: 25 characters          		 The date and time the 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.
          9 Agreement description Alphanumeric
          Blanks: yes
          Max length: 200 characters          		 Description of the agreed as specified by the merchant.
          10 Agreement payer PayPal Account ID Varchar
          Blanks: yes
          Max length: 24 characters          		 Unique PayPal customer account number.
          11 Agreement payer email address Varchar
          Max length: 127 characters          		 Email address of payer.
          12 Agreement payer name Varchar
          Blanks: yes
          Max length: 64 characters          		 First and last name of agreement payer, in the following format: firstName lastName
          13 Agreement payer business name Varchar
          Blanks: yes
          Max length: 127 characters          		 Payer's business name.
          14 Agreement custom field Varchar
          Blanks: yes
          Max length: 256 characters          		 Custom content specified by originator of the agreement. Reserved for use by merchant.

          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 Data Description
          1 Column type Literal SF
          2 Row count Number The number of body data rows in the section (used for reconciliation).

          Section record count data

          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 Data Description
          1 Column type Literal SC
          2 Row count Number The number of body data rows in the section (used for reconciliation).

          Version history

          Publication date Version Changes
          April 2019 2.2 Updated the file record limit from 100,000 to 1 million.
          September 2015 2.1 Various content changes.
          December 2013 2.0 Changed UTF-8 to UTF-16.
          June 2013 2.0 Updated the allowable values for Agreement Payment type - X, I, and E.
          October 2012 2.0 Changed the order so that Record Footer Data (RF) appears before Report Record Count Data (RC).
          Updated sample report.
          September 2012 2.0 Updated version to 2.0
          Changed file format to PPA-yyyymmdd.sequenceNumber.version.format
          Changed the order so that Report Record Count Data (RC) appears before Record Footer Data (RF).
          Updated sample report.
          August 2012 1.2.5 Updated the data description for the following fields:
          Agreement ID
          Agreement payer PayPal account ID
          Agreement payer name
          March 2009 1.2.4 Corrected report name from PAP to PPA
          October 2008 1.2.3 Updated information about report retention time on the SFTP server.
          Changed the SFTP directory location from ppreports to ppreports/outgoing.
          May 2007 1.2.2 Updated to reflect new file and data structure.
          August 2006 1.0.0 First release of Preapproved Payments Agreement Report.

          See also

          ReferencePayPal.comPrivacyCookiesSupportLegalContact

          We use cookies to improve your experience on our site. May we use marketing cookies to show you personalized ads? Manage all cookies