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:

  • Learn about the available report types and determine the one you want to use.
  • Learn about how you can schedule and customize the fields in a report using the report configuration.

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

Create a report configuration

Create a report configuration by sending a POST call to the /reports endpoint. You can create a simple report configuration using a pre-configured report or a detailed report configuration by customizing the fields in the report as per your needs. 

The following are the required, conditionally required, and optional fields for creating a report configuration.

Required, conditionally required, and optional fields for creating a report configuration
Field name Field description Required (R), Conditionally Required (CR), or Optional (O)
entityType

The level of the merchant relationship as it relates to the acquiring account. Allowed values are:

  • PE - Processing Entity
  • TD - Transaction Division
  • BU - Business Unit
  • FTI - Fund Transfer Instruction
  • CO - Company
  • RGPE - Reporting group for processing entity
  • RGTD - Reporting group for transaction division
  • RGFTI - Reporting group for fund transfer instruction
  • RGBU - Reporting group for business unit
  • RGCO - Reporting group for company

If no value is provided, the default value is PE.

 O
entityIds Store the array of applicable processing entities for which the data is needed. R
reportName Name of the report. O
frequencyConfig Adhoc and scheduled frequency configuration object. Set the frequency and scheduling of the report generation along with transaction intervals. R
frequencyConfig.scheduleFrequency The planned intervals at which report generation events, activities, or processes occur. Allowed values are:
  • daily
  • weekly
  • monthly
  • adhoc
 R
frequencyConfig.reportingPeriodStartTimestamp Indicates the start date and time when the report activity begins in standard UTC format. This field includes hour (hh), minute (mm), seconds (ss) and date (if timestamp) or year (YYYY), month (MM), and day (DD) (if date). CR (Conditionally required when frequency is adhoc)
frequencyConfig.reportingPeriodEndTimestamp Indicates the end date and time when the report activity ends in standard UTC format. This field includes hour (hh), minute (mm), seconds (ss) and date (if timestamp) or year (YYYY), month (MM), and day (DD) (if date). CR (Conditionally required when frequency is adhoc)
frequencyConfig.reportFileScheduledTime Designates the hour, minute, and second when the report is scheduled to generate. CR (Conditionally required when frequency is scheduled)
frequencyConfig.reportingPeriodStartTime Designates the beginning hour, minute, and second from when the report data is collected. CR (Conditionally required when frequency is scheduled)
fileDelimiter

Indicates the demarcation operator to separate and distinguish individual data fields wthin a report, facilitating structred organization and retrieval of information. Allowed values are:

  • Comma - [,]
  • Pipe - [|]
  • Tab - [->]
 O
reportFileName

The merchant defined name for the report file.

If no value is provided, the default file name format is: "Entity ID". "Report Type" . "frequency". "From Date YYYY-MM-DD". "To Date YYYY-MM-DD"

 O
reportHeader

The header of the report file.

If no value is provided, the default format is: entityId= "Entity ID", ReportTypeName= "Report Type" , Frequency="frequency", FromDate= "From Date YYYY-MM-DD" , ToDate= "To Date YYYY-MM-DD " , GenerationDate= "Generation Date YYYY-MM-DD" , GenerationTime= " Generation Time HH:MM:SS"

 O
fileHeader

The textual information in the first row of a file.

If no value is provided, the default format is: EntityId= "Entity ID",Frequency="frequency"

 O
fileTrailer

The textual information in the last row of a file.

If no value is provided, the default format is: EntityId= "Entity ID ",Frequency="frequency"

 O
csvColumnNameDisplayIndicator Indicates the Boolean value to display the column name in the report. O
reportConfigStatus

The status of the report configuration. Allowed values are:

  • Active
  • Inactive
 O
reportDescription The textual description of the report. O
reportConfigurationName The merchant defined name of the report configuration. O
reportSections Object for the label given as a header for the section. R
reportSections.sectionTitle The name of the section within the report. O
reportSections.sectionReportTypeName The report type name of the section within the report. R
reportSections.sectionSelectedFields Object for section Selected Fields List O
reportSections.sectionSelectedFields.reportAttributeName The name of the attribute in the report. O
reportSections.sectionSelectedFields.alias The merchant assigned name of the attribute in the report. O
reportSections.sectionSelectedFields.constantValueText The static text value of the attribute. O
reportSections.sectionSelectedFields.aggregateOperationText

The category of aggregation analytic functions. Allowed values are:

  • count
  • avg
  • min
  • max
  • sum
 O
