Creating Requests With a Client Application

The client uses GET, POST, and PUT methods to send requests to the server. To send the request, you must include an authorization token in the header and specify the format for the report that you want to download.

Request Format

To create a request, you must send an HTTP message to the report server with your client application. The URL and method that you specify in your message indicates which function you are requesting and the parameters of the request. Partners can specify the organization ID, which enables them to create requests that return data for a specific merchant. For example, to download a report, you would format the URL as follows:

https://<url_prefix>/reporting/v3/report-downloads?organizationId={organizationId}&download=true&reportDate={date}&reportName={reportName}

If the

organizationId

field value is

SampleMerchant

, you would use the following URL to download the report from February 20, 2018, titled SampleDailyReport from the production system:

https://<url_prefix>/reporting/v3/report-downloads?organizationId=SampleMerchant&reportDate=20180220&reportName=SampleDailyReport

IMPORTANT

Pass the

organizationId

field in the request only if you are a partner creating a request to retrieve data for a specific merchant. Otherwise, the

organizationId

field is passed in your authentication method and not required in the request.

Client Application Requirements

To connect to the report server, your client application must support HTTPS encrypted by using Transport Layer Security (TLS). Your client application must support HTTP/1.1 and TLS 1.2 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.

IMPORTANT

Although you may be able to use a third-party client application to download the reports, we do not recommend or support third-party client applications or client libraries that may interfere with our applications.

Request Header

The default format for responses is JSON, but some reports can also return CSV or XML. You can set the response to return CSV or XML in the request header by setting the

Accept

value to either

application/xml

or

text/csv

. The report format can be set for the following reports:

Conversion Detail

Purchase and Refund Detail

Reporting API

Viewing Report Definitions

You can view a list of supported reports and their attributes before subscribing to them. You can also view the attributes of an individual report type.

For a summary of all reports, the request format is:

GET https://<url_prefix>/reporting/v3/report-definitions?organizationId={organizationId}

Summary Report Definition URL Values
Value	Description	Required/ Optional
< `url_prefix`>	Name of the server from which to download the report. Use one of these values: Production : api.cybersource.com Production in India : api.in.cybersource.com Test : apitest.cybersource.com	Required
`{organizationId}`	The organization ID under which the report is subscribed. This can be the merchant ID, account ID, or reseller ID.	Optional

For a summary of a single report type, the request format is:

GET https://<url_prefix>/reporting/v3/report-definitions/{reportDefinitionName}?organizationId={organizationId}&download=true

Single Report Definition URL Values
Value	Description	Required/ Optional
`< url_prefix>`	Name of the server from which to download the report. Use one of these values: Test: `apitest.cybersource.com` Production: `api.cybersource.com` Production in India: api.in.cybersource.com	Required
`{reportDefinitionName}`	Name of the report type you want to review. The options are: `TransactionRequestClass`: Transaction Request Report `PaymentBatchDetailClass`: Payment Batch Detail Report `ExceptionDetailClass`: Transaction Exception Detail Report `ProcessorSettlementDetailClass`: Processor Settlement Detail Report `ProcessorEventsDetailClass`: Processor Events Detail Report `FundingDetailClass`: Funding Detail Report `AgingDetailClass`: Aging Detail Report `ChargebackAndRetrievalDetailClass`: Chargeback And Retrieval Detail Report `DepositDetailClass`: Deposit Detail Report `FeeDetailClass`: Fee Detail Report `InvoiceSummaryClass`: Invoice Summary Report `PayerAuthDetailClass`: Payer Authentication Detail Report `ConversionDetailClass`: Conversion Detail Report `SubscriptionDetailClass`: Subscription Detail Report `JPTransactionDetailClass`: JP Transaction Detail Report `ServiceFeeDetailClass`: Service Fee Detail Report `GatewayTransactionRequestClass`: Gateway Transaction Request Report `DecisionManagerEventDetailClass`: `Decision Manager` Event Detail Report `RecurringBillingDetailClass`: Recurring Billing Details Report	Required
`{organizationId}`	The organization ID under which the report is subscribed. This can be the merchant ID, account ID, or reseller ID.	Optional

