Reconciliation: Request a Report

Related API Reference

🔗
API Reference: Request a client reconciliation report

Overview

This is the first step of getting a report through the API. The request describes what goes into the report. The response confirms that generation has started and returns a reportId, which you use in the next steps.

POST {API_BASE_URL}/reconciliation/api/v2/outgoing-reconciliations/settlement-accounts/{SETTLEMENT_ACCOUNT_ID}/reports/on-demand
Authorization: Bearer {ACCESS_TOKEN}
Content-Type: application/json

Request Fields

Field	Required	Description
periodStart	Yes	First day of the period, `YYYY-MM-DD`. The period starts at 00:00:00 in the given `timezone`.
periodEnd	Yes	Last day of the period, `YYYY-MM-DD`, inclusive. The period ends at 23:59:59 in the given `timezone`. Maximum 40 days in total.
timezone	Yes	Timezone in IANA format, for example `Europe/Moscow`. It sets the period boundaries and the dates shown in the report.
transactionTypeAndStatus	Yes	At least one item. Defines which transactions get into the report (see below).
fileFormat	No	`XLSX` (default) or `CSV`.

transactionTypeAndStatus

Each item is a transaction type and the list of statuses to include for it.

Field	Description
transactionType	`PAYMENT`, `DISBURSEMENT` or `REFUND`.
statuses	Transaction statuses to include, for example `["CAPTURED"]`. Only transactions in these statuses get into the report.

Available statuses:

Transaction type	Statuses
PAYMENT	`ACCEPTED`, `AUTHORIZATION_REQUESTED`, `AUTHORIZATION_PENDING`, `AUTHORIZED`, `CAPTURE_REQUESTED`, `CAPTURED`, `CANCELLATION_REQUESTED`, `CANCELLED`, `EXPIRED`, `DECLINED`, `ERROR`, `PARTNER_RECONCILED`, `SETTLED`
DISBURSEMENT	`ACCEPTED`, `DISBURSEMENT_REQUESTED`, `PAID_OUT`, `DECLINED`, `ERROR`
REFUND	`ACCEPTED`, `REFUND_REQUESTED`, `REFUND_ISSUED`, `REFUNDED`, `REFUND_FAILED`, `DECLINED`, `ERROR`

Example

Report with successful payments only, for 1–7 October 2026:

curl -X POST \
  "$API_BASE_URL/reconciliation/api/v2/outgoing-reconciliations/settlement-accounts/SA1234567890/reports/on-demand" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "periodStart": "2026-10-01",
    "periodEnd": "2026-10-07",
    "timezone": "Europe/Moscow",
    "transactionTypeAndStatus": [
      { "transactionType": "PAYMENT", "statuses": ["CAPTURED"] }
    ]
  }'

Payments and disbursements in one report, as CSV:

{
  "periodStart": "2026-10-01",
  "periodEnd": "2026-10-31",
  "timezone": "UTC",
  "fileFormat": "CSV",
  "transactionTypeAndStatus": [
    { "transactionType": "PAYMENT", "statuses": ["CAPTURED", "DECLINED"] },
    { "transactionType": "DISBURSEMENT", "statuses": ["PAID_OUT"] }
  ]
}

Response

The API responds with 202 Accepted. At this point the file does not exist yet, so s3Key, s3DownloadPath, fileName and fileUrl are empty and fileSize is 0.

{
  "reportId": "OREC366168819952398336",
  "status": "GENERATION_STARTED",
  "s3Key": "",
  "s3DownloadPath": "",
  "fileSize": 0,
  "fileName": "",
  "fileUrl": "",
  "generationDate": "2026-10-08T05:12:41.318Z",
  "startDate": "2026-09-30T21:00:00Z",
  "endDate": "2026-10-07T20:59:59Z",
  "clientTimezone": "UTC+3",
  "generatedBy": "john.doe",
  "transactionTypes": ["PAYMENT"]
}

Save the reportId, then check the report status.

📌
The report is generated in the background. Use the status and download steps to get the file.

Errors

HTTP code	Message example	What to do
400	`Period length is 45 days, which is invalid or exceeds the maximum allowed of 40 days`	Request a shorter period, or split it into several reports.
400	`At least one transaction type must be selected`	Pass at least one item in `transactionTypeAndStatus`.
400	Invalid date or timezone	Use `YYYY-MM-DD` dates and an IANA timezone.
403	`Access Denied to SA1234567890!`	Check that the token belongs to the owner of the account.
429	`A report for settlement account SA1234567890 is already being generated ...`	Wait until the previous report is `GENERATED` or `ERROR`.