Skip to main content

Manage report configurations

Report configurations are the attributes of your custom report. The following sections describe how to:

  • Create new report configurations
  • Get a list of all report configurations for a merchant profile
  • Get details about a specific configuration
  • Update a report configuration

Before you begin

Before creating and managing report configurations make sure you understand the basics of report configurations including schedules, standard configurations and advanced configurations.

Also, you’ll need to understand report types available for your payment method codes and regions.

To get started, generate simple report configuration request with minimal fields. The following is an example of creating a simple report configuration with minimal fields:

HTTP method: POST
Endpoint: /reports

Json
{ 
    "entityType": "PE", 
    "entityIds": [ 
        "9876543210", 
        "9876543211" 
    ], 
    "reportSections": [ 
        { 
            "sectionReportTypeName": "Transaction Details" 
        } 
    ], 
    "frequencyConfig": { 
        "scheduleFrequency": "Daily", 
        "reportFileScheduledTime": "09:00:00", 
        "reportingPeriodStartTime": "23:00:00" 
    } 
}
Json
{ 
    "reportIdentifier": "ac4e5189-43c7-4766-8c05-fde51ccc3528", 
    "reportConfigurationId": "70c36405-60b6-4a36-a539-2a95dd307516", 
    "reportTypeNames": [ 
        "Transaction Details" 
    ], 
    "createTimestamp": "2020-11-20T19:43:26.604Z" 
}

This method will create a new report configuration with defaulted fields. Once it is created, the full report configuration can be retrieved with a GET request and the full report configuration can then be edited and updated using a PUT request. This is typically easier than building a full report configuration from scratch.

See Get details about a specific configuration below to learn how to retrieve the full report configuration. Also see Update a report configuration below to learn how to edit using a PUT request.

Tip

For additional details including standard and advanced configurations, see Report configurations.

Get a list of all report configurations

It’s simple to get a historic list of all the report configuration runs for a given merchant profile. The following details are available for each report configuration requested:

  • Report configuration ID
  • Update timestamp
  • Frequency Configuration:
    • Schedule frequency (daily, weekly, monthly or adhoc)
    • Report File Scheduled Time (appear for daily, weekly, monthly)
    • Report period start time  (appear for daily, weekly, monthly)
    • Report period start timestamp (appear for Adhoc)
    • Report period end timestamp (appear for Adhoc)
  • Report configuration status
  • Report type names
  • Section Report Type IDs

The following example shows how to request a list of all historical report configurations:

HTTP method: GET
Endpoint: /report-configs

Json
{ 
  "summarizedReportConfigurations": [ 
    { 
      "reportConfigurationId": "193544e3-0fdf-472e-8cae-798ff88da609", 
      "updateTimestamp": "2021-08-23T02:07:43.550Z", 
      "frequencyConfig": { 
        "scheduleFrequency": "Adhoc", 
        "reportFileScheduledTime": "2021-08-23T09:00:00Z", 
        "reportingPeriodStartTime": "2021-08-23T23:00:00Z" 
      }, 
      "reportConfigStatus": "Active", 
      "reportTypeNames": [ 
        "Settlement Summary", 
        "Settlement Details" 
      ], 
      "reportTypeIds": [ 
        "1004", 
        "1002" 
      ] 
    }, 
    { 
      "reportConfigurationId": "044a7d09-b0eb-4cef-84dc-c4771d15375c", 
      "updateTimestamp": "2021-08-23T02:07:41.779Z", 
      "frequencyConfig": { 
        "scheduleFrequency": "Adhoc", 
        "reportingPeriodStartTimestamp": "2020-04-11 01:00:00", 
        "reportingPeriodEndTimestamp": "2020-04-13 23:00:00" 
      }, 
      "reportConfigStatus": "Active", 
      "reportTypeNames": [ 
        "Transaction Details" 
      ], 
      "reportTypeIds": [ 
        "1003" 
      ] 
    } 
  ], 
  "lastPage": true 
}
Tip

The GET /report-configs response uses pagination. Learn more about pagination.

Get details about a specific configuration

