Use the Reporting API

Overview

The Reporting API notation here does not include the authorization information that is passed with every request. All Reporting API requests require that you specify these parameters and values as your user information.

Parameter Description
user If you set up one or more additional users on the account, this value is the ID of the user authorized to process transactions. If, however, you have not set up additional users on the account, user has the same value as vendor.
vendor Your merchant login ID that you created when you registered for the Payflow account.
partner The ID provided to you by the authorized PayPal Reseller who registered you for the Payflow service. If you purchased your account directly from PayPal, use PayPal.
password The 6 to 32-character password that you defined while registering for the account.

Responses include the following information:

  • 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).

Run reports

You can run reports and obtain the report data right away. If, however, running a report takes more than the time allotted, the report is run offline, and you must periodically check for the report data.

To run a report:

  1. Call runReportRequest, providing the following parameter information.

    runReportRequest(reportName,reportParams,pageSize)
    
    Parameter Description
    reportName Name of the report, for example, DailyActivityReport.
    reportParam(s) (Optional) and for each request input param to be assigned a value.
    pageSize Number of rows of data per page. Default is 50.

    The runReportResponse returns the reportId. The reportId is used to refer to the particular report in future requests. The reportId returned is valid for up to 120 days.

  2. Call getMetaDataRequest, providing the ReportId returned when the report was run, to get the metadata.

    getMetaDataRequest(ReportId)
    

    getMetaDataResponse returns the following data.

    Parameter Description
    numberOfRows Total number of rows.
    numberOfPages Total number of pages in the report.
    pageSize Page size.
    numberOfColumns Total number of columns.
    dataName Name of each column.
    dataType Type of column data, for example, string.
  3. Call getDataRequest with the following parameters to get the report.

    getDataRequest(reportId,pageNum)
    
    Parameter Description
    reportId ID for this report returned by runReportRequest; reportId is valid for up to 120 days.
    pageNum Report page number containing data to be returned.

    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.

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

  1. Request to run a report by calling runReportRequest.

    runReportRequest(reportName,reportParams,pageSize)
    
    Parameter Description
    reportName Name of the report, for example, DailyActivityReport.
    reportParam(s) (Optional) and for each request input param to be assigned a value.
    pageSize Number of rows of data per page. Default is 50.

    The report times out. The ReportId and status code 2 are returned.

  2. Get the report results later by calling getResultsRequest, providing the reportId as a parameter.

    getResultsRequest(reportId)
    

    getResultsResponse returns a statusCode and statusMsg. Call getResultsResponse in a loop until statusCode 3, “Report has completed successfully,” is returned.

  3. Request to get the report’s metadata by calling getMetaDataRequest.

    getMetaDataRequest(ReportId)
    

    getMetaDataResponse returns the following data.

    Parameter Description
    numberOfRows Total number of rows.
    numberOfPages Total number of pages in the report.
    pageSize Page size.
    numberOfColumns Total number of columns.
    dataName Name of each column.
    dataType Type of column data, for example, string.
  4. Request to get the report data by calling getDataRequest.

    getDataRequest(reportId,pageNum)
    
    Parameter Description
    reportId ID for this report returned by runReportRequest; reportId is valid for up to 120 days.
    pageNum Report page number containing data to be returned.

    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.

Manage report templates

Using the Reporting API, you can create, update, and delete report templates.

Create a report template

To create a report template, call createTemplateRequest with the following parameters.

createTemplateRequest(templateName,reportName,reportParams)
Parameter Description
templateName Name that you are giving to the report template.
reportName Standard report from which you are creating the report template.
reportParam(s) paramName and paramValue of each reportParam to be assigned a value.

The response to creating a report template returns a respCode and respMsg.

Update a report template

To update a report template, call the updateTemplateRequest with the following parameters.

updateTemplateRequest(templateName,reportParams)
Parameter Description
templateName Name given to the report template when it was created.
reportParam(s) paramName and paramValue of each reportParam to be assigned a value.

The response to updating a report template returns a respCode and respMsg.

Note: Updating a report template is not incremental. It only sets values for the parameters that are passed to updateTemplateRequest.

Delete a report template

To delete a report template, call deleteTemplateRequest, providing the templateName as the input parameter.

deleteTemplateRequest(templateName)

The response to deleting a report template returns a respCode and respMsg.

Using report templates

Report templates are run like any standard report. They can also be scheduled to run on a daily, weekly, or monthly basis. Report template schedules can be updated or deleted.

Run a report template

To run a report template and obtain the report template data:

  1. Call runReportRequest with the following parameters.

    runReportRequest(templateName,reportParams,pageSize)
    
    Parameter Description
    templateName Name given to the report template when it was created.
    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.
  2. Request to get the report’s metadata by calling getMetaDataRequest.

    getMetaDataRequest(ReportId)
    

    getMetaDataResponse returns the following data.

    Parameter Description
    numberOfRows Total number of rows.
    numberOfPages Total number of pages in the report.
    pageSize Page size.
    numberOfColumns Total number of columns.
    dataName Name of each column.
    dataType Type of column data, for example, string.
  3. Request to get the report data by calling getDataRequest.

    getDataRequest(reportId,pageNum)
    
    Parameter Description
    reportId ID for this report returned by runReportRequest; reportId is valid for up to 120 days.
    pageNum Report page number containing data to be returned.

    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.

