Chapter 1

Introduction

This chapter explains how to use CyberSource reports.

User Permissions

Available Reports

Report Formats

To download most of the reports described in this guide, you need to subscribe to them in the Business Center. All merchants are automatically subscribed to the Payment Submission Detail Report and the Transaction Exception Detail Report.

Reports are available in XML and CSV formats. You cannot receive a report in more than one format.

User Permissions

Administrators can subscribe to, configure, view, and download reports for all the merchant IDs that they control. If you are an administrator, control access to reports by creating users for each of your merchant IDs, and give each user the correct access rights. You must set the permissions for all the users in the User Administration and Role Administration sections of the Business Center (Figure 1). For instructions on setting the user permissions, see the online help.

This table describes the reports permissions available for users.

Figure 5

Figure 1 Sample User Administration Page

Available Reports

Each report shows your transactions for a single day. To view information for an entire week, month, or year, you must combine the daily reports.

Payment Batch Detail Report

Payment Submission Detail Report

Payment Events Report

Transaction Exception Detail Report

Single Transaction Report

User Management Report

Important The CSV version of the Payment Submission Detail Report uses quotation marks around each of the report’s values. The CSV versions of other reports do not use quotation marks around each value.

Payment Batch Detail Report

This report contains summary information about credit card, electronic check, bank transfer, and direct debit transactions.

Payment Submission Detail Report

This report is identical to the Payment Batch Detail Report with the following additions: The Payment Submission Detail Report includes additional payment types and values. The XML format has more additional payment types and values than for the CSV format.

Payment Events Report

This report contains information about payment events that occur after a transaction is sent to the payment processor.

Transaction Exception Detail Report

This report provides detailed information about transactions that were flagged by CyberSource or by the processor because of errors in requests for follow-on transactions. When these errors occur, you are notified in the Message Center. These notifications remain in the Message Center for seven days. The following figures show the Message Center and descriptions of transaction errors.

Single Transaction Report

This report contains summary information about credit card, electronic check, Bill Me Later, China processing, Boletos Bancários, and bank transfers for a single request ID.

Note For the Global Payment Services, this report covers errors in primary requests and follow-on requests.

Although you are automatically subscribed to this report, you can change the type of output between XML and CSV in the Report Subscription area of the Business Center.

Reporting Formats

The reported errors are available in three forms:

•   Daily report in XML (this page) or CSV (this page) format: You can view and download this report in the reports section of the Business Center. If you view the report in the Business Center and the report contains data, you can link directly to each transaction’s details page. Daily reports remain available for 6 months.

•   On-demand query (Requesting a Report With a Query API): You can request this kind of report at any time during the day. On-demand reports cover transactions that have taken place during the previous 24 hours.

•   Exception search: In the Transaction Search area of the Business Center, you can search for errors that might have occurred during a specific period of time, with a maximum of six months. These errors link to the transaction details page. With this feature, you can find and correct the errors before the daily report becomes available. For more information, see the online help.

Regardless of the format that you choose, the reported data remains available for six months.

Errors Reported

In all forms of the report, you are notified when follow-on transactions fail all processing attempts, which can occur even after you receive a success message in the API reply. Therefore, before accepting an order, you need to check this report to make sure no errors occurred for the transaction.

User Management Report

To see at a glance all the permissions and roles granted to users, users with the appropriate permission can download a daily report or use a query to request an on-demand user management report. The report is available in CSV or XML format. For example, this report in CSV format was run September 14, 2007. The report shows two enabled users:

•   The first user has a custom role with permissions for processing payment authorizations in the Virtual Terminal.

•   The second user has the report download role, which enables the user to download reports but not to log into the Business Center.

This figure shows the User Administration page with the download feature outlined in red.

CyberSource recommends that you immediately save the report on your computer. You can save the report by date if you are a merchant or by merchant ID if you are an administrator. By downloading the report regularly, you can easily keep track of the changes among your users and their permissions. You can obtain this report at any time.

For a complete description of the report, see User Management Report for the XML format or User Management Report for the CSV format.

Report Formats

Each report is available in one or more formats: PDF, CSV (comma-separated values), or XML (eXtensible Markup Language):

•   PDF is available for some of the pre-defined reports only. You can use Adobe Acrobat Reader® to view, save, or print PDF files. If Acrobat Reader is not installed on your computer, you can download it for free at Adobe Systems. The authorization and capture reports are available in PDF format.

•   CSV is a data format in which each column value is separated by a comma from the value in the next column, which allows you to transfer data from one application to another (such as Microsoft Excel), and each row starts a new line of data. For example, data taken from a database and represented in CSV format looks similar to this sample that contains the same information as the XML report above:

All reports are available in CSV format.

•   XML is designed especially for Web documents. With it, you can create your own tags so that you can interpret your data precisely and completely. This sample shows a sample report in XML format.

XML Conventions

To understand how a report in XML format is constructed, you need to be familiar with the syntax and the data types used for XML reports.

Report Declaration

The report is described as follows:

<?xml version="1.0" encoding="utf-8"?>

<!DOCTYPE Report SYSTEM URIreference>

<Report Name= CDATA

        Version=NMTOKEN

        xmlns=CDATA

        MerchantID=CDATA

        ReportStartDate=CDATA

        ReportEndDate=CDATA>

Note The value of URIreference is the same as that for xmlns. Whether you are operating in test or live mode, the namespace always refers to ebctest instead of ebc.

Element Declaration

Elements are described as follows:

<Sample Attribute=CDATA>

  (Element)

  (ChoiceOne) | (ChoiceTwo)

  (ComplexElement)

  (OptionalElement)?

  (RequiredRecurringElement)+

  (OptionalRecurringElement)*

</Sample>

Note In the DTDs, the ?, +, and * characters may be inside or outside the parentheses. Either syntax is acceptable.

CSV Conventions

CSV reports are described as follows:

•   The first and second records in the report describe the report format and indicate the dates included in the report.

•   If the value of a field contains a comma, the contents of the field are surrounded by double quotes ("). For example, the value A,B,C is represented by "A,B,C".

•   If the value of a field contains a double quote ("), the contents of the field are surrounded by double quotes, and the double quote is represented as two double quotes. For example, the value Sample "value" is represented by
"Sample ""value"""

•   Records are separated by a carriage return and a line feed.

Data Types and Lengths

These terms are used to refer to the data type of each field:

•   Amount: Amount includes a decimal point if necessary.

•   Boolean: Single character, such as T for true or F for false.

•   Date and time:

• Date: YYYY-MM-DD, with YYYY (four-digit year), MM (two-digit month), and DD (two-digit day).

• Time: <date>THH:MM:SS[+ | -]HH:MM where:

THH:MM:SS is the time, with HH (hours), MM (minutes), and SS (seconds).

[+ | -]HH:MM is the time zone’s offset from Greenwich Mean Time (GMT or UTC), with HH representing hours and MM representing minutes. The number is prefixed by either a plus (+) or minus (-) to indicate whether the offset adds to or subtracts from UTC. For example, the offset for Pacific Daylight Time is -07:00.

Example 2009-04-13T07:00:00-07:00 represents April 4, 2009 at 7 AM PDT.

•   Numeric: string containing numbers.

•   String: Letters, numbers, and special characters (for example, @, #, and %). All text uses UTF-8 character encoding.

Data lengths indicate the maximum length of each field. Fields shorter than the maximum length are not padded.