Recurring Payments Profile

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


Overview

The Recurring Payments Profile Report (RPP) is for use by any merchant or payment processing partner, who have integrated the Recurring Payments Product. The Recurring Payments Profile Report gives merchants and processing partners detailed information about outstanding subscribed monthly payments.

The Recurring Payments Profile Report is available through PayPal’s website and Secure FTP Server, which is defined and described in the Secure FTP Server Specification. Recurring Payments are created with PayPal Recurring Payments API, as documented in the NVP API Developer Guide and Reference.

Know before you begin

  • The RPP is available via the Secure FTP Server (reports.paypal.com), which requires a separate user account for access to the RPP. A user account that is enabled for the RPP is also enabled to create user accounts for the Secure Drop-Box. To ensure data security, RPP users must generate their own user accounts for the Secure Drop-Box.
  • The RPP is generated and delivered by PayPal on a regular (24 hour) basis. With the initial release of the RPP, the RPP is generated and distributed by 9AM daily in the leading timezone of the reporting window.
  • You can receive the RPP in either comma separated value (csv) or tab delimited values format (tab). Contact your PayPal Account Manager to set the data format for this report.
  • The RPP is available via the Secure FTP Server for 45 days after the date of its delivery.
  • The reports character encoding is UTF-8 (8-bit UCS/Unicode Transformation Format).
  • The reports are available in these formats:
    • Portable Document Format (PDF)
    • Comma-Separated Values (CSV)

Distribution and access

The following steps describe how to set up and access the RPP using the Secure FTP Server:

  1. Create a Secure FTP Server user account. Login to PayPal (www.paypal.com) and create a Secure PayPal Reporting FTP Server username and password. Passwords for accessing the Secure FTP Server cannot be reset by PayPal. To obtain a new password, you must create a new Secure FTP Server user account.

  2. Grant access to third-party users. You must explicitly grant access to third-parties by contacting their PayPal Account Manager to supply the following information: – Third-parties’ PayPal login username – Type of permission: reporting access (read) The third-party is then notified by email that access to the business partner’s Secure FTP Server has been granted.

  3. Access the Secure FTP Server programmatically using an FTP client. The hostname of the Secure FTP Server is reports.paypal.com. A user account on the Secure FTP Server has the following directory structure: /ppreports/outgoing

New or revised versions

In the future, PayPal will support multiple versions of the RPP. 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.

Notifications

PayPal operationally monitors the generation and delivery of the RPP 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 the RPP.

Section 1: Report file name

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

The filename of the RPP for a single account follows this naming convention:

RPP-yyyymmdd.SequenceNumber.Version.Format
FieldInformation
RPPAn abbreviation for Recurring Payments Profile.
yyyymmddThe date for the data in the report. It represents the latest, or ending date, of the data.
SequenceNumberThe sequence number of the report file. It is two characters, right-justified, and zero-filled. The sequence number begins with 01 and continues until all parts of the report are recorded in files. The sequence number is always present in the report filename even if there is only one file.
VersionThe version of the report. Three characters, right-justified and zero-filled.
FormatOne of the following:
  • CSV (comma-separated values)
  • TAB (tab-delimited field)

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

RPP-yyyymmdd.ReportingWindow.SequenceNumber.TotalFiles.Version.Format
FieldInformation
RPPAn abbreviation for Recurring Payments Profile.
yyyymmddThe date for the data in the report. It 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
SequenceNumberThe sequence number of the report file. It is two characters, right-justified, and zero-filled. The sequence number begins with 01 and continues until all parts of the report are recorded in files. The sequence number is always present in the report filename even if there is only one file.
TotalFilesThe total number of files of the report for this date. The number of files is always two digits and zero-padded. For example, for 2 total files, TotalFiles is 02.
VersionThe version of the report. Three characters, right-justified and zero-filled.
FormatOne of the following:
  • CSV (comma-separated values)
  • TAB (tab-delimited field)

Section 2: 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. The following table lists the valid row types, along with the sections that describe the data for that row type.

Row types

CodeDescriptionSection
RHReport headerReport Header Data
FHFile headerFile Header Data
SHSection headerSection Header Data
CHColumn headerSection Body Data
SBRow dataSection Body Data
SFSection footerSection Footer Data
SCSection record countSection Record Count Data
RFReport footerReport Footer Data
RCReport record countReport Record Count Data
FFFile footerFile Footer Data

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

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

File 1File 2
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)
Section Header (SH)
Column Header (CH)
Row Data (SB)
...
File Footer (FF)
File Header (FH)
Row Data (SB)
...
Row Data (SB)
Section Footer (SF)
Section Record Count (SC)
Report Footer (RF)
Report Record Count (RC)
File Footer (FF)

Section 3: Report data

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

Note: 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.

PositionColumn nameData typeData Description
1Column TypeLiteralRH
2Report Generation DateDate/timeThe 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.
3Reporting WindowVarcharThe 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.
4Account IDVarcharAccount number receiving the report (Payer ID – encrypted hash of PayPal account).
5Report VersionVarcharThe 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.

