Skip to main content

Custom integration

This page provides all the information you need to customize your reports and integrate with the Reporting API.

Before you begin

You must onboard the Reporting API to receive your access credentials. Contact your relationship manager or contact us if you need assistance.

How it works

You can custom integrate to the Reporting API by performing the following steps:

  1. Choose the report type you want to use.
  2. Build a custom report configuration and schedule when you want the report to be generated.
  3. Check the report status.
  4. Retrieve the generated report.

Step 1: Choose report type

Report types are categorized into the following two categories:

  • Pre-funded report types - These report types allow you generate reports on pre-funded transactions, which are authorized transactions that need to be settled between you and the bank.
  • Post-funded report types - These report types allow you generate reports on post-funded transactions, which are settled between the merchant and the bank.

Step 2: Build a custom report configuration and schedule

Customize your report configurations by choosing:

  • The entities for which the reporting data needs to be generated.
  • The applicable attributes you want in your report. Download the Global Reporting Attributes Catalog to identify the attributes that each report type contains.
  • The report delimiter using the field fileDelimiter.
  • The custom report file name using the field reportFileName.
  • The custom file header and file trailer using the fields fileHeader and fileTrailer.
  • Advanced customization to use aliases, aggregates, and custom calculations.

For information on the fields of a report configuration and how to manage them, refer to Manage report configurations.

Schedule a custom report

You can decide when you want the report to be generated by choosing the frequency (daily, weekly, monthly, and adhoc) and the starting and ending time stamp for data collection. 

Required fields for scheduling a report
Field name Description Valid values
scheduleFrequency Specifies frequency of the report schedule. 
  • daily - Running a report every day.
  • weekly - Running a report every Tuesday would be weekly|tue.
  • monthly - Running a report on the 3rd day following the end of the month would be monthly|3.
  • adhoc - Running a report on a custom schedule.
reportFileScheduleTime Specifies when report generation should begin, not when the report has completed. Applies only for daily, weekly, and monthly.  Time in UTC time zone. 
reportingPeriodStartTime  Specifies the starting point for data collection. The start time must be your end of day time to include all information in that period for daily, weekly, and monthly.

Your end of the day time in UTC time zone. 

For example, if your end of the day is 10 PM EST, the reportingPeriodStartTime is 03:00:00.
reportingPeriodEndTime Specifies the ending point for data collection. Applies only for adhoc. Your end of the day time in UTC time zone.

For more information on how to configure a report schedule, refer to Scheduled and adhoc.

The following sample request code block shows how you can customize your report configuration.

HTTP Method: POST

Endpoint: /reports

Scenario: Creating a custom report configuration.

Json
{
    "entityType": "CO",
    "entityIds": [
        "1234567"
    ],
    "reportSections": [
        {
            "sectionReportTypeName": "Settlement Details",
            "sectionReportTypeId": "3002",
            "sectionSelectedFields": [
                {
                    "alias": "Record Type",
                    "constantValueText": "Settlement Details Report"
                },
                {
                    "reportAttributeName": "Entity Identifier"
                },
                {
                    "reportAttributeName": "Entity Name"
                },
                {
                    "reportAttributeName": "Entity Type Code"
                },
                {
                    "reportAttributeName": "Transaction Processing Entity Identifier"
                },
                {
                    "reportAttributeName": "Company External Identifier"
                },
                {
                    "reportAttributeName": "Payment Method Code"
                },
                {
                    "reportAttributeName": "Payment Method Code Description Text"
                },
                {
                    "reportAttributeName": "Card Usage Type"
                },
                {
                    "reportAttributeName": "Card Product Type"
                },
                {
                    "reportAttributeName": "Transaction Timestamp"
                },
                {
                    "reportAttributeName": "Submission Timestamp"
                },
                {
                    "reportAttributeName": "Account Number"
                },
                {
                    "reportAttributeName": "Authorization Code"
                },
                {
                    "reportAttributeName": "Transaction Identifier"
                },
                {
                    "reportAttributeName": "Merchant Order Number"
                },
                {
                    "reportAttributeName": "Submission Identifier"
                },
                {
                    "reportAttributeName": "Fund Transfer Identifier"
                },
                {
                    "reportAttributeName": "Presentment Amount"
                },
                {
                    "reportAttributeName": "Presentment Currency Code"
                },
                {
                    "reportAttributeName": "Settlement Amount"
                },
                {
                    "reportAttributeName": "Settlement Currency Code"
                },
                {
                    "reportAttributeName": "Settled Total Assessment Amount"
                },
                {
                    "reportAttributeName": "Settled Total Interchange Amount"
                },
                {
                    "reportAttributeName": "Settled Total Other Amount"
                }
            ],
            "sectionSortOrderList": [
                {
                    "reportAttributeName": "Payment Method Code",
                    "sortOrderCode": "asc"
                }
            ],
            "sectionFilterAttributeList": [
                {
                    "reportAttributeName": "Merchant Action Code",
                    "filterAttributeCode": "=\"AU\""
                }
            ]
        }
    ],
    "fileDelimiter": ",",
    "reportConfigurationName": "Custom Settlement Details Report",
    "reportFileName": "Custom Settlement Details Report,<Processing Entity ID>.<Report Type>.<frequency>.<From Date YYYY-MM-DD>.<To Date YYYY-MM-DD>",
    "reportHeader": "ReportHeader,<Processing Entity ID>,<Report Type>,<frequency>,<From Date YYYY-MM-DD>,<To Date YYYY-MM-DD>,<Generation Date YYYY-MM-DD>,<Generation Time HH:MM:SS>",
    "fileHeader": "BEGIN,ProcessingEntityId=<Processing Entity ID>,Frequency=<frequency>",
    "fileTrailer": "END,ProcessingEntityId=<Processing Entity ID>,Frequency=<frequency>",
    "csvColumnNameDisplayIndicator": true,
    "reportConfigStatus": "active",
    "reportName": "Custom Settlement Details Report",
    "frequencyConfig": {
        "scheduleFrequency": "adhoc",
        "reportingPeriodStartTimestamp": "2024-04-01 03:00:00",
        "reportingPeriodEndTimestamp": "2024-04-02 02:59:59"
    }
}