Responses

This call can return one of the following HTTP status codes:

200: Ok.

400: Invalid request.

404: Report not found.

For detailed information on the responses, including which fields are returned, see the Reporting REST API Reference .

Reporting API

Managing Report Subscriptions

The API enables you to view the details of a single report subscription and a list of all report subscriptions. You can also create, edit, and delete report subscriptions.

Reporting API

Retrieving Available Reports

Using the API, you can retrieve a list of reports that are generated and available for download. The request format is:

https://<url_prefix>/reporting/v3/reports?startTime={startTime}&endTime={endTime}?timeQueryType={timeQueryType}

Create/Update Report Subscription Request URL Values
Value	Description	Required/Optional
<`url_prefix`>	Name of the server from which to download the report. Use one of these values: Test: `apitest.cybersource.com` Production: `api.cybersource.com` Production in India: api.in.cybersource.com	Required
`{organizationId}`	The organization ID under which the report is subscribed. This can be the merchant ID, account ID, or reseller ID.	Optional
`{startTime}`	Report start date to search on in ISO 8601 format. Example : 2016-11-22T12:00:00.000Z	Required
`{endTime}`	Report end date to search on in ISO 8601 format. Example : 2016-11-22T12:00:00.000Z	Required
`{timeQueryType}`	Time you would like to search. Valid values: reportTimeFrame executedTime	Required
`{reportMimeType}`	Format of the report. Valid values are: application/xml text/csv	Optional
`{reportFrequency}`	Frequency of the report subscription. The options are: Daily Weekly Monthly Adhoc	Optional
`{reportName}`	Unique name of the report.	Optional
`{reportDefinitionId}`	Report definition ID.	Optional
`{reportStatus}`	Status of the report. The options are: COMPLETED PENDING QUEUED RUNNING ERROR NO_DATA	Optional

Responses

This call can return one of the following HTTP status codes:

200: Ok.

400: Invalid request.

404: Report not found or there are no available transactions.

For detailed information on the responses, including which fields are returned, see the Reporting REST API Reference .

Reporting API

Downloading Reports

You can use the Reporting API to download completed reports. For information about creating reports, see the Business Center Reporting User Guide
. You cannot receive a report in more than one format.

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://<url_prefix>/reporting/v3/report-downloads&organizationId={organizationId}&reportDate={date}&reportName={reportName}

For example, if your organization ID were

SampleMerchant

, you would use the following URL to download the XML version of the February 20, 2017, which is named Sample Daily Report:

https://<url_prefix>/reporting/v3/report-downloads&organizationId=SampleMerchant&reportDate=20170220&reportName=SampleDailyReport

Report Download URL Values
Value	Description	Required/ Optional
<`url_prefix`>	Name of the server from which to download the report. Use one of these values: Test: `apitest.cybersource.com` Production: `api.cybersource.com` Production in India: api.in.cybersource.com	Required
`{organizationId}`	The organization ID under which the report is subscribed. This can be the merchant ID, account ID, or reseller ID.	Optional
`{reportName}`	Unique name of the report subscription you want to create or edit.	Required
`{reportDate}`	The date of the report. For reports that span multiple days, this value would be the end date of the report. Format: YYYY-MM-DD	Required

You can also download reports based on the report ID. To find out the report ID for a report, perform a report search as described in Retrieving Available Reports and find the report ID value you want to search for in the response. Format the URL as follows:

https://<url_prefix>/reporting/v3/reports/{reportId}&organizationId={organizationId}

Report Download by Report ID URL Values
Value	Description
<`url_prefix`>	Name of the server from which to download the report. Use one of these values: Test: `apitest.cybersource.com` Production: `api.cybersource.com` Production in India: api.in.cybersource.com
`{reportId}`	Report ID.
`{organizationId}`	The organization ID under which the report is subscribed. This can be the merchant ID, account ID, or reseller ID.

Responses

This call can return one of the following HTTP status codes:

200: Ok.

400: Invalid request.

404: Report not found or there are no available transactions.

For detailed information on the responses, including which fields are returned, see the Reporting REST API Reference .