Get the details about a specific report configuration run in the past with the below information:

  • Report Configuration ID
  • Report Configuration Name
  • Report Description 
  • Entity IDs
  • Report Sections:
    • Section Title
    • Section Report Type Name
    • Section Report Type ID
    • Section Selected Fields:
      • Constant Value Text
      • Report Attribute Name
  • Section Sort Orders:
    • Report Attribute Name
    • Sort Order Code
  • Section Filter Attributes:
    • Report Attribute Name
    • Filter Attribute Code
  • Frequency Configuration:
    • Schedule Frequency
    • Report File Scheduled Time (appear for daily, weekly, monthly)
    • Report Period Start Time (appear for daily, weekly, monthly)
    • Reporting Period Start Timestamp (appear for ad hoc)
    • Reporting Period End Timestamp (appear for ad hoc) 
  • File Delimiter
  • Report File Name
  • Report Header
  • File Header
  • File Trailer
  • CSV Column Name Display Indicator
  • Total Row Count Display Indicator
  • Section Row Count Display Indicator
  • Report Configuration Status
  • Update Time Stamp

The following example shows how to request details about a specific report configuration:

HTTP method: GET
Endpoint: /report-configs/{reportConfigurationId}

Json
{ 
    "reportConfigurationId": "7611d1bf-325c-4795-a828-ac21f9bea5dc", 
    "entityIds": [ 
        "992994469896" 
    ], 
    "reportSections": [ 
        { 
            "sectionTitle": "Transaction Details", 
            "sectionReportTypeName": "Transaction Details", 
            "sectionReportTypeId": "1001", 
            "selectedFields": [ 
                { 
                    "reportAttributeName": "Action Date" 
                }, 
                { 
                    "reportAttributeName": "Transaction Processing Entity Identifier" 
                }, 
                { 
                    "reportAttributeName": "Transaction Currency Code" 
                }, 
                { 
                    "reportAttributeName": "Settlement Currency Code" 
                }, 
                { 
                    "reportAttributeName": "Payout Posted Timestamp" 
                }, 
                { 
                    "reportAttributeName": "Transaction Identifier", 
                    "alias": "Txn count", 
                    "aggregateOperationText": "count" 
                }, 
                { 
                    "reportAttributeName": "Transaction Amount", 
                    "aggregateOperationText": "sum", 
                    "alias": "Transaction Amount Total" 
                }, 
                { 
                    "reportAttributeName": "Settlement Currency Code" 
                }, 
                { 
                    "reportAttributeName": "Transaction Processing Entity Identifier" 
                }, 
                { 
                    "reportAttributeName": "Transaction Identifier", 
                    "aggregateOperationText": "count", 
                    "alias": "Total Authorization Count", 
                    "conditionalAggregateIndicator": true, 
                    "aggregateConditionAttributeName": "Event Type Category Code", 
                    "aggregateConditionText": "= \"NON\"" 
                }, 
                { 
                    "reportAttributeName": "Transaction Identifier", 
                    "aggregateOperationText": "count", 
                    "alias": "Total Declined Deposit Count", 
                    "conditionalAggregateIndicator": true, 
                    "aggregateConditionAttributeName": "Event Type Category Code", 
                    "aggregateConditionText": "= \"DEC\"" 
                }, 
                { 
                    "reportAttributeName": "Transaction Identifier", 
                    "aggregateOperationText": "count", 
                    "alias": "Total Authorization Count", 
                    "conditionalAggregateIndicator": true, 
                    "aggregateConditionAttributeName": "Event Type Category Code", 
                    "aggregateConditionText": "= \"NON\"" 
                }, 
                { 
                    "reportAttributeName": "Transaction Amount", 
                    "aggregateOperationText": "sum", 
                    "alias": "Total Declined Amount", 
                    "conditionalAggregateIndicator": true, 
                    "aggregateConditionAttributeName": "Event Type Category Code", 
                    "aggregateConditionText": "= \"DEC\"" 
                }, 
                { 
                    "reportAttributeName": "Transaction Identifier", 
                    "aggregateOperationText": "count", 
                    "alias": "Total Cancelled Count", 
                    "conditionalAggregateIndicator": true, 
                    "aggregateConditionAttributeName": "Event Type Category Code", 
                    "aggregateConditionText": "IN (\"CNSALE\",\"CNREF\")" 
                }, 
                { 
                    "reportAttributeName": "Transaction Amount", 
                    "aggregateOperationText": "sum", 
                    "alias": "Total Cancelled Amount", 
                    "conditionalAggregateIndicator": true, 
                    "aggregateConditionAttributeName": "Event Type Category Code", 
                    "aggregateConditionText": "IN (\"CNSALE\",\"CNREF\")" 
                }, 
                { 
                    "reportAttributeName": "Transaction Identifier", 
                    "aggregateOperationText": "count", 
                    "alias": "Total Rejected Count", 
                    "conditionalAggregateIndicator": true, 
                    "aggregateConditionAttributeName": "Event Type Category Code", 
                    "aggregateConditionText": "= \"REJ\"" 
                }, 
                { 
                    "reportAttributeName": "Transaction Amount", 
                    "aggregateOperationText": "sum", 
                    "alias": "Total Rejected Amount", 
                    "conditionalAggregateIndicator": true, 
                    "aggregateConditionAttributeName": "Event Type Category Code", 
                    "aggregateConditionText": "= \"REJ\"" 
                }, 
                { 
                    "reportAttributeName": "Transaction Amount", 
                    "aggregateOperationText": "sum", 
                    "alias": "Net Successful Transaction Amount", 
                    "conditionalAggregateIndicator": true, 
                    "aggregateConditionAttributeName": "Event Type Category Code", 
                    "aggregateConditionText": "IN (\"SALE\",\"REF\")" 
                } 
            ] 
        } 
    ], 
    "frequencyConfig": { 
        "scheduleFrequency": "Adhoc", 
        "reportingPeriodStartTimestamp": "2020-04-11 01:00:00", 
        "reportingPeriodEndTimestamp": "2020-04-13 23:00:00" 
    }, 
    "fileDelimeter": ",", 
    "reportFileName": "theFileNameOfTheReport", 
    "reportHeader": "RH_ReportHeader", 
    "fileHeader": "FH_FileHeader", 
    "fileTrailer": "FT_FileTrailer", 
    "csvColumnNameDisplayIndicator": true, 
    "totalRowCountDisplayIndicator": false, 
    "sectionRowCountDisplayIndicator": false, 
    "reportConfigStatus": "Active", 
    "updateTimestamp": "2021-08-23T02:07:41.779Z" 
}

