Payflow Pro Reporting Developer’s Guide Last updated: June 2010
Payflow Pro Reporting Developer’s Guide Document Number: 200009.en_US-200912 © 2010 PayPal, Inc. All rights reserved. PayPal is a registered trademark of PayPal, Inc. The PayPal logo is a trademark of PayPal, Inc. Other trademarks and brands are the property of their respective owners. The information in this document belongs to PayPal, Inc. It may not be used, reproduced or disclosed without the written approval of PayPal, Inc. Copyright © PayPal. All rights reserved. PayPal (Europe) S.à r.l. et Cie., S.
Contents Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 Audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 Organization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 Where to Go for More Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 How to Contact Customer Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 Revision History . . . . . . . .
Contents Chapter 3 Response Codes and Status Codes . . . . . . . . . . . . . 19 Response Codes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 Status Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 Appendix A Reporting XML Schema . . . . . . . . . . . . . . . . . . . 21 Appendix B Reporting Samples . . . . . . . . . . . . . . . . . . . . . 29 Running a Daily Activity Report . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Contents Creating a Schedule Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51 Getting a Schedule. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52 Getting a Schedule Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52 Getting a Schedule Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52 Updating a Schedule . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53 Updating a Schedule Request . . . .
Contents CommentSearch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87 AccountNumberRefSearch. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88 PurchaseOrderSearch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89 RecurringBillingProfileIDSearch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91 RecurringBillingProfileNameSearch . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Preface Payflow Pro Reporting Developer’s Guide describes the Reporting XML API. The XML API enables you to develop Web and desktop applications that create, schedule, and run standard (pre-defined) and custom Payflow services reports. Audience This guide assumes that its readers: z Have a good understanding of XML application development z Have a background in payments services You should familiarize yourself with the introductory and Payflow documentation on PayPal Manager’s Documentation page.
Preface Where to Go for More Information Where to Go for More Information PayPal Manager online help describes the use of PayPal Manager—the web-based administration tool that you use to process transactions manually, issue credits, and generate reports. How to Contact Customer Service For answers to specific questions about PayPal products, contact Customer Service at payflowsupport@paypal.com Revision History Revision history for Reporting Developer’s Guide. TABLE P.
1 Reporting Overview The Reporting API is an API that you can use to automate your report queries. It allows you to programmatically query in XML the Reporting database. PayPal Manager is also a client of the Reporting API. Everything that Manager can do with reports is available to you through API calls. You can, for example, request a particular report be run within a specified date range. The response returns all the data that the report generates.
1 Reporting Overview URL for Running Applications Running Reports by Report Template Name or Report Name You can run reports and report templates. To run a report or report template, you submit a runReportRequest, passing in the respective report name or report template name. You can also pass in additional parameters in with a request. To submit a request to the Reporting API, you post your XML request via HTTPS to the host URLs in the body of the request.
2 Using the Reporting API This chapter describes how you can use the Reporting API to perform the following tasks. z “Running Reports” on page 12 z “Managing Report Templates” on page 14 z “Using Report Templates” on page 15 z “Performing Searches” on page 18 API Notation in this Chapter The chapter uses the following short-hand notation for referring to Reporting API requests and parameter information. requestName (paramName, paramName, [...]) requestName is the name of the request.
2 Using the Reporting API Where to Go For More Information on the APIs Response Data Responses include the following information: z z z All responses return a base response consisting of a response code (responseCode) and a response message (responseMsg). Most responses return applicable response parameter data. Some responses return a status code (statusCode) and a status message (statusMsg).
Using the Reporting API Running Reports 2 Running a Report and Obtaining Report Data This procedure describes how to run a report and how to obtain the data in that report. Step 1. Run the report To run a report, call runReportRequest, providing the following parameter information. runReportRequest(reportName, reportParams, pageSize) Parameter Description reportName Name of the report, for example, DailyActivityReport.
2 Using the Reporting API Managing Report Templates Data is returned for the report page specified by pageNum. To obtain the data in a multi-page report, you must call getDataRequest for each report page. Running Reports Offline When a report takes longer to run than the time allotted, it is taken offline and status code 2, “Report is currently executing,” is returned. You must check for the results at a later time. Step 1. Run the report Request to run a report by calling runReportRequest. See “Step 1.
Using the Reporting API Using Report Templates reportParam(s) 2 paramName and paramValue of each reportParam to be assigned a value. The response to creating a report template returns a respCode and respMsg. Step 2. Update a report template To update a report template, call the updateTemplateRequest with the following parameters. updateTemplateRequest(templateName, reportParams) templateName Name given to the report template when it was created.
2 Using the Reporting API Using Report Templates reportParam(s) (Optional) paramName and paramValue for each reportParam that you want to assign a value to. These parameters can be ones previously saved in the report template or additional ones. The parameter values take precedence over the values previously saved for the parameters in the report template. pageSize Number of rows of data per page. Default is 50. Step 2.
Using the Reporting API Using Report Templates 2 getScheduleResponse returns all the reportIds and execution dates of the reports that were run on the schedule. Step 3. Get the metadata For each report, call getMetaDataRequest, passing in the reportId as a parameter, to get the information on how that report is formatted. See “Step 2. Get the metadata” on page 13. Step 4. Get the report data Request to get the report data for each report that was run by calling getDataRequest. See “Step 3.
2 Using the Reporting API Performing Searches Performing Searches Using the Reporting API, you can search for transaction data by any of the following search names. z TransactionIDSearch z BatchIDSearch z AccountNumberSearch z CommentSearch z AccountNumberRefSearch z PurchaseOrderSearch z RecurringBillingProfileIDSearch z RecurringBillingProfileNameSearch z RecurringBillingAccountNumberSearch z RecurringBillingCommentSearch z RecurringBillingAmountSearch Step 1.
3 Response Codes and Status Codes This chapter provides the following details on reports. It identifies: z Response codes and response messages z Status codes and the status messages Response Codes Response codes indicate the success or failure of a Reporting request. Table 5-2 describes the supported response codes and messages returned with each. TABLE 3.
3 Response Codes and Status Codes Status Codes Status Codes Status codes indicate the status of a report, not necessarily the status of the Reporting request to be executed. A report may fail even if a Reporting request succeeds. TABLE 3.
A Reporting XML Schema This appendix contains the XML Reporting 1.0 schema. PAGE 22A Reporting XML Schema
Reporting XML Schema A
A Reporting XML Schema PAGE 25Reporting XML Schema A
PAGE 26A Reporting XML Schema
Reporting XML Schema A
A 28 Reporting XML Schema Reporting Developer’s Guide
B Reporting Samples This appendix demonstrates how to use the Reporting API to create, run, and manage reports. For details on the predefined reports named in this appendix, see the Manager User’s Guide. N O T E : In this appendix, replace these values shown in boldface with appropriate values: User, Vendor, Partner, and Password. Running a Daily Activity Report This section demonstrates how to run a Daily Activity Report.
B Reporting Samples Running a Daily Activity Report Running a Daily Activity Report Response In the response to running the Daily Activity Report, the responseCode of 100 indicates that the report completed successfully. The reportId 132 returned is used to uniquely identify this report in future calls to the Reporting API.
Reporting Samples Running a Transaction Summary Report B R u n n i n g a Tr a n s a c t i o n S u m m a r y R e p o r t This sample demonstrates how to run a Transaction Summary Report. Running a Transaction Summary Report Request The request demonstrates how to run a Transaction Summary Report with a page size of 50 lines starting on September 7, 2007 at 12:00AM and ending on September 7, 2007 at 12:59 and 59 seconds PM.
B Reporting Samples Getting Results by Report ID Running a Transaction Summary Report Response In the response to running the Transaction Summary Report, the response code of 100 indicates that the request completed successfully. The status code of 3 indicates that the report completed successfully and the reportId 131 is returned for future reverence in calls inquiring about this report.
Reporting Samples Getting Metadata B Getting Results by Report ID Response In the response to getting results by report ID, the response code of 100 indicates that the request completed successfully. The status code of 3 indicates that the report with reportId 131 completed successfully.
B Reporting Samples Getting Metadata Getting Metadata Response In the response to retrieving metadata, the response code of 100 indicates that the request completed successfully. The response returns the number columns, rows, pages, and lines per page are present in the format of the report with reportID 131. For each table column, the response returns the column heading.
Reporting Samples Getting Metadata B Reponse Msg string Comment1 string Comment2 string Format Returned The format returned by this sample is shown below.
B Reporting Samples Getting Data G e t t i n g D a ta This sample demonstrates how to retrieve the data in a previously run report. Getting Data Request In the request to retrieve data, reportId 131 specifies the report for which the data is being requested. The reportId value of 131 was returned in a previous call to run the report. The pageNum refers to the page number desired in a multi-page report.
Reporting Samples Getting Data B 4111XXXXXXXX1111 01/07 A1000 0 Approved V89A0A000088 2007-09-07 17:46:09
B Reporting Samples Getting Data V89A0A000089 2007-09-07 17:48:20 S 0 4111XXXXXXXX1111 01/07 A1000 0 <
Reporting Samples Getting Data B 0 4111XXXXXXXX1111 01/07 A1000 0 Approved V89A0A00008B 2007-0
B Reporting Samples Getting Data Approved V89A0A00008C 2007-09-07 17:53:32 S 0 4111XXXXXXXX1111 01/07 A1000
Reporting Samples Getting Data B S 0 4111XXXXXXXX1111 01/07 A1000 0 Approved V89A0A00008E
B Reporting Samples Getting Data 0 Approved V89A0A00008F 2007-09-07 17:56:33 S 0 4111XXXXXXXX1111 01/07
Reporting Samples Getting Data B 2007-09-07 18:01:31 S 0 4111XXXXXXXX1111 01/05 A1000 24 Unknown error
B Reporting Samples Getting Data 0 Approved V89A0A000092 2007-09-07 18:02:19 S 0 4111XXXXXXXX1111 12/05
Reporting Samples Getting Data B 2007-09-07 18:03:09 S 0 4111XXXXXXXX1111 12/05 A1000 0 Approved
B Reporting Samples Getting Data Data Returned The data is returned in the following tabular format of 13 rows and 11 columns: 46 V89A0A000087 2007-09-07 17:45:07 S O 4111XXXXXXXX1111 01/07 A1000 O Approved V89A0A000088 2007-09-07 17:45:09 S O 4111XXXXXXXX1111 01/07 A1000 O Approved V89A0A000089 2007-09-07 17:48:20 S O 4111XXXXXXXX1111 01/07 A1000 O Approved V89A0A00008A 2007-09-07 17:52:03 S O 4111XXXXXXXX1111 01/07 A1000 O Approved V89A0A00008B 2007-09-07 17:53:07
Reporting Samples Creating a Report Template B C r e a t i n g a R e p o r t Te m p l a t e This sample demonstrates how to create a report template from a standard Daily Activity Report. Creating a Report Template Request This request creates a report template from a Daily Activity Report with a report template name of ‘My Template.’ It sets the values of two parameters (name1 and name2). The parameter names and values are stored in the database.
B Reporting Samples Updating a Report Template Updating a Report Template This sample demonstrates how to update the parameter information in a report template. Updating a Report Template Request The request specifies the report template to update by its name ‘My Template’ and the report type (Daily Activity Report) upon which it was originally based.Updating a report template is not an additive process.
Reporting Samples Getting a Report Template B Getting a Report Template This sample demonstrates how to retrieve a report template. Getting a Report Template Request The request specifies the report template name ‘My Template’ to retrieve.
B Reporting Samples Deleting a Report Template Deleting a Report Template This sample demonstrates how to delete a report template. Deleting a Report Template Request The request to delete a report template includes the templateName ‘My Template.’
Reporting Samples Creating a Schedule B Creating a Schedule This sample demonstrates how to create a schedule for a report template. Creating a Schedule Request ?xml version="1.
B Reporting Samples Getting a Schedule Getting a Schedule Getting a Schedule Request ?xml version="1.
Reporting Samples Updating a Schedule B U pd a t i n g a S c h e d u l e This sample demonstrates how to update a schedule. Updating a Schedule Request
B Reporting Samples Deleting a Schedule Deleting a Schedule This sample demonstrates how to delete a schedule.
Reporting Samples Running a Transaction ID Search B R u n n i n g a Tr a n s a c t i o n I D S e a r c h This sample demonstrates how to run a search by transaction ID. Running a Transaction ID Search Request
B 56 Reporting Samples Running a Transaction ID Search Reporting Developer’s Guide
C Report Parameters Daily Activity Report TABLE C.
C Report Parameters Daily Activity Report Currency values are returned in the three-character currency code specified. The values are: z USD (US dollar) (default value) z EUR (Euro) z GBP (UK pound) z CAD (Canadian dollar) z JPY (Japanese Yen) z AUD (Australian dollar) TABLE C.
Report Parameters Transaction Summary Report C Tr a n s a c t i o n S u m m a r y R e p o r t TABLE C.
C Report Parameters Settlement Report Settlement Report TABLE C.
Report Parameters Settlement Report TABLE C.
C Report Parameters PayPal Settlement Summary Report PayPal Settlement Summary Report TABLE C.7 Default value Autocomputed by scheduler ? Y N/A Y datetime YYYY-MMDD HH:MI:SS Y N/A Y string N GMT N Name Description Type Required? start_date Start date to run report for datetime YYYY-MMDD HH:MI:SS end_date End date to run report for timezone Timezone used to interpret times TABLE C.
Report Parameters Shipping and Billing Report C Shipping and Billing Report TABLE C.
C Report Parameters Batch ID Report TABLE C.
Report Parameters Custom Report C TABLE C.11 Batch ID Report input parameters timezone Timezone used to interpret times string N GMT GMT+/-XX:XX GMT N group_by_ tender Should group results by tender? string N true false false N TABLE C.
C Report Parameters Custom Report TABLE C.
Report Parameters Custom Report C TABLE C.
C Report Parameters Custom Report TABLE C.
Report Parameters Custom Report C TABLE C.
C Report Parameters Custom Report TABLE C.
Report Parameters Custom Report C TABLE C.
C Report Parameters Custom Report TABLE C.
Report Parameters C Fraud Protection Report TABLE C.14 Custom Report output parameters Shipping First Name string Shipping Last Name string Shipping Address string Shipping City string Shipping State string Shipping Zip string Shipping Country string Customer Code string Freight Amount currency Duty Amount currency Fraud Protection Report TABLE C.
C Report Parameters Filter Scorecard Report TABLE C.16 Fraud Protection Report output parameters Column name Type Transaction ID string Time date Type string Tender Type string Amount currency Deployment Mode string Fraud Transaction string Filter Scorecard Report TABLE C.
Report Parameters Auto Delayed Capture Report C Auto Delayed Capture Report TABLE C.19 Auto Delayed Capture Report input parameters Default value Autocomputed by scheduler? Y N/A Y datetime YYYY-MMDD HH:MI:SS Y N/A Y string N GMT N Name Description Type Required? start_date Start date to run report for datetime YYYY-MMDD HH:MI:SS end_date End date to run report for timezone Timezone used to interpret times Allowed values GMT GMT+/XX:XX TABLE C.
C Report Parameters Auto Credit Report Auto Credit Report TABLE C.21 Auto Credit Report input parameters Default value Autocomputed by scheduler? Y N/A Y datetime YYYYMM-DD HH:MI:SS Y N/A Y string N GMT N Required ? Name Description Type start_date Start date to run report for datetime YYYYMM-DD HH:MI:SS end_date End date to run report for timezone Timezone used to interpret times Allowed values GMT GMT+/XX:XX TABLE C.
Report Parameters Auto Void Report C Auto Void Report TABLE C.23 Auto Void Report input parameters Default value Autocomputed by scheduler? Y N/A Y datetime YYYYMM-DD HH:MI:SS Y N/A Y string N GMT N Required ? Name Description Type start_date Start date to run report for datetime YYYYMM-DD HH:MI:SS end_date End date to run report for timezone Timezone used to interpret times Allowed values GMT GMT+/XX:XX TABLE C.
C Report Parameters Auto Resettle Report Auto Resettle Report TABLE C.25 Auto Resettle Report input parameters Default value Autocomputed by scheduler? Y N/A Y datetime YYYYMM-DD HH:MI:SS Y N/A Y string N GMT N Required ? Name Description Type start_date Start date to run report for datetime YYYYMM-DD HH:MI:SS end_date End date to run report for timezone Timezone used to interpret times Allowed values GMT GMT+/XX:XX TABLE C.
Report Parameters Recurring Billing Report C Recurring Billing Report TABLE C.
C Report Parameters Recurring Profile Report TABLE C.28 Recurring Billing Report output parameters Result Code number Recurring Profile Report TABLE C.
Report Parameters Recurring Profile Report C TABLE C.
C Report Parameters Recurring Profile Failed Report Recurring Profile Failed Report TABLE C.31 Recurring Profile Failed Report input parameters Name Description Type Required? start_date Start date to run report for date YYYYMM-DD Y timezone Timezone used to interpret times string N Allowed values GMT GMT+/XX:XX Default value Autocomputed by scheduler? N/A Y GMT N TABLE C.
D Search Parameters Transaction ID Search TABLE D.1 Transaction ID Search input parameters Name Description Type Required ? transaction_id Transaction ID to search for string Y timezone Timezone used to interpret times string N TABLE D.
D Search Parameters Transaction ID Search TABLE D.
Search Parameters Batch ID Search D Batch ID Search TABLE D.3 Batch ID Search input parameters Name Description Type Required ? batch_id Batch ID to search for string Y start_date Start date to search for datetime YYYYMM-DD HH:MI:SS Y end_date End date to search for datetime YYYYMM-DD HH:MI:SS Y timezone Timezone used to interpret times string N TABLE D.
D Search Parameters AccountNumberSearch AccountNumberSearch TABLE D.5 Name Description Type Required ? account_number Account Number to search for string Y start_date Start date to search for datetime YYYY-MMDD HH:MI:SS Y end_date End date to search for datetime YYYY-MMDD HH:MI:SS Y timezone Timezone used to interpret times string N TABLE D.
Search Parameters CommentSearch D CommentSearch TABLE D.
D Search Parameters AccountNumberRefSearch TABLE D.8 CommentSearch output parameters Account Number string Expires string Amount currency Response Msg string Comment1 string Comment2 string AccountNumberRefSearch TABLE D.
Search Parameters PurchaseOrderSearch D TABLE D.10 AccountNumberRefSearch output parameters Type string Tender Type string Account Number string Expires string Amount currency Response Msg string Comment1 string Comment2 string PurchaseOrderSearch TABLE D.
D Search Parameters PurchaseOrderSearch TABLE D.
Search Parameters RecurringBillingProfileIDSearch D RecurringBillingProfileIDSearch TABLE D.13 RecurringBillingProfileIDSearch input parameters Name Description Type Required ? profile_id Recurring Billing Profile ID to search for string Y timezone Timezone used to interpret times string N Allowed values Default value Autocomputed by scheduler? GMT GMT+/XX:XX GMT N TABLE D.
D Search Parameters RecurringBillingProfileNameSearch TABLE D.14 RecurringBillingProfileIDSearch output parameters Date Established date RecurringBillingProfileNameSearch TABLE D.15 RecurringBillingProfileNameSearch input parameters Name Description Type Required ? profile_name Recurring Billing Profile Name to search for string Y timezone Timezone used to interpret times string N Allowed values Default value Autocomputed by scheduler? GMT GMT+/XX:XX GMT N TABLE D.
Search Parameters RecurringBillingAccountNumberSearch D RecurringBillingAccountNumberSearch TABLE D.17 RecurringBillingAccountNumberSearch input parameters Name Description Type Required? account_number Account number to search for string Y timezone Timezone used to interpret times string N Allowed values Default value Autocomputed by scheduler? GMT GMT+/XX:XX GMT N TABLE D.
D Search Parameters RecurringBillingCommentSearch RecurringBillingCommentSearch TABLE D.19 RecurringBillingCommentSearch input parameters Name Description Type Required? comment Comment to search for string Y timezone Timezone used to interpret times string N Allowed values Default value Autocomputed by scheduler? GMT GMT+/XX:XX GMT N TABLE D.
Search Parameters RecurringBillingAmountSearch D RecurringBillingAmountSearch TABLE D.21 RecurringBillingAmountSearch input parameters Name Description Type Required? amount Amount to search for string Y timezone Timezone used to interpret times string N Allowed values Default value Autocomputed by scheduler? GMT GMT+/XX:XX GMT N TABLE D.
D Search Parameters FraudTransactionSearch F r a u d Tr a n s a c t i o n S e a r c h TABLE D.23 FraudTransactionSearch input parameters Name Description Type Required? fraud_transaction_id Fraud transaction ID to search for string Y transaction_type Transaction timezone Timezone used to interpret times string N Allowed values Default value Autocomputed by scheduler? GMT GMT+/XX:XX GMT N TABLE D.
Search Parameters FraudTransactionSearch D TABLE D.
D Search Parameters OrderIDSearch OrderIDSearch TABLE D.25 OrderIDSearch input parameters Name Description Type Required ? order_id Order ID to search for string Y timezone Timezone used to interpret times string N Allowed values Default value Autocomputed by scheduler? GMT GMT+/XX:XX GMT N TABLE D.
Search Parameters PayPalTransactionIDSearch D TABLE D.26 OrderIDSearch output parameters Comment2 string Result Code number Response Msg string Authcode string Original Transaction ID string AVS Street Match string Original Amount currency AVS Zip Match string Batch ID number AVS Result Code string PayPalTransactionIDSearch TABLE D.
D Search Parameters PayPalTransactionIDSearch TABLE D.
Search Parameters PayPalEmailSearch D PayPalEmailSearch TABLE D.29 PayPalEmailSearch input parameters Name Description Type Required ? email Email address to search for string Y start_date Start date to search for datetime YYYYMM-DD HH:MI:SS Y end_date End date to search for datetime YYYYMM-DD HH:MI:SS Y timezone Timezone used to interpret times string N Allowed values Default value Autocomputed by scheduler? GMT GMT+/XX:XX GMT N TABLE D.
D Search Parameters PayPalNameSearch PayPalNameSearch TABLE D.
Index Index C R createScheduleRequest 16 createTemplateRequest 14 creating report templates 47 creating schedules 51 creating templates 47 response codes 19 retrieve report results by reportId 32 retrieving metadata 33 retrieving report data 36 retrieving templates 49 running an ad hoc report 31 running reports 13 running reports offline 14 running transaction ID search 55 runReportRequest 13, 15 runSearchRequest 18 D Daily Activity Report 29 deleteScheduleRequest 17 deleteTemplateRequest 15 deleting r
Index 104 Reporting Developer’s Guide