Reporting API

Creating a One-Time Report

To create a one-time report, your client application must send an HTTP POST request to the report server. The request body contains the details for creating the report, such as the report type, the start time, and the frequency. The format of the URL is as follows:

PUT https://<url_prefix>/reporting/v3/reports

The request body would be:

{
                "organizationId": "myorg",
                "reportName": "DailyTransactions",
                "reportDefinitionName": "TransactionDetailClass",
                "reportFields": [
                    "Request.RequestID",
                    "Request.TransactionDate",
                    "Request.MerchantID",
                    "BillTo.FirstName",
                    "BillTo.LastName",
                    "BillTo.City",],
                "startTime": "1100",
                "reportMimeType": "application/xml,
                "reportFrequency": "DAILY",
                "timezone": "GMT",
                "startTime": "0900",
                "startDay": "1"
                }

Create One-Time Report URL Values
Value	Description
<`url_prefix`>	Name of the server from which to download the report. Use one of these values: Test: `apitest.cybersource.com` Production: `api.cybersource.com` Production in India: api.in.cybersource.com

Create/Update Report Subscription Request Body Values
Value	Description	Required/ Optional
`organizationId`	The organization ID under which the report is subscribed. This can be the merchant ID, account ID, or reseller ID.	Optional
`reportDefinitionName`	Name of the report type you want to review. The options are: `TransactionRequestClass`: Transaction Request Report `PaymentBatchDetailClass`: Payment Batch Detail Report `ExceptionDetailClass`: Transaction Exception Detail Report `ProcessorSettlementDetailClass`: Processor Settlement Detail Report `ProcessorEventsDetailClass`: Processor Events Detail Report `FundingDetailClass`: Funding Detail Report `AgingDetailClass`: Aging Detail Report `ChargebackAndRetrievalDetailClass`: Chargeback And Retrieval Detail Report `DepositDetailClass`: Deposit Detail Report `FeeDetailClass`: Fee Detail Report `InvoiceSummaryClass`: Invoice Summary Report `PayerAuthDetailClass`: Payer Authentication Detail Report `ConversionDetailClass`: Conversion Detail Report `SubscriptionDetailClass`: Subscription Detail Report `JPTransactionDetailClass`: JP Transaction Detail Report `ServiceFeeDetailClass`: Service Fee Detail Report `GatewayTransactionRequestClass`: Gateway Transaction Request Report `DecisionManagerEventDetailClass`: `Decision Manager` Event Detail Report `RecurringBillingDetailClass`: Recurring Billing Details Report	Required
`reportFields`	Array of field names which should be included in the report. For a list of available fields, see Reporting Fields and Descriptions	Required
`reportMimeType`	Format of the report. Valid values are: application/xml text/csv	Optional
`reportName`	Unique name of the report subscription you want to create or edit.	Required
`timeZone`	Merchant’s time zone. For a list of supported time zones, see Supported Time Zones. Example: America/Chicago	Optional
`startTime`	Time of day the report will run. Format: HHMM	Optional
`startDay`	Day of month (1-31) the report will run for monthly reports.	Optional
`reportFilters`	Array that contains additional filters.	Optional
`reportPreferences.signed Amounts`	Indicator that determines whether or not a negative sign is used for the amount of all refunded transactions. Valid values: true false	Optional
`reportPreferences.fieldName Convention`	Specify the field naming convention to be followed in reports (applicable only to csv report formats). Valid values: SOAPI SCMP	Optional
`selectedMerchantGroupName`	Name of the merchant group.	Optional

Responses

This call can return one of the following HTTP status codes:

200: Ok.

304: Not modified.

404: Report not found or no transactions are available.

For detailed information on the responses, including which fields are returned, see the Reporting REST API Reference .

Reporting API

Downloading On-Demand Conversion Detail Report

The Conversion Detail Report contains details of transactions for a merchant. To request the report, your client application must send an HTTP GET message to the report server. The default format for responses is JSON, but some reports can also return CSV or XML. You can set the response to return CSV or XML in the request header by setting the

Accept

value to either

application/xml

or

text/csv

.

Format the URL as follows:

