> ## Documentation Index
> Fetch the complete documentation index at: /llms.txt
> Use this file to discover all available pages before exploring further.

# Statements

> Download a CSV of every movement on your wallets for a date range.

A statement is a CSV file listing the movements on your wallets between two dates, with the balance before and after each one. Use it to reconcile.

## Request a statement

Request statements in the [dashboard](https://app.payvehq.com), on the **Statements** page. Choose what to include and the date range.

| Option | Values |
| - | - |
| Type | `all`, `payouts`, `payins`, `conversions` |
| From, to | The first and last day to include |
| Format | `csv` |

> [!NOTE]
>
> An API key cannot request a statement. It can list and download the ones you have requested.

Payve builds the file in the background. A statement moves through these statuses:

| Status | Meaning |
| - | - |
| `pending` | Requested. |
| `processing` | Being built. |
| `completed` | Ready to download. |
| `failed` | Could not be built. Request it again. |

## List statements

`GET /v1/statements`

```bash
curl "$PAYVE_API_URL/v1/statements?limit=20&offset=0" \
  -H "x-api-key: $PAYVE_API_KEY"
```

```json
{
  "data": [
    {
      "id": 58,
      "type": "all",
      "fromDate": "2026-11-01T00:00:00.000Z",
      "toDate": "2026-11-17T00:00:00.000Z",
      "format": "csv",
      "status": "completed",
      "filename": "statement_all_2026-11-01_2026-11-17.csv",
      "rowCount": 214,
      "createdAt": "2026-11-18T07:00:00.000Z",
      "completedAt": "2026-11-18T07:00:04.000Z"
    }
  ],
  "total": 1
}
```

This list uses `limit` (default 20) and `offset`, not a cursor. `total` is the number of statements on this page.

`GET /v1/statements/{id}` returns one statement.

## Download a statement

`GET /v1/statements/{id}/download` returns the file as `text/csv`.

```bash cURL
curl "$PAYVE_API_URL/v1/statements/58/download" \
  -H "x-api-key: $PAYVE_API_KEY" \
  -o statement.csv
```

```javascript Node
import { writeFile } from 'node:fs/promises';

const res = await fetch(`${process.env.PAYVE_API_URL}/v1/statements/58/download`, {
  headers: { 'x-api-key': process.env.PAYVE_API_KEY },
});
if (!res.ok) throw new Error(`Statement not ready: ${res.status}`);
await writeFile('statement.csv', await res.text());
```

```python Python
import os, requests

res = requests.get(
    f"{os.environ['PAYVE_API_URL']}/v1/statements/58/download",
    headers={"x-api-key": os.environ["PAYVE_API_KEY"]},
)
res.raise_for_status()
with open("statement.csv", "w") as f:
    f.write(res.text)
```

A statement that is not `completed` yet returns `404` with the message `Statement not ready yet`. Wait and try again.

## The file

```csv
Date,Type,Reference,Direction,Amount,Currency,Balance Before,Balance After
```

| Column | Meaning |
| - | - |
| `Date` | When the movement was recorded. ISO 8601, UTC. |
| `Type` | What kind of movement it was. |
| `Reference` | The reference of the transaction behind it. |
| `Direction` | Whether money came in or went out. |
| `Amount` | The amount moved. |
| `Currency` | The currency of the row. |
| `Balance Before` | The wallet balance before the movement. |
| `Balance After` | The wallet balance after it. |

> [!WARNING]
>
> **Amounts in the CSV are in major units with decimals** (`50000.00`), not minor units. This is the
> one place Payve does not use minor units. Convert before you compare a statement with API amounts.

## Reconcile with it

**1. Request yesterday's statement each morning**

Choose type `all`.

**2. Match every row to your own records**

Match on `Reference`. Each of your payouts, pay-ins and conversions should have its rows, and
each row should match something you know about.

**3. Check the running balance**

Each row's `Balance After` should equal the next row's `Balance Before` in the same currency.

**4. Investigate anything unmatched**

Fetch the transaction through the API, then contact [support](/support.md) with its public id if it
still does not add up.

## When it fails

| Status | Cause | Fix |
| - | - | - |
| `404` | The statement does not exist or is not ready. | Check the id and the `status`. |
| `403` | The statement belongs to another account. | Use an id from your own list. |