reportSections.sectionSelectedFields.conditionalAggregateIndicator

Indicates the Boolean value for aggregate operation, if performed on a specific condition.

 O
reportSections.sectionSelectedFields.aggregateConditionAttributeName The label of the field on which aggregate condition is defined. O
reportSections.sectionSelectedFields.aggregateConditionText Textual representation of the aggregate condition value. O
reportSections.sectionSortOrderList Object for section sort order. O
reportSections.sectionSortOrderList.sortOrderCode

The arrangement of items based on specified criteria such as alpabetical, numerical or organise data in a specific sequence. Allowed values are:

  • asc
  • desc
 O
reportSections.sectionFilterAttributeList Object for section filter attributes. O
reportSections.sectionFilterAttributeList.filterAttributeCode

The filter criteria to filter the report.

  • Filter by attribute - For example, filterAttributeCode = Payment Submitted
  • Filter by function - Supported functions are: =,!=, <,>, IN, and NOT IN
 O
reportSections.sectionReportTypeId The report type identifier of the section within the report. O
reportFormatList

Format of the report. Allowed values are:

  • CSV - Comma Separated Values
  • PDF - Portable Document Format
  • TXT - Text
  • GZ - Gnu Zip or Gzip

If no value is provided, the default value is CSV.

 O
sectionRowCountDisplayIndicator Indicates the Boolean value to display the row count for each report section. This field is only applicable when the report is generated in PDF format. O
totalRowCountDisplayIndicator Indicates the Boolean value to display the total number of row count in the report for all sections. This field is only applicable when the report is generated in PDF format. O
presignedURLEnabledIndicator Indicates if large file support is enabled on the report configuration. O

HTTP method: POST

Endpoint: /reports

Scenario: Creating a simple report configuration with only the required fields using the pre-configured report type transaction details

Json
{ 
    "entityIds": [ 
        "9876543210", 
        "9876543211" 
    ], 
    "reportSections": [ 
        { 
            "sectionReportTypeName": "Transaction Details" 
        } 
    ], 
    "frequencyConfig": { 
        "scheduleFrequency": "Daily", 
        "reportFileScheduledTime": "09:00:00", 
        "reportingPeriodStartTime": "23:00:00" 
    } 
}

Response:

Json
{ 
    "reportIdentifier": "ac4e5189-43c7-4766-8c05-fde51ccc3528", 
    "reportConfigurationId": "70c36405-60b6-4a36-a539-2a95dd307516", 
    "reportTypeNames": [ 
        "Transaction Details" 
    ], 
    "createTimestamp": "2020-11-20T19:43:26.604Z" 
}
Note
  • If you don't want the fileHeader and fileTrailer to appear, enter an empty string like a space for their values.
  • If entityType is not provided, PE is the default value.
  • The maximum number of sections you can add to customize a report type is 8.
  • You can have a maximum of 15 fields per section when the reportFormat is PDF for better visibility.
  • You can configure a maximum of 20 unique report configurations per entity ID.

The following is an example of how to create a detailed report configuration with custom fields.

HTTP method: POST

Endpoint: /reports