Update a report configuration

You can modify the existing report configuration by using a PUT request to the /report-configs endpoint. 

The following is an example of a PUT request to set a report configuration to Active status.

HTTP method: PUT
Endpoint: /report-configs/{reportConfigurationId}

Json
{ 
   "reportConfigStatus": "Active"
}
Json
{ 
    "reportConfigurationId": "7611d1bf-325c-4795-a828-ac21f9bea5dc", 
    "entityIds": [ 
        "9876543210", 
        "9876543211" 
    ], 
    "reportSections": [ 
        { 
            "sectionTitle": "Transaction Details", 
            "sectionReportTypeName": "Transaction Details", 
            "sectionReportTypeId": "1001", 
            "selectedFields": [ 
                { 
                    "reportAttributeName": "Firm Authorization Approval Code" 
                }, 
                { 
                    "reportAttributeName": "Firm Authorization Response Category Code" 
                }, 
                { 
                    "reportAttributeName": "Firm Authorization Response Code" 
                }, 
                { 
                    "reportAttributeName": "Firm Authorization Response Description Text" 
                }, 
                { 
                    "reportAttributeName": "Payment Instrument Code" 
                }, 
                { 
                    "reportAttributeName": "Payment Method Code" 
                }, 
                { 
                    "reportAttributeName": "Transaction Identifier" 
                }, 
                { 
                    "reportAttributeName": "Transaction Processing Entity Identifier" 
                } 
            ] 
        } 
    ], 
    "frequencyConfig": { 
        "scheduleFrequency": "Adhoc", 
        "reportingPeriodStartTimestamp": "2021-08-23 01:00:00", 
        "reportingPeriodEndTimestamp": "2021-08-23 23:00:00" 
    }, 
    "fileDelimeter": "|", 
    "reportFileName": "theFileNameOfTheReport", 
    "reportHeader": "RH_ReportHeader", 
    "fileHeader": "FH_FileHeader", 
    "fileTrailer": "FT_FileTrailer", 
    "csvColumnNameDisplayIndicator": true, 
    "totalRowCountDisplayIndicator": false, 
    "sectionRowCountDisplayIndicator": false, 
    "reportConfigStatus": "Active", 
    "updateTimestamp": "2021-08-23 00:26:23.884" 
}
Tip

As mentioned above, creating a simple report configuration, then retrieving the full report configuration, editing it and updating with a PUT is the easiest way to build new report configurations.