Reporting API

Using the Reporting API, you can:
  • View report attributes before creating a subscription
  • View report subscriptions
  • Create, edit, and delete report subscriptions
  • Download reports
  • Create one-time reports

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://
      

      
/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:///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

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.visaacceptance.com
  • Test
    : apitest.visaacceptance.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://
    

    
/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.visaacceptance.com
  • Production:
    api.visaacceptance.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
  • 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.

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.

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:///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.visaacceptance.com
  • Production:
    api.visaacceptance.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.

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://
      

      
/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://
      

      
/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.visaacceptance.com
  • Production:
    api.visaacceptance.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://
      

      
/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.visaacceptance.com
  • Production:
    api.visaacceptance.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.

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.visaacceptance.com
  • Production:
    api.visaacceptance.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
  • 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.

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://
    

    
/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.visaacceptance.com
  • Production:
    api.visaacceptance.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.

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://
    

    
/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.visaacceptance.com
  • Production:
    api.visaacceptance.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.

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://
    

    
/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.visaacceptance.com
  • Production:
    api.visaacceptance.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.

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://
    

    
/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.visaacceptance.com
  • Production:
    api.visaacceptance.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.

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://
    

    
/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.visaacceptance.com
  • Production:
    api.visaacceptance.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.