Reconciliation: Overview

Related API Reference

🔗
API Reference: Request a client reconciliation report

Overview

A reconciliation report (registry) is a file with your transactions for a chosen period. You can use it to reconcile your accounting with the platform.

You can request a report yourself at any time through the API. The report is generated asynchronously, so getting a file takes three steps.

How It Works

sequenceDiagram
    participant App as Your app
    participant API as API

    App->>API: POST .../reports/on-demand + period, types, statuses
    API-->>App: 202 reportId + GENERATION_STARTED
    loop Until status is GENERATED
        App->>API: GET .../reports/{reportId}/status
        API-->>App: 200 status
    end
    Note over App: take s3Key from the response
    App->>API: GET /outgoing-reconciliation-files?key + reconciliationId
    API-->>App: 200 report file (XLSX or CSV)

Step	Description	Guide
1	Request a report for a period, transaction types and statuses. You receive a `reportId`.	Request a report
2	Poll the report status by `reportId` until it becomes `GENERATED`.	Check the report status
3	Download the file using `s3Key` and `reportId` from the status response.	Download the report

Before You Start

Get an access token as described in Get Access and Refresh Tokens and pass it in the Authorization: Bearer {ACCESS_TOKEN} header of every request.
Find the Settlement Account ID (with the SA prefix, for example SA1234567890) in the Client Portal. A report always belongs to one Settlement Account, and the token must have access to it.
Use the API base URL of your environment from Access URLs. All reconciliation endpoints are under the /reconciliation path.

Limits

⚠️

Maximum period of one report is 40 calendar days (both boundary days are included).

One report at a time per Settlement Account. While a report is being generated, a new request for the same account returns 429. Wait until the status becomes GENERATED or ERROR.

Report Statuses

Status	Description
GENERATION_STARTED	The report is being generated. The file is not available yet.
GENERATED	The file is ready. `s3Key` and `s3DownloadPath` are filled in, download the file.
ERROR	Generation failed. Request the report again; contact support if the error repeats.

Report List

To see reports that were already generated, including scheduled ones, use Get the list of client reconciliation reports. The response has the same fields as the status response.

Errors

Error responses have the same structure:

{
  "failureMessage": "Period length is 45 days, which is invalid or exceeds the maximum allowed of 40 days",
  "timestamp": "2026-10-08T05:12:41.318Z"
}

HTTP code	When it happens
400	Invalid request: empty `transactionTypeAndStatus`, invalid date or timezone, period longer than 40 days, unknown Settlement Account, report not found when downloading.
401	The `Authorization` header is missing or invalid when downloading a file.
403	The token has no access to the Settlement Account or to the report.
404	The report is not found when checking its status.
429	A report for this Settlement Account is already being generated.

When to Use

Reconcile your accounting with the platform for a chosen period.
Audit payments, disbursements and refunds with the statuses you need.
Automate report retrieval instead of downloading files manually.