https://<url_prefix>/reporting/v3/conversion-details?startTime={startTime}&endTime={endTime}&organizationId={organizationId}

On-Demand Conversion Detail Report URL Values
Value	Description	Required/ Optional
< `url_prefix`>	Name of the server from which to download the report. Use one of these values: Test: `apitest.cybersource.com` Production: `api.cybersource.com` Production in India: api.in.cybersource.com	Required
`{startTime}`	Report start date to search on in ISO 8601 format. Example: 2016-11-22T12:00:00.000Z	Required
`{endTime}`	Report end date to search on in ISO 8601 format. Example: 2016-11-22T12:00:00.000Z	Required
`{organizationId}`	The organization ID under which the report is subscribed. This can be the merchant ID, account ID, or reseller ID.	Optional

Responses

This call can return one of the following HTTP status codes:

200: Ok.

400: Invalid request.

404: Report not found or no transactions are available.

For detailed information on the responses, including which fields are returned, see the Reporting REST API Reference .

Reporting API

Downloading On-Demand Notification of Change Report

The Notification of Change Report contains a list of eCheck-related values updated as a result of a response to an eCheck settlement transaction. To request the report, your client application must send an HTTP GET message to the report server. Format the URL as follows:

https://<url_prefix>/reporting/v3/notification-of-changes?startTime={startTime}&endTime={endTime}

On-Demand Notification of Change Report URL Values
Value	Description	Required/Optional
< `url_prefix`>	Name of the server from which to download the report. Use one of these values: Test: `apitest.cybersource.com` Production: `api.cybersource.com` Production in India: api.in.cybersource.com	Required
`{startTime}`	Report start date to search on in ISO 8601 format. Example: 2016-11-22T12:00:00.000Z	Required
`{endTime}`	Report end date to search on in ISO 8601 format. Example: 2016-11-22T12:00:00.000Z	Required

Responses

This call can return one of the following HTTP status codes:

200: Ok.

400: Invalid request.

401: Unauthorized. The provided token is no longer valid.

404: Report not found or no transactions are available.

500: Internal server error.

For detailed information on the responses, including which fields are returned, see the Reporting REST API Reference .

Reporting API

Downloading On-Demand Purchase and Refund Detail Report

The Purchase and Refund Detail Report contains purchase and refund details that have been submitted to your payment processor. Merchants using certain payment processors will also see fee and funding data. To request the report, your client application must send an HTTP GET message to the report server. The default format for responses is JSON, but some reports can also return CSV or XML. You can set the response to return CSV or XML in the request header by setting the

Accept

value to either

application/xml

or

text/csv

.

Format the URL as follows:

https://<url_prefix>/reporting/v3/purchase-refund-details&startTime={startTime}&endTime={endTime}

On-Demand Purchase and Refund Detail Report URL Values
Value	Description	Required/ Optional
< `url_prefix`>	Name of the server from which to download the report. Use one of these values: Test: `apitest.cybersource.com` Production: `api.cybersource.com` Production in India: api.in.cybersource.com	Required
`{startTime}`	Report start date to search on in ISO 8601 format. Example: 2016-11-22T12:00:00.000Z	Required
`{endTime}`	Report end date to search on in ISO 8601 format. Example: 2016-11-22T12:00:00.000Z	Required
`{organizationId}`	The organization ID under which the report is subscribed. This can be the merchant ID, account ID, or reseller ID.	Optional
`{paymentSubtype}`	Payment subtypes. The default value is ALL . Valid values: ALL: All Payment Subtypes VI: Visa MC: Mastercard AX: American Express DI: Discover DP: PINless Debit	Optional
`{viewBy}`	View results by request date or submission date. The default value is requestDate . Valid values: requestDate: Request Date submissionDate: Submission Date	Optional
`{groupName}`	Group name, which is defined in the Group Management Module in the `Business Center`.	Optional
`{offset}`	Controls the starting point within the collection of results, which defaults to 0. The first item in the collection is retrieved by setting a zero offset. For example, if you have a collection of 15 items to be retrieved from a resource and you specify limit=5, you can retrieve the entire set of results in 3 successive requests by varying the offset value: offset=0 , offset=5 , and offset=10 . If an offset larger than the number of results is provided, this will result in no embedded object being returned.	Optional
`{limit}`	Controls the maximum number of items that may be returned for a single request. The default is 2000.	Optional