PositionColumn nameData typeData description
1Column TypeLiteralRF
2Row CountNumberThe number of body data rows in the report (used for reconciliation). Note that 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.

PositionColumn nameData typeData description
1Column TypeLiteralRC
2Row CountNumberThe number of body data rows in the report (used for reconciliation). Note that the report may span multiple files.

Section 4: File data

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

Note: 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.

PositionColumn nameData typeData description
1Column TypeLiteralFH
2Row CountNumberThe 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.

PositionColumn nameData typeData description
1Column TypeLiteralFF
2Row CountNumberThe number of body data rows in the file (used for reconciliation).

Section 5: Section data

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

NOTE: 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.

PositionColumn nameData typeData description
1Column TypeLiteralSH
2Reporting Period Start DateDate/timeThe date 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.
3Reporting Period End DateDate/timeThe date 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.
4Account IDVarcharAccount number generated by PayPal.

Section body

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:

CH,"Profile ID","Description","Payer Name","Payer Email","Billing Cycles","Currency Code","Amount","Tax Amount","Ship Amount","Profile Status","Billing Period Type","Billing Cycles Remaining","Date Last Paid","Amount Last Paid","Outstanding Balance","Next Bill Date","Num Failed Payment","Date Last Modified"
Filed nameData characteristicsDescription
Column TypeLiteralCH
Profile IDType: alphanumeric
Max Length: 64 characters
Profile ID of the subscriber; encrypted value given to the customer during profile setup.
Example: I-6FE511321P0478119.
DescriptionType: alphanumeric
Max Length: 127 characters
Product or service to which the customer is subscribed.
Payer NameType: Varchar
Blanks: Yes
Max Length: 64 characters
Name of the payer.
Payer EmailType: alphanumeric
Max Length: 127 characters
Email ID of the payer.
Billing cycleType: numeric
Max Length: 38
Frequency of the scheduled payment. This is a combination of two fields: BillingPeriod + BillingFrequency).
Example: 5 Days
Currency CodeType: currency
Max Length: 3 characters
Currency of the transaction.
Example: USD
AmountType: numeric
Max Length: 38 characters
Recurring payment base amount (in cents).
Example: 2000
TaxAmount Type: numeric
Max Length: 38 characters
Tax amount to be added to the base amount (in cents).
Example: 180
Ship AmountType: numeric
Max Length: 38 characters
Shipping and handling amount to be added to the base amount.
Example: 500
ProfileStatus Type: alpha
Max Length: 1 character
Status of the profile. Values are:
  • Active
  • Inactive
  • Suspended
Billing Period TypeType: alpha
Max Length: 1 character
Type of the billing period. Values are:
  • Trial
  • Regular
Billing Cycles RemainingType: alpha
Max Length: 1 character
The number of billing cycles remaining.
Example: 2
Date Last PaidType: dateDate and time of the last successful payment, 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.
Amount Last PaidType: numeric
Max Length: 38 characters
Amount (in cents) of last successful payment.
Example: 2680
Outstanding BalanceType: numeric
Max Length: 38 characters
Amount delinquent.
Next Bill DateType: dateDate and time of the next scheduled bill date, 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.
Num failed PaymentType: numericNumber of failed payments currently associated with the profile.
Example: 2
Date_Last_ModifiedType: dateDate and time the profile was last modified, 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.

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.

PositionColumn nameData typeData description
1Column TypeLiteralSF
2Row CountNumberThe 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.

PositionColumn nameData typeData description
1Column TypeLiteralSC
2Row CountNumberThe number of body data rows in the section (used for reconciliation).

Sample CSV report

"RH",2007/12/05 22:43:15 -0800,"A","QRQJ9CLWCBH3Q",001,<br />
        FH,01<br />
        SH,2007/12/03 00:00:00 -0800,2007/12/03 23:59:59 -0800,"QRQJ9CLWCBH3Q"<br />
        CH,"Profile ID","Description","Payer Name","Payer Email","Billing Cycles","Currency Code","Amount","Tax Amount","Ship Amount","Profile Status","Billing Period Type","Billing Cycles Remaining","Date Last Paid","Amount Last Paid","Outstanding Balance","Next Bill Date","Num Failed Payment","Date Last Modified"<br />
        SB,"I-6FE511321P0478119","Item6","PrabhaS","pshanmugam-us2-buyer@paypal.com","1Days","USD",500,100,100,"Suspended","Regular",0,"",,100,"",1,"2007/12/0302:00:35 -0800"<br />
        SF,2<br />
        SC,2<br />
        RF,2<br />
        RC,2<br />
        FF,2<br />

Version history

Publication dateVersionChanges
September 20201.3Converted this report specification documentation from PDF to HTML.
April 20191.2Updated the file record limit from 100,000 to 1 million.
September 20151.1Various content changes
September 20121.0.3Changed file format to - RPP-yyyymmdd.sequenceNumber.version.format
August 20121.0.2Updated data description for Payer Name.
October 20081.0.1Updated information about report retention time on the Secure FTP Server and changed the Secure FTP server directory location from ppreports to ppreports/outgoing.
March 20081.0.0First release of PayPal Recurring Payments Profile Report.

See also