> ## 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.

# Upload files

> Send your own files to Payrails through the file upload API or the Portal, to extend the analytics data set and feed reconciliation.

In order to extend your data set with us directly we provide you with the option to upload files. These files are processed to enhance our data models and improve the accuracy of visualizations and insights available through our analytics tools. This option also gives ability to share files that are specifically needed in order to run our reconciliation product for you.

You can upload files in the following ways

* Upload files programmatically using our FileUpload API
* *Upload files through the Portal view (coming soon)*

Supported Files

* Generic transactions- or order files
* Adyen reports
* Checkout reports

## Structure Overview

To ensure successful processing, please adhere to the following specifications:

* **Format:** Only **CSV** files are currently supported.
* **Size Limit:** Maximum **5GB** per file.
* **Number Format:** In order to prevent possible ambiguities in the numbers interpretation, we are restricting the format to only support **decimal dot separators** in the files that are being uploaded.
* **Schema:** Files must follow the same schema as defined in our Orders Report [orders-report#/](/docs/analytics-and-reporting/upload-files/orders-report)

## Upload files via API - How It Works

1. **Request an Upload URL**

   Call the `POST /analytics/files/upload` endpoint to request a temporary, pre-signed S3 URL. This URL acts as a secure, one-time gateway to our storage. Request Body as below:

   ```
   {
     "datasetType": "ordersV1",
     "file": {
       "name": "merchant_orders_2026-01-01.csv",
       "type": "csv"
     }
   }
   ```

2. **Upload Your File (Technical Implementation)**

   Once you have the pre-signed URL, you can upload your data file using a standard HTTP `PUT` request.

   **Using curl:** For a quick implementation or testing, you can use the following `curl` command. We recommend using the `--write-out` flag during testing to verify the HTTP status code returned by the server.

   ```bash theme={null}
   curl --request PUT \
     --upload-file '{your_file_path}' \
     '{presigned_url}' \
     --write-out "\nHTTP_STATUS:%{http_code}\n"
   ```

   * **Note:** The `-write-out` portion is optional but highly useful for debugging; a successful upload will return an `HTTP 200`.
   * **Expiration:** The pre-signed URL is valid for **1 hour**. If the upload does not start within this window, you must request a new URL.

3. **Processing & Validation**

   After the upload is complete, our system automatically begins validation in the background. We check the file for structural integrity and header alignment.

4. **Check File Status**

   Since large files (up to 5GB) may take time to process, you can monitor the progress programmatically.

   * **Endpoint:** `GET /analytics/files/{id}`
   * **Details:** Retrieve the current processing status (`Available`, `Processing`, `Imported`, `Completed`, or `Failed`) and view import statistics once finished.
     * **Available:** The file has been successfully validated and is ready to be imported.
     * **Processing:** The system is currently validating or parsing the file.
     * **Imported:** The file has been successfully imported and analysed.
     * **Completed:** The final state of a successful process, indicating that all data has been fully processed and is now Available for reporting.
     * **Failed:** An error occurred during ingestion.

5. **Data Integration & Visualization**

   Once the status is marked as Complete, your data is automatically merged into our analytics engine where we further process it. Once processing is complete, your custom data will now power your dashboards, providing a unified view of your performance and reconciliation insights.

<Note>
  **Note on Performance**

  Files containing large volumes of data may take
  longer to process and visualize. We recommend monitoring the file status via
  the API for high-volume uploads.
</Note>


## Related topics

- [Upload evidence files](/reference/uploaddisputeevidence.md)
- [Get a URL for file upload.](/reference/fileupload.md)
- [Orders Report](/docs/analytics-and-reporting/upload-files/orders-report.md)