Responses

This call can return one of the following HTTP status codes:

200: Ok.

400: Invalid request.

401: Unauthorized. The provided token is no longer valid.

404: Report not found or no transactions are available.

500: Internal server error.

For detailed information on the responses, including which fields are returned, see the Reporting REST API Reference .

Reporting API

Downloading On-Demand Net Funding Report

The Net Funding report contains the daily interchange, discount, and standard assessments. Some month-end fees, such as authorizations, are detected at the end of the month and appear in the Net Funding report on that particular day. Total Net Funding is obtained after subtracting chargebacks, fees, and any other negative amounts. To request the report, your client application must send an HTTP GET message to the report server. Format the URL as follows:

https://<url_prefix>/reporting/v3/net-fundings&startTime={startTime}&endTime={endTime}

On-Demand Net Funding Report URL Values
Value	Description	Required/ Optional
< `url_prefix`>	Name of the server from which to download the report. Use one of these values: Test: `apitest.cybersource.com` Production: `api.cybersource.com` Production in India: api.in.cybersource.com	Required
`{startTime}`	Report start date to search on in ISO 8601 format. Example: 2016-11-22T12:00:00.000Z	Required
`{endTime}`	Report end date to search on in ISO 8601 format. Example: 2016-11-22T12:00:00.000Z	Required
`{organizationId}`	The organization ID under which the report is subscribed. This can be the merchant ID, account ID, or reseller ID.	Optional
`{groupName}`	Group name, which is defined in the Group Management Module in the `Business Center`.	Optional

Responses

This call can return one of the following HTTP status codes:

200: Ok.

400: Invalid request.

401: Unauthorized. The provided token is no longer valid.

404: Report not found or no transactions are available.

500: Internal server error.

For detailed information on the responses, including which fields are returned, see the Reporting REST API Reference .

Reporting API

Downloading Payment Batch Summary Report

The Payment Batch Summary report shows total sales and refunds by currency and payment method. To request the report, your client application must send an HTTP GET message to the report server. Format the URL as follows:

https://<url_prefix>/reporting/v3/payment-batch-summaries&startTime={startTime}&endTime={endTime}

On-Demand Net Funding Report URL Values
Value	Description	Required/ Optional
< `url_prefix`>	Name of the server from which to download the report. Use one of these values: Test: `apitest.cybersource.com` Production: `api.cybersource.com` Production in India: api.in.cybersource.com	Required
`{startTime}`	Report start date to search on in ISO 8601 format (yyyy-MM-dd'T'HH:mm:ss.SSSZ). Example: 2019-05-01T12:00:00-05:00	Required
`{endTime}`	Report end date to search on in ISO 8601 format (yyyy-MM-dd'T'HH:mm:ss.SSSZ). Example: 2019-08-30T12:00:00-05:00	Required
`{organizationId}`	The organization ID under which the report is subscribed. This can be the merchant ID, account ID, or reseller ID.	Optional
`{rollUp}`	Specifies whether to present data in spans of a single day, week, or month. The options are: `day` `week` `month`	Conditional. Required when requesting breakdown data for a merchant.
`{breakdown}`	Used to request data at the parent-level account, such as Reseller. The options are: `account_rollup`: Returns batch summaries data aggregated at the account level. `all_merchant`: Returns batch summaries data for all MIDs that belong to the requesting parent ID. `selected_merchant`: Returns batch summaries data for the selected merchant.	Conditional. Required when requesting breakdown data for a merchant.
`{startDayOfWeek}`	Start day of week to breakdown data. The options are: `1` `2` `3` `4` `5` `6` `7`	Optional

Responses

This call can return one of the following HTTP status codes:

200: Ok.

400: Invalid request.

404: Report not found or no transactions are available.

For detailed information on the responses, including which fields are returned, see the Reporting REST API Reference .

Reporting API