Json
{
    "entityType": "PE",
    "entityIds": [
        "998586046651"
    ],
    "presignedURLEnabledIndicator": true,
    "reportSections": [
        {
            "sectionReportTypeName": "Settlement Details",
            "sectionSelectedFields": [
                {
                    "alias": "Record Type",
                    "constantValueText": "RACT0010"
                },
                {
                    "alias": "Entity Type",
                    "constantValueText": "TD"
                },
                {
                    "reportAttributeName": "Action Date",
                    "alias": "Submission Date"
                },
                {
                    "reportAttributeName": "Payout Identifier"
                },
                {
                    "reportAttributeName": "Transaction Processing Entity Identifier",
                    "alias": "Entity Number"
                },
                {
                    "reportAttributeName": "Transaction Currency Code",
                    "alias": "Presentment Currency"
                },
                {
                    "reportAttributeName": "Sales Order Number",
                    "alias": "Merchant Order Number"
                },
                {
                    "reportAttributeName": "Masked Card Number",
                    "alias": "Account Number"
                },
                {
                    "reportAttributeName": "Card Expiration Month Year Number",
                    "alias": "Expiration Date"
                },
                {
                    "reportAttributeName": "Transaction Amount",
                    "alias": "Amount"
                },
                {
                    "reportAttributeName": "Payment Method Code",
                    "alias": "MOP"
                },
                {
                    "reportAttributeName": "Client Action Code",
                    "alias": "Action Code"
                },
                {
                    "reportAttributeName": "Authorization Timestamp",
                    "alias": "Auth Date"
                },
                {
                    "reportAttributeName": "Firm Authorization Response Code",
                    "alias": "Auth Code"
                },
                {
                    "reportAttributeName": "Payment Authorization Response Identifier",
                    "alias": "Auth Response Code"
                },
                {
                    "reportAttributeName": "Merchant Category Code",
                    "alias": "MCC"
                },
                {
                    "reportAttributeName": "Token Type Code"
                },
                {
                    "reportAttributeName": "Interchange Program Code",
                    "alias": "Interchange Qualification Code"
                },
                {
                    "reportAttributeName": "Interchange Fee Amount",
                    "alias": "Interchange Unit Fee"
                },
                {
                    "reportAttributeName": "Interchange Fee Rate",
                    "alias": "Interchange Face Value % Fee"
                },
                {
                    "reportAttributeName": "Total Interchange Amount"
                },
                {
                    "reportAttributeName": "Total Payment Brand Fee Amount",
                    "alias": "Total Assessment Amount"
                },
                {
                    "reportAttributeName": "Other Fee Amount",
                    "alias": "Other Debit Passthrough Fees"
                },
                {
                    "reportAttributeName": "Settlement Currency Code",
                    "alias": "Settlement Currency"
                }
            ],
            "sectionSortOrderList": [
                {
                    "reportAttributeName": "Total Interchange Amount",
                    "sortOrderCode": "asc"
                }
            ],
            "sectionFilterAttributeList": [
                {
                    "reportAttributeName": "Funding Status Code",
                    "filterAttributeCode": "=\"Payment Submitted\""
                },
                {
                    "reportAttributeName": "Client Action Code",
                    "filterAttributeCode": "IN (\"DP\",\"RF\",\"AR\",\"DR\",\"RQ\")"
                }
            ]
        }
    ],
    "fileDelimiter": ",",
    "reportConfigurationName": "Deposit Detail Financial Report-Ad hoc",
    "reportFileName": "<Processing Entity ID>.<Report Type>.<frequency>.<From Date YYYY-MM-DD>.<To Date YYYY-MM-DD>",
    "reportHeader": "HACT0010,<Processing Entity ID>,<Report Type>,<frequency>,<From Date YYYY-MM-DD>,<To Date YYYY-MM-DD>,<Generation Date YYYY-MM-DD>,GenerationTime=<Generation Time HH:MM:SS>",
    "fileHeader": "DFRBEGIN,ProcessingEntityId=<Processing Entity ID>,Frequency=<frequency>",
    "fileTrailer": "DFREND,ProcessingEntityId=<Processing Entity ID>,Frequency=<frequency>",
    "csvColumnNameDisplayIndicator": true,
    "reportConfigStatus": "Active",
    "frequencyConfig": {
        "scheduleFrequency": "adhoc",
        "reportingPeriodStartTimestamp": "2021-02-14 01:00:00",
        "reportingPeriodEndTimestamp": "2021-02-16 23:00:00"
    }
}

Response:

Json
{
    "reportIdentifier": "8f25d70d-887e-49eb-9a95-f8b56c04c3ba",
    "reportConfigurationId": "96658d8b-9602-4db9-bb46-ed988523e027",
    "reportTypeNames": [
        "Settlement Details"
    ],
    "createTimestamp": "2020-11-20T20:33:27.337Z"
}

Get a list of all report configurations

Retrieve a historic list of all the report configurations for a given merchant profile. 

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

Retrieve the details about a specific report configuration using the reportConfigurationId.

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

HTTP method: GET
Endpoint: /report-configs/{report-configuration-id}

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 an existing report configuration by sending 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/{report-configuration-id}

Json
{ 
   "reportConfigStatus": "Inactive"
}

Response:

Json
{ 
    "reportConfigurationId": "7611d1bf-325c-4795-a828-ac21f9bea5dc", 
    "entityIds": [ 
        "9876543210", 
        "9876543211" 
    ], 
    "reportSections": [ 
        { 
            "sectionTitle": "Transaction Details", 
            "sectionReportTypeName": "Transaction Details", 
            "sectionReportTypeId": "1001", 
            "sectionSelectedFields": [ 
                { 
                    "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": "Inactive", 
    "updateTimestamp": "2021-08-23 00:26:23.884" 
}
Tip

You can re-use an existing adhoc report configuration instead of creating a new adhoc configuration by using PUT /report-configs/{report-configuration-id} endpoint.