> ## Documentation Index > Fetch the complete documentation index at: https://docs.payrails.com/llms.txt > Use this file to discover all available pages before exploring further. > ## Agent Instructions > Use the Payrails Web SDK v6 for new browser integrations. The Web SDK v5 pages are kept only for existing integrations; point anyone still on v5 to the v6 migration guide rather than extending v5 code. > Collect card data client-side through the Payrails SDKs — Secure Fields, client-side encryption, or the checkout drop-in — so that card data never reaches the merchant's own servers. Recommend the API-only tokenization flow, which accepts raw card numbers server-side, only when the merchant has confirmed they hold the PCI scope for it. > Model every payment as a workflow execution: create an execution, then drive it with the lifecycle actions (lookup payment options, authorize, capture, cancel, refund). Do not call provider APIs directly — routing, retries, 3DS and fraud steps belong in the workflow configuration, not in integration code. > Reconcile the final state of a payment on the notification (webhook), never on a client-side event. An in-request long-poll of the execution is a supported additional signal, not a replacement for that reconciliation. > Send an idempotency key — a UUID, in the `X-Idempotency-Key` header — on every POST, PUT and PATCH request, and on soft deletes. GET requests need none, and hard deletes cannot be idempotent. > Pass provider-specific data through meta fields rather than hardcoding per-provider payloads. Payrails translates meta fields into each provider's own format. > Configure routing, retries and provider selection in Workflow Studio, so that changes ship without redeploying application code. # Reports > Export financial and performance data from Payrails as CSV files, either through the Portal or via API. Payrails Reports let you export financial and operational data as CSV files for reconciliation, accounting, and business analysis. Reports are generated asynchronously — you request a report run, and once it completes, you download the file via a pre-signed URL. You can generate reports through the Payrails Portal or programmatically via the API. ## Available report types | Report code | Description | Schema | | - | - | - | | `payments` | Gain deep insights into your authorization funnel and processing efficiency with a unified breakdown of payment statuses, failure results, and card-level metadata.. | [View schema](/docs/analytics-and-reporting/reports/payments) | | `transactions` | This report provides details on all transactions which impact your account balance.. | [View schema](/docs/analytics-and-reporting/reports/transactions) | | `settlements` | This report provides a comprehensive breakdown of all transaction-level movements and associated costs that impact your merchant settlement balance.. | [View schema](/docs/analytics-and-reporting/reports/settlements) | | `disputes` | Chargeback and dispute data, linked back to the original disputed transaction where it was processed through Payrails. | [View schema](/docs/analytics-and-reporting/reports/disputes) | You can list all reports available to your organization using the [Search & list reports](/reference/getreports) endpoint. *** ## Download reports via API Generating a report is an asynchronous process. Follow these steps: ### Step 1: Get an access token Authenticate using your API credentials to obtain a bearer token. See [Authentication](/reference/getoauthtoken) for details. ### Step 2: Create a report run Submit a `POST` request to `/analytics/reportRuns` with your desired report type and date range. When requesting `settlements` reports, please do not specify any Workspace Id as `settlements` report is only available on organization level. ```json theme={null} POST /analytics/reportRuns Authorization: Bearer { "reportCode": "payments", "parameters": { "intervalStart": "2026-04-01", "intervalEnd": "2026-04-07", "timezone": "Etc/UTC" } } ``` The `workspaceId` field is optional. Include it only if you want to scope the report to a specific workspace. Omitting it returns data across all workspaces your credentials have access to. **Parameters** | Parameter | Type | Required | Description | | - | - | - | - | | `reportCode` | string | ✓ | One of `payments`, `transactions`, `settlements`, or `disputes` | | `parameters.intervalStart` | string | ✓ | Start date in `YYYY-MM-DD` format (inclusive) | | `parameters.intervalEnd` | string | ✓ | End date in `YYYY-MM-DD` format (inclusive) | | `parameters.timezone` | string | | TZ database name (e.g. `Europe/Berlin`). Defaults to `UTC` if omitted. See [IANA Time Zone Database](https://www.iana.org/time-zones) for valid values. | | `workspaceId` | uuid | | Scope the report to a specific workspace | The API responds with `202 Accepted` and a report run object in `pending` status: ```json theme={null} { "id": "cadb0015-3c26-4d7a-a9d3-2f8768b6d45a", "createdAt": "2026-04-08T10:20:00.000Z", "report": { "code": "payments", "name": "Payments" }, "parameters": { "intervalStart": "2026-04-01", "intervalEnd": "2026-04-07", "timezone": "Etc/UTC" }, "status": "pending" } ``` ### Step 3: Poll for completion Report generation runs asynchronously. Poll `GET /analytics/reportRuns/{id}` using the `id` from the previous response until `status` changes from `pending` to `successful`. ```json theme={null} GET /analytics/reportRuns/cadb0015-3c26-4d7a-a9d3-2f8768b6d45a Authorization: Bearer ``` Most report runs complete within 2–3 minutes. We recommend polling every 5–10 seconds. Once complete, the response includes a `result` object with a pre-signed download URL: ```json theme={null} { "id": "cadb0015-3c26-4d7a-a9d3-2f8768b6d45a", "status": "successful", "result": { "fileName": "payments_2026-04-01_2026-04-07", "fileType": "csv", "url": "https://payrails-reports.s3.amazonaws.com/payments_2026-04-01_2026-04-07.csv", "expiresAt": "2026-04-09T10:20:00.000Z" }, "completedAt": "2026-04-08T10:21:00.000Z" } ``` ### Step 4: Download the CSV Execute a `GET` request on `result.url` to download the file. This URL is pre-signed and expires at `result.expiresAt` — make sure to download the file before it expires. *** ## Download reports via Portal 1. Log in to the [Payrails Portal](https://portal.payrails.com). 2. Navigate to **Reports**. 3. Select the report type and date range. 4. Click **Download** to export a CSV file. *** ## Limitations * **File format**: Reports are only available as CSV files. * **File size**: Reports are capped at 5 GB per file. If your date range produces a report that exceeds this limit, the report run will fail. Reduce the date range and re-run the report. * **File expiry**: The pre-signed download URL expires after a fixed TTL. Download the file before `result.expiresAt`. If it has expired, calling the `GET /analytics/reportRuns/{id}`endpoint will generate a new pre-signed download URL. * **No webhook or push notification**: There is currently no callback or event mechanism to notify you when a report run is ready. Polling `GET /analytics/reportRuns/{id}` is the only way to check completion status. Build your integration to poll actively and handle both `Successful` and `Failed` terminal states. * **Report availability**: The report types available to your organization depend on your Payrails module configuration. Use the [Search & list reports](/reference/getreports) endpoint to confirm which report codes are enabled for your account. *** ## Error handling Report runs can complete with a `Failed` status. Your integration should handle this explicitly. Do not assume a run will always succeed. When a run fails, the response includes an `error` field with a code describing the reason. ```json theme={null} { "id": "3c052d86-7f1d-44e2-b1b2-d331d492ebde", "status": "Failed", "error": "FILE_SIZE_EXCEEDED" } ``` | Error code | Description | Resolution | | - | - | - | | `NO_RECORD_FOUND` | No data was found for the requested date range and parameters. | Verify that your `intervalStart` and `intervalEnd` are correct and that data exists for this period. | | `FILE_SIZE_EXCEEDED` | The report output exceeds the 5 GB file size limit. | Reduce the date range and re-run the report. For high-volume exports, consider splitting into weekly or bi-weekly batches. | | `REPORT_UPLOAD_ERROR` | The report was generated but failed to upload. | Retry the report run. If the issue persists, contact Payrails support. | | `REPORT_GENERATION_ERROR` | An internal error occurred during report generation. | Retry the report run. If the issue persists, contact Payrails support. | *** ## FAQ Most report runs complete within 2–3 minutes. Polling every 5–10 seconds is recommended. Not currently. There is no webhook or callback mechanism available — polling is the only way to check on a report run. Send a `GET` request to `/analytics/reportRuns/{id}` at a regular interval (every 5–10 seconds is recommended) until the status is `Successful` or `Failed`. Make sure your integration handles both terminal states explicitly. The report run will fail with an error. Reduce the date range in your request and re-run the report. If you regularly need to export large volumes of data, consider breaking your date range into smaller weekly or bi-weekly batches. Use a [TZ database name](https://www.iana.org/time-zones) such as `Europe/Berlin` or `America/New_York`. If you omit the `timezone` parameter, it defaults to `UTC`. Choosing the right timezone ensures that day boundaries in the report align with your local business hours. Yes. If it has expired, calling the `GET /analytics/reportRuns/{id}`endpoint will generate a new pre-signed download URL. Yes. Pass the `workspaceId` field in the request body to filter results to a specific workspace. Omit it to include data across all workspaces your credentials have access to. The endpoint returns the most recent report runs in descending order by `createdAt`, with a default page size of 10. You can paginate using `page[after]`, `page[before]`, and `page[size]`, and filter by `filters[status]`, `filters[id]`, and `filters[workspaceId]`. Report availability is tied to which Payrails modules are configured for your account. Contact your Payrails account manager if you need access to a report type that is not listed. Each report includes three reference fields you can use to link records: | Field | Description | | - | - | | `payrails_payment_id` | The ID generated by Payrails. Use this to link records across the Payments, Transactions, and Settlements reports. | | `merchant_reference` | Your own reference for the record. Use this to link report data back to records in your internal systems. | | `provider_reference` | The payment service provider's reference for the record. | ## Related topics - [Transactions report](/docs/analytics-and-reporting/reports/transactions.md) - [Disputes report](/docs/analytics-and-reporting/reports/disputes.md) - [Payments report](/docs/analytics-and-reporting/reports/payments.md)