The response payload returns the reportIdentifier and reportConfigurationId. You can use the reportIdentifier to check the status of a report and the reportConfigurationId to retrieve the details of a report configuration or update a report configuration.

Step 4: Check the report status

You can check the status of a report by performing a GET call to the /reports endpoint using the report-id as the path parameter.

HTTP Method: GET

Endpoint: /reports/{report-id}

Scenario: Checking the status of a report using the report-id = 5cec7414-03fb-11f0-aa5f-e95281c39793

Json
{
    "reportIdentifier": "5cec7414-03fb-11f0-aa5f-e95281c39793",
    "reportConfigurationId": "5cec7413-03fb-11f0-aa5f-67e2d78a57d0",
    "reportTypeNames": [
        "Settlement Details"
    ],
    "reportStatus": "completed",
    "updateTimestamp": "2025-03-18T13:18:54.512Z",
    "createTimestamp": "2025-03-18T13:17:38.996Z",
    "intervalParam": {
        "reportingPeriodStartTimestamp": "2024-04-01 03:00:00",
        "reportingPeriodEndTimestamp": "2024-04-02 02:59:59",
        "scheduleFrequency": "adhoc"
    },
    "reportDetails": {
        "reportFileName": "Custom Settlement Details Report.1234567.adhoc.2024-04-01.2024-04-02",
        "url": "https://report-files-api.merchant.jpmorgan.com/api/v1/report-files/5cec7414-03fb-11f0-aa5f-e95281c39793"
    }
}

If you have scheduled for daily, weekly, or monthly report or don't know the report-Id, you can perform a GET /reports to retrieve the latest report details.

HTTP Method: GET

Endpoint: /reports

Scenario: Retrieve the details of all reports.

Json
{
    "next": null,
    "summarizedReports": [
        {
            "reportIdentifier": "6ee97665-8d2c-424c-859a-dd98a9e4e0ca",
            "reportConfigurationId": "193544e3-0fdf-472e-8cae-798ff88da609",
            "reportTypeNames": [
                "Settlement Summary",
                "Settlement Details"
            ],
            "reportStatus": "requested",
            "updateTimestamp": "2021-08-23T00:23:05.353Z",
            "createTimestamp": "2021-08-23T00:19:05.353Z",
            "intervalParam": {
                "reportingPeriodStartTimestamp": "2021-08-23 00:18:18",
                "reportingPeriodEndTimestamp": "2021-08-23 00:19:18",
                "scheduleFrequency": "adhoc"
            }
        },
        {
            "reportIdentifier": "c6a6f075-64d5-476f-b463-bc1c5de1abd7",
            "reportConfigurationId": "ca788ad9-521c-45ec-b36d-0fdd38701e4d",
            "reportTypeNames": [
                "Transaction Details"
            ],
            "reportStatus": "completed",
            "updateTimestamp": "2021-08-20T00:23:05.353Z",
            "createTimestamp": "2021-08-20T00:19:05.353Z",
            "intervalParam": {
                "reportingPeriodStartTimestamp": "2021-08-20 00:18:18",
                "reportingPeriodEndTimestamp": "2021-08-20 00:19:18",
                "scheduleFrequency": "adhoc"
            },
            "reportDetails": {
                "reportFileName": "992994469896.Multiple.adhoc.2021-08-20.2021-08-20",
                "url": "https://sample-report-url"
            }
        }
    ],
    "lastPage": true
}

For more information, refer to Retrieve report details.

Step 5: Retrieve the generated report

You can retrieve the generated reports (reportStatus = completed) in various formats using the Reporting API or Commerce Center.

For more information on the different formats and ways you can retrieve a generated report, refer to Retrieve report files.

Scheduled and Adhoc

Manage report configurations

Retrieve reports