listReports endpoint for settlement reports

As part of our Checkout API solution, the listReports endpoint offers an alternative way to access your settlement data. It returns a list of settlement reports and their URLs, so you can automatically pull settlement data into your accounting or reconciliation systems.

For more information, see the listReports specification.

Settlement report data

The listReports endpoint pulls the same reports available in the Reach Admin Portal, including transactional data, fees, FX rates, and reserves. For more information on Reach's settlement reports and your data, see the Reach reports and data share page.

Request

A listReports request is a form-encoded POST signed with the same HMAC method as the Checkout API. If your Checkout API integration is live, you can reuse its signing code.

Environments

There are two environments available:

• Production: https://checkout.rch.io/v2.22/listReports
• Sandbox: https://checkout.rch.how/v2.22/listReports

Request body

The request body (Content-Type: application/x-www-form-urlencoded) carries two fields:

request parameters

The following table describes the request parameters:

Response

A successful call returns a Reports array with one entry per settlement report, each carrying an ID, a creation time, and a download URL. It returns metadata only; you fetch the report files separately.

Status codes

The following table describes potential HTTP status codes and responses:

A bad signature comes back as the message Signature mismatch.

Example request and response

The following code block shows an example of a potential request and response:

curl X- POST 'https://checkout.rch.how/v2.22/listReports'  \
  -H 'Content-Type: application/x-www-form-urlencoded'  \
  --data-urlencode 'request={"MerchantId":"<MERCHANT-GUID>","BusinessPartner":"<SETTLEMENT_BP>","SinceReportdI":1042}'  \
  --data-urlencode 'signature=<HMAC-OF-REQUEST-JSON>'

{
  "Reports": [
    { "ReportId" :1043, "CreatedTime": "2026-10-30T14:05:12Z", "Url": "https://..."},
    { "ReportId": 1051, "CreatedTime": "2026-11-06T14:04:58Z", "Url": "https://..."}
  ]
}

Retrieve reports

Reports are generated according to your settlement schedule. After a report is generated, it is available through listReports. Rather than manually accessing the files through the Admin Portal, you can use this alternative method to set up a scheduled retrieval.

Scheduled retrieval

The usual pattern is a scheduled job that lists new reports, downloads each CSV, and stores the highest ReportId it has seen.

One possible setup process has the following steps:

1. First run: call listReports without SinceReportId to get every report to date.
2. Download: fetch each entry's URL to get the CSV settlement report.
3. Save the cursor: store the highest ReportId returned.
4. Later runs: pass the stored value as SinceRportId so only newer reports come back.

Considerations to plan around

When you create our scheduled job, consider the following:

• A report is available on the day its settlement runs. If you're on weekly settlement, you receive one report per week.
• No report exists until the first settlement after you move into a production environment, so your list is empty until then.
• If you settle in more than one currency, you receive a separate report per currency.