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

# Orders Report

> The CSV format for an orders file upload, with the required and optional fields, their types, and an example value for each column.

## File Format

* **Format:** Only **CSV** files are currently supported.

## Required Fields

| Field Name | Type | Description | Example |
| - | - | - | - |
| provider | string | Payment provider name (must be supported) | `stripe` |
| provider\_account | string | Provider account identifier | `acct_12345` |
| provider\_reference | string | Provider reference for the transaction | `ref_67890` |
| acquirer | string | Acquirer name | `acquirerX` |
| type | string | Transaction type: `capture`, `refund`, or `chargeback` | `capture` |
| currency | string | 3-letter ISO 4217 currency code | `USD` |
| amount | float | Transaction amount (must be > 0) | `100.50` |
| created\_at | string | RFC3339 timestamp | `2025-12-03T10:15:30Z` |
| order\_reference | string | Merchant order reference | `order_001` |

## Optional Fields

| Field Name | Type | Description | Example |
| - | - | - | - |
| timezone | string | IANA timezone name | `Europe/Berlin` |
| transaction\_reference | string | Merchant transaction reference | `txn_002` |
| holder\_reference | string | Merchant holder reference | `holder_003` |
| auth\_code | string | 6-digit authorization code | `123456` |
| arn | string | 23-digit Acquirer Reference Number | `12345678901234567890123` |
| rrn | string | 12-digit Retrieval Reference Number | `123456789012` |

## Value References

**`type` allowed values:** `capture`, `refund`, `chargeback`

## Validation Rules

* All required fields must be present and non-empty.
* `currency` must be a valid 3-letter ISO 4217 code.
* `amount` must be a positive number.
* `created_at` must be a valid RFC3339 timestamp.
* `auth_code`, `arn`, and `rrn` must match their respective digit lengths if provided.
* `timezone` must be a valid IANA timezone name if provided.

## Example CSV

```
provider,provider_account,acquirer,provider_reference,type,created_at,timezone,currency,amount,order_reference,transaction_reference,holder_reference,auth_code,arn,rrn
stripe,acct_123,stripe,pi_123,capture,2024-09-12T10:15:30Z,Europe/London,USD,123.45,order-001,txn-001,holder-001,123456,12345678901234567890123,123456789012
adyen,acct_456,adyen,psp_456,refund,2024-10-01T08:00:00Z,,EUR,10.00,order-002,,,,,
```


## Related topics

- [Upload files](/docs/analytics-and-reporting/upload-files/index.md)
- [Reports](/docs/analytics-and-reporting/reports/index.md)
- [Transactions report](/docs/analytics-and-reporting/reports/transactions.md)