|
|
|
|
|
|
This chapter explains how to download CyberSource reports.
Requesting a Report With a Client Application
Requesting a Report With a Query API
Requesting a Report With a Client Application
The client uses a GET method and does not use search parameters. For the Single transaction report, you can obtain the complete daily report in XML or CSV format as follows:
• XML: Because you cannot specify a DTD version, the most current report version is used.
• CSV: The basic report version is used.
Client Application Requirements
To connect to the report server, your client application must support HTTPS connections. An HTTPS connection is similar to an HTTP connection, but it is encrypted by using Secure Sockets Layer (SSL). Your client application must support HTTP/1.0 or HTTP/1.1 and SSL v2 or SSL v3 connections.
HTTPS libraries are available for many programming languages, including Java, C/C++, Perl, and Visual Basic. You can implement a client in any language that allows you to use HTTPS to communicate with the report server.
Your client application must use Basic Access Authentication to send the user name and password. Many HTTPS client libraries implement this authentication method. For information about Basic Access Authentication, see http://www.ietf.org/rfc/rfc2617.txt.
Important Although you may be able to use a third-party client application to download CyberSource reports, CyberSource does not recommend or support third-party client applications or client libraries that may interfere with CyberSource applications.
You can use the information in this guide to write applications that process these reports automatically.
Format Requirements
This section describes the appropriate format for a request and a reply.
Request Format
To request a report, your client application must send an HTTP GET message to the report server. The URL that you specify in your message indicates which report you want to download. Format the URL as follows:
https://<server_name>/DownloadReport/YYYY/MM/DD/<merchant_ID>/<report_name>.<report_format>
For example, if your merchant ID were sample, you would use the following URL to download the XML version of the August 1, 2009 Payment Events Report from the production system:
https://ebc.cybersource.com/ebc/DownloadReport/2009/08/01/sample/PaymentEventsReport.xml
Table 3 describes each value in the URL.
|
Value |
Description |
|---|---|
|
<server_name> |
Name of the server from which to download the report. Use one of these values: • Test server: ebctest.cybersource.com/ebctest • Production server: ebc.cybersource.com/ebc • Test reports server: downloadreportstest.cybersource.com • Production reports server: downloadreports.cybersource.com |
|
YYYY |
Four-digit year |
|
MM |
Two-digit month. For example, use 08 for August. |
|
DD |
Two-digit day. For example, use 01 for the first day of the month. |
|
<merchant_id> |
CyberSource merchant ID |
|
<report_name> |
Name of the report to download. Use one of these values: • PaymentBatchDetailReport • PaymentSubmissionDetailReport • PaymentEventsReport • TransactionExceptionDetailReport |
|
<report_format> |
Report format to download. Use one of these values: • csv: Comma-separated values • xml: Extensible Markup Language |
You can add Basic Access Authentication parameters to the URL as follows:
https://<username>:<password>@<server_name>/DownloadReport/YYYY/MM/DD/<merchant_ID>/<report_name>.<report_format>
Reply Format
If the request is successful, the server responds by sending an HTTPS reply message. The body of this message contains the report that you requested.
Note You cannot receive the Payment Batch Detail Report in both XML and CSV formats.
For information about report formats, see Chapter 3, XML Reports and Chapter 4, CSV Reports. For information about configuring your reports, see the online help.
If the request fails, the server sends an HTTP reply message that describes the error. Use this information to determine why the request failed and to debug your client application.
Requesting a Report With a Query API
The query uses a POST method with search parameters. As with the client application, this application uses Basic Access Authentication to send the user name and password. You can request these reports:
On-Demand Transaction Exception Detail Report
On-Demand Single Transaction Report
On-Demand User Management Report
On-Demand Transaction Exception Detail Report
Note In the Transaction Search area of the Business Center, you can search for errors that might have happened during a specific period of time, for 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.
The On-Demand Transaction Exception Detail Report is identical to the daily report except in the time of delivery and in the method used for obtaining the report. The reported data remains available for six months.
The query can be automated by a computer or viewed by a human. Although you can request this report as many times as you wish during the day, each time you will see only the errors that occurred after midnight Pacific time. The errors that occurred earlier appear in the daily version of the report.
The result of a query can include up to 2000 transactions. If your query results cover more than 2000 transactions, the report shows transactions from the start time until the limit is reached. If the report contains no errors, you receive an empty report. You are responsible for making sure that transactions are counted only once.
Formulating the Query
The requested interval cannot exceed 24 hours and you must use the UTC time format, which is indicated in the report as Pacific time. For example, when you set the time interval from 07:00:00 to 07:00:00, your search results will be identical to the daily report, which covers midnight to midnight Pacific time. To request the report, send the required data described in Table 4 to one of these URLs:
|
Production |
https://ebc.cybersource.com/ebc/TransactionExceptionDetailReportRequest.do |
|
Test |
https://ebctest.cybersource.com/ebctest/TransactionExceptionDetailReportRequest.do |
XML format
To use the XML format, write a program that can send the required fields in a POST request.
HTML format
To use the HTML format, write an HTML form with one of the URLs listed above. The following sample shows the form tag with the action to send a report request to the production URL. The form includes the required fields and a Submit button.
|
<form action="https://ebc.cybersource.com/ebc/TransactionExceptionDetailReportRequest.do" method="post"> <table> <tr><td>MerchantID</td><td> <input type="text" name="merchantID"></td></tr> <tr><td>UserName </td><td> <input type="text" name="username"></td></tr> <tr><td>Password </td><td> <input type="text" name="password"></td></tr> <tr><td>StartDate </td><td> <input type="text" name="startDate"></td></tr> <tr><td>StartTime </td><td> <input type="text" name="startTime"></td></tr> <tr><td>EndDate </td><td> <input type="text" name="endDate"></td></tr> <tr><td>EndTime </td><td> <input type="text" name="endTime"></td></tr> <tr><td>ReportFormat</td><td> <input type="text" name="format"></td></tr> </table> <input type="submit" value="Submit"> </form> |
Viewing and Saving the Report
After sending a request, you receive a response immediately. The report contains all the transactions with data errors that occurred during the requested time period. If no orders contained errors, the report is empty.
XML format
If the query is successful, the results appear as a document of mime type application/xml. To use this report, write a program to save or process the XML data in the report.
HTML format
If you use a browser that supports XSLT, such as Microsoft Internet Explorer 6.0+ or Firefox 2.0, the XML file that you receive can be converted to HTML and formatted into a table that you can see in your browser. Save the report as follows:
1 Right-click the report.
2 Select View Source.
If you do not save the source, only the URL for the request is saved. The report appears in your default text editor.
3 Save the text file as an XML file.
The table representation is restored when you view the report again in the browser.
Interpreting Result Messages
All requests return the status code 200. If a system error occurs, you receive the HTTP error code 503 (Service unavailable). If your query contains an error, the body mime type is text/plain and the body of the message contains one of these errors:
|
Error |
Message |
|
Incorrect merchant ID user name, or password |
Invalid login credentials |
|
Incorrect date or time |
Invalid date/time range |
|
Format |
Invalid format |
|
Other error |
The server is busy |
Sample Report
Empty fields are represented slightly differently between the daily and the on-demand XML versions of the report: in the daily report, empty fields are shown in the format <PaymentMethod/> whereas in the on-demand report, they are shown in the format <PaymentMethod></PaymentMethod>.
For a sample report, see Transaction Exception Detail Report. The DTD is in Appendix A Transaction Exception Detail Report.
On-Demand Single Transaction Report
The query uses a POST method with search parameters to obtain the details of a single transaction. The content of the report is described on this page, the DTDs on this page, and the samples on this page.
Formulating the Query
You can request this report as many times as you wish each day. Table 5 describes the request information.
|
Parameter |
Value |
|
Required/Optional |
|---|---|---|---|
|
merchantID |
Your CyberSource ID |
Required |
|
|
type |
transaction |
Required |
|
|
subtype |
transactionDetail |
Required |
|
|
requestID |
Number of the transaction that you want to see |
Required |
|
|
includeExtendedDetail |
This field is optional and is used to determine the status of a capture request and its associated system-generated authorization for split shipment transactions. This field can contain one of these values: • Predecessor: For follow-on capture requests, this includes details of the capture and the system-generated authorization. • Related: This includes the details of the capture request, the system-generated authorization, and any related transactions, such as original auth and capture. Note This element is included only in versions 1.3 and greater. For more information on split shipment, see Credit Card Services Implementation Guide. |
Optional |
|
|
versionNumber |
Version number that contains the information that you want. Each higher version contains all the elements and attributes of the lower version in addition to the elements and attributes introduced in the new version. If your report does not contain the data specific to the version, the elements and attributes specific to that version do not appear in your report. Note Although you can specify any of the versions, versions 1.4 and 1.5 are specific to the on-demand Single Transaction Report With a Query API whereas all other versions are specific to the daily report. If you do not specify a version, version 1.1 is used. |
Optional |
|
|
|
1.7 |
BalanceAmount, BalanceCurrencyCode, RequestedAmount, RequestedAmountCurrencyCode |
|
|
|
1.6 |
BinAccountType, BinCountry, BinIssuer, BinScheme, GrandTotal, InfoCodes, IPCity, IPCountry, IPRoutingMethod, IPState, TravelData |
|
|
|
1.5 |
ACHVerificationResult, ACHVerificationResultMapped |
|
|
|
1.4 |
BoletoNumber, NumberOfInstallments |
|
|
|
1.3 |
PredecessorRequestID, User, includeExtendedDetail |
|
|
|
1.2 |
EventType, TransactionReferenceNumber |
|
|
|
1.1 |
Default version |
|
Send the information in the preceding table to one of these URLs:
|
Production Test |
https://ebc.cybersource.com/ebc/Query https://ebctest.cybersource.com/ebctest/Query |
XML format
To use the XML format, write a program that can send the required fields in a POST request.
HTML format
To use the HTML format, write an HTML form that uses one of the above URLs. The sample below shows the form tag with the action attribute to send a query request to the production URL. The form includes the required fields and a Submit button.
|
<form action="https://ebc.cybersource.com/ebc/Query" method="POST"> <table> <tr> <td>merchantID</td> <td><input type="text" name="merchantID" value="example"></td> </tr> <tr> <td>type</td> <td><input type="text" name="type" value="transaction"></td> |
|
</tr> <tr> <td>subtype</td> <td><input type="text" name="subtype" value="transactionDetail"></td> </tr> <tr> <td>requestID</td> <td><input type="text" name="requestID" value="1613857572210138565732"></td> </tr> <tr> <td>versionNumber</td> <td><input type="text" name="versionNumber" value="1.5"></td> </tr> <tr> <td></td> <td><input type="reset"> <input type="submit" value="Submit"></input></td> </tr> </table> </form> |
Viewing and Saving the Report
You receive a response immediately.
XML format
If the query is successful, the results appear as a document of mime type application/xml. To use this report, write a program to save or process the XML data in the report.
|
<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE Report SYSTEM "https://ebctest.cybersource.com/ebctest/reports/dtd/tdr_1_5.dtd"> <Report xmlns="https://ebctest.cybersource.com/ebctest/reports/dtd/tdr_1_5.dtd" Name="Transaction Detail" Version="1.5" MerchantID="example" ReportStartDate="2009-08-20T04:22:37-11:00" ReportEndDate="2009-08-20T04:22:37-11:00"> <Requests> <Request> Complete details of a single transaction here </Request> </Requests> </Report> |
HTML format
The XML file that you receive is converted to HTML and formatted into a table that you can see in any browser that supports XSLT, such as Microsoft Internet Explorer 6.0 or Mozilla Firefox 3. Save the report as follows:
1 Right-click the report.
2 Select View Source.
If you do not save the source, only the URL for the request will be saved. The report appears in Notepad or in your default text editor.
3 Save the text file as an XML file.
The table representation is restored when you view the report again in the browser.
Interpreting Result Messages
All requests return the status code 200. If your query contains an error, the body mime type is text/plain and the body of the message contains one of these errors:
|
Error |
Message |
|---|---|
|
400 |
Please check the username and password Missing input parameter: type Missing input parameter: merchantID Invalid input parameter: type or subtype |
|
401 |
Requires authentication |
|
403 |
You are not authorized to access it |
|
500 |
Invalid Missing input data Unable to find the request System error. Please try again later |
|
501 |
GET is not supported by this URL |
On-Demand User Management Report
The query uses a POST method with search parameters to obtain the list of your users and their permissions. A report applies only to users in production, not to those in the test environment.
Formulating the Query
You can request this report at any time. This table describes the request information.
|
Parameter |
Field Name |
Format |
|---|---|---|
|
Merchant ID |
merchantID |
Merchant or account ID used to access the Business Center. |
|
User name |
username |
Name used to access the Business Center. This field can be different from the merchant ID. If this field is empty, the value of merchantID is used to generate the report. Important To use this field, the user name must have the User Management permission. |
|
Password |
password |
Password associated with the user name. |
|
Users to be reported |
reportMerchantID |
Value that determines which users can be included in the report. This optional field can contain one of these values: • all: Default value if the field is empty. • Account ID (example: sampleMerchant_acct) • Account user (example: sampleMerchant_admin) • Merchant ID (example: sampleMerchant) • Merchant user (example: sampleMerchant) Table 7 shows how to use the preceding values with the merchant ID and user name. |
|
Report format |
format |
xml | csv |
|
merchantID |
username |
reportMerchantID |
Content of the Report |
|---|---|---|---|
|
Account Level |
|
|
|
|
sampleMerchant_acct |
sampleMerchant_admin |
all |
All account users for sampleMerchant_acct and its merchant users |
|
sampleMerchant_acct |
All account users for sampleMerchant_acct |
||
|
sampleMerchant |
All merchant users for sampleMerchant |
||
|
Merchant Level |
|
|
|
|
sampleMerchant |
sampleMerchant |
all |
All merchant users for sampleMerchant |
|
sampleMerchant_acct |
Not allowed |
||
|
sampleMerchant |
All merchant users for sampleMerchant |
Send the information in Table 6 to one of these URLs:
|
Production Test |
https://ebc.cybersource.com/ebc/UserListing https://ebctest.cybersource.com/ebctest/UserListing |
XML format
To use the XML format, write a program that can send the required fields in a POST request.
HTML format
To use the HTML format, write an HTML form that uses one of the previous URLs. The following sample shows the form tag with the action attribute to send a query request to the production URL. The form includes the required fields and a Submit button.
|
<form action="https://ebc.cybersource.com/ebc/UserListing" method="POST"> <table> <tr> <td>merchantID</td> <td><input type="text" name="merchantID" value="example"></td> </tr> <tr> <td>username</td> <td><input type="text" name="username" value="userlisting"></td> </tr> <tr> <td>password</td> <td><input type="text" name="password" value="securepassword"></td> </tr> <tr> <td>format</td> <td><input type="text" name="format" value="csv"></td> </tr> <tr> <td></td> <td><input type="reset"> <input type="submit" value="Submit"></input></td> </tr> </table> </form> |
Interpreting Result Messages
All requests return the status code 200. If your query contains an error, the body mime type is text/plain and the body of the message contains one of these errors:
|
Error |
Message |
|---|---|
|
400 |
Please check the username and password Missing input parameter: type Missing input parameter: merchantID Invalid input parameter: type or subtype |
|
401 |
Invalid user |
|
403 |
You are not authorized to access it |
|
405 |
Request method not allowed |
|
500 |
Invalid Missing input data Unable to find the request System error. Please try again later. |
|
501 |
GET is not supported by this URL |
Viewing and Saving the Report
After sending a request, you receive a response immediately.
XML format
If the query is successful, the results appear as a document of mime type application/xml. To use this report, write a program to save or process the XML data in the report.
|
<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE Report SYSTEM "https://ebc.cybersource.com/ebc/reports/dtd/ul.dtd"> <Report Name="User Listing" Version="1.0" xmlns="https://ebc.cybersource.com/ebc/reports/dtd/ul.dtd" ReportDate="2007-09-21 05:31 GMT"> <Users> <User username="infodev_user" merchantid="infodev" firstname="Jane" lastname="Doe" email="" datecreated="2007-03-29 07:47 GMT" lastaccess="2007-09-21 04:26 GMT" status="Enabled" role="Custom"> <Permissions> </Permissions> </User> </Users> </Report> |
HTML format
If you use a browser that supports XSLT, such as Microsoft Internet Explorer 6.0 or Firefox 2.0, you can convert the XML file that you receive to HTML and format the HTML into a table that you can see in your browser. Save the report as follows:
1 Right-click the report.
2 Select View Source or Save Target As.
If you do not save the source, only the URL for the request will be saved. The report appears in your default text editor.
3 Save the text file as an XML file.
The table representation is restored when you view the report again in the browser.
|
|
|
|
|
|