Schedule a report template

You can schedule a report template to run on a daily, weekly, or monthly basis. The Reporting API includes functionality to create schedules and to get the results of a scheduled report template.

  1. Create a schedule for a report template, call createScheduleRequest with the following parameters.

    createScheduleRequest(scheduleName,templateName,schedule)
    
    Parameter Description
    scheduleName Name that you give to the schedule.
    templateName Name of the report template to be scheduled.
    schedule One of these values:
    • daily.
    • weekly. Select dayOfWeek value: Sunday, Monday, Tuesday, Wednesday, Thursday, Friday, or Saturday.
    • monthly. Specify dayOfMonth value as an integer from 1 to 31. If you specify 30 when the month is 28 days long, the value is corrected to 28.
    Note:The time of the day starts at midnight the previous night. The value daily, for example, means midnight the previous night to midnight tonight.
  2. To get the results of a scheduled report template that is run, call getScheduleRequest with scheduleName as a parameter.

    getScheduleRequest(schedulename)
    

    getScheduleResponse returns all the reportIds and execution dates of the reports that were run on the schedule.

  3. For each report, call getMetaDataRequest, passing in the reportId as a parameter, to get the information on how that report is formatted.

    getMetaDataRequest(ReportId)
    

    getMetaDataResponse returns the following data.

    Parameter Description
    numberOfRows Total number of rows.
    numberOfPages Total number of pages in the report.
    pageSize Page size.
    numberOfColumns Total number of columns.
    dataName Name of each column.
    dataType Type of column data, for example, string.
  4. Request to get the report data for each report that was run by calling getDataRequest.

    getDataRequest(reportId,pageNum)
    
    Parameter Description
    reportId ID for this report returned by runReportRequest; reportId is valid for up to 120 days.
    pageNum Report page number containing data to be returned.

    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.

Manage report template schedules

Using the Reporting API, you can update and delete report template schedules.

Update a schedule

To update a schedule, call the updateScheduleRequest with the following parameters.

updateScheduleRequest(scheduleName,templateName,schedule)
Parameter Description
scheduleName Name that you give to the schedule.
templateName Name of the report template to be scheduled.
schedule One of these values:
  • daily.
  • weekly. Select dayOfWeek value: Sunday, Monday, Tuesday, Wednesday, Thursday, Friday, or Saturday.
  • monthly. Specify dayOfMonth value as an integer from 1 to 31. If you specify 30 when the month is 28 days long, the value is corrected to 28.
Note:The time of the day starts at midnight the previous night. The value daily, for example, means midnight the previous night to midnight tonight.

The response to updating a schedule returns a respCode and respMsg.

Delete a schedule

To delete a schedule, call deleteScheduleRequest, providing the scheduleName as the input parameter.

deleteTemplateRequest(scheduleName)

The response to deleting a schedule returns a respCode and respMsg.

Performing API Searches

Using the Reporting API, you can search for transaction data by any of the following search names.

  • TransactionIDSearch
  • BatchIDSearch
  • AccountNumberSearch
  • CommentSearch
  • AccountNumberRefSearch
  • PurchaseOrderSearch
  • RecurringBillingProfileIDSearch
  • RecurringBillingProfileNameSearch
  • RecurringBillingAccountNumberSearch
  • RecurringBillingCommentSearch
  • RecurringBillingAmountSearch

To run a search request:

  1. Call runSearchRequest with the following parameters.

    runSearchRequest(searchName,reportParam(s),pageSize)
    
    searchName One of the search names listed above, for example, TransactionIDSearch.
    reportParam(s) paramName and paramValue of one or more input parameters for this search. See Report Parameters for the required and optional parameters.
    pageSize Number of rows of data per page. Default is 50.

The runSearchResponse object returns the reportId for this search and the statusCode and statusMsg. The reportId returned is valid for up to 120 days.

  1. Request to get the search metadata by calling getMetaDataRequest.

    getMetaDataRequest(ReportId)
    

    getMetaDataResponse returns the following data.

    Parameter Description
    numberOfRows Total number of rows.
    numberOfPages Total number of pages in the report.
    pageSize Page size.
    numberOfColumns Total number of columns.
    dataName Name of each column.
    dataType Type of column data, for example, string.
  2. Request to get the search data by calling getDataRequest.

    getDataRequest(reportId,pageNum)
    
    Parameter Description
    reportId ID for this report returned by runReportRequest; reportId is valid for up to 120 days.
    pageNum Report page number containing data to be returned.

    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.

Response and Status Codes

Response Codes

Response codes indicate the success or failure of a Reporting request. The table below describes the supported response codes and messages returned with each.

Response Code Response Message
100 Request has completed successfully
101 Request has failed
102 An internal scheduler error has occurred
103 Unknown report requested
104 Invalid Report ID
105 A system error has occurred
106 A database error has occurred
107 Invalid XML request
108 User authentication failed
109 Invalid report parameters provided
110 Invalid merchant account
111 Invalid page number
112 Template already exists
113 Unknown template requested

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.

Status Code Status Message
1 Report has been created
2 Report is currently executing
3 Report has completed successfully
4 Report has failed
5 Report has expired
6 Report has expired
Feedback