> **Description:** Practical Python implementation examples.

# Report API: Sample scripts

Two Python scripts are available to help you work with the Report API: one that fetches real settlement data, and one that generates synthetic data for testing.

**NOTE**

These scripts are starting-point examples, not production-ready code.
They demonstrate the basic patterns for authentication and data retrieval, but do not include pagination, robust error handling, or retry logic.

## Prerequisites

- Python 3.x
- For the fetch script: install the `requests` library:

  ```shell
  pip install requests
  ```

- For the fetch script: API credentials (see [API keys](https://developer.vippsmobilepay.com/docs/knowledge-base/api-keys.md))

## Retrieve data from the Report API

This script authenticates, retrieves all your ledgers, then pulls both `funds` and `fees` entries for today from the Report API and saves them to a CSV file named by date (for example, `2026-03-03.csv`).

[Download fetch-report-api-data.py](https://developer.vippsmobilepay.com/downloads/report-api/fetch-report-api-data.py)

### Configure the script

Open the script and set the following variables before running it:

| Variable | Description |
|---|---|
| `USE_MIAMI_API` | Set to `True` for accounting partners using the MIAMI API; `False` for merchants using their own API keys. |
| `CLIENT_ID` | Your client ID. |
| `CLIENT_SECRET` | Your client secret. |
| `SUBSCRIPTION_KEY` | Your `Ocp-Apim-Subscription-Key`. Required for merchants (`USE_MIAMI_API = False`). |
| `MERCHANT_SERIAL_NUMBER` | Your merchant serial number. Required for merchants (`USE_MIAMI_API = False`). |

### Run the script

```shell
python3 fetch-report-api-data.py
```

The settlement data is saved to a CSV file named after today's date (for example, `2026-03-03.csv`).

### CSV columns

The output file contains one row per ledger entry with these columns:

| Column | API field |
|---|---|
| Reference (Vipps PSP) | `pspReference` |
| Time | `time` |
| Ledger Date | `ledgerDate` |
| Entry Type | `entryType` |
| Order ID/Reference (merchant) | `reference` |
| Currency | `currency` |
| Amount | `amount` |
| Balance Before | `balanceBefore` |
| Balance After | `balanceAfter` |
| Recipient Handle | `recipientHandle` |
| Message | `message` |
| Name | `name` |
| Masked Phone | `maskedPhoneNo` |

## Generate fake data

This script creates synthetic data that matches the shape of `GET /report/v2/ledgers/{ledgerId}/{topic}/dates/{ledgerDate}` responses. This is useful for testing data pipelines without connecting to the live API. It requires no external libraries and streams output to disk to avoid loading everything into memory at once.

[Download generate-fake-report-api-data.py](https://developer.vippsmobilepay.com/downloads/report-api/generate-fake-report-api-data.py)

### Output files

The script writes one gzipped JSON file per day for each topic:

- `out/funds/YYYY-MM-DD.json.gz`
- `out/fees/YYYY-MM-DD.json.gz`

### Arguments

| Argument | Default | Description |
|---|---|---|
| `--start` | *(required)* | Start date in `YYYY-MM-DD` format. |
| `--end` | *(required)* | End date in `YYYY-MM-DD` format. |
| `--payments` | `1000000` | Total number of payments to distribute across the date range. |
| `--out` | `./out` | Output directory. |
| `--ledger-id` | `302321` | Ledger ID to use in the generated data. |
| `--recipient-handle` | `NO:123455` | Recipient handle to use in the generated data. |
| `--currency` | `NOK` | Currency code. |
| `--net-settlement` | *(flag)* | Simulate net settlement: adds daily `fees-retained` entries (negative in `funds`, positive in `fees`) and a `payout-scheduled` when the balance is positive. If omitted, gross settlement is simulated with a monthly `fees-invoiced` entry on the last day of each month. |
| `--include-gdpr` | `0.10` | Probability (0-1) that a transaction includes GDPR fields (`name`, `message`, `maskedPhoneNo`). |
| `--seed` | `42` | Random seed for reproducible output. |
| `--tz` | `Z` | Timestamp suffix. |

### Example

```shell
python generate-fake-report-api-data.py \
  --payments 1000000 \
  --start 2025-10-01 \
  --end   2025-10-31 \
  --out   ./out \
  --ledger-id 302321 \
  --recipient-handle NO:123455 \
  --currency NOK \
  --net-settlement \
  --include-gdpr 0.12 \
  --seed 42
```

This creates sample data for 1,000,000 payments across October 2025, distributed by weekday (Fridays and Saturdays are slightly busier). It produces realistic mixes of entry types including captures, refunds, disputes, and corrections for both `funds` and `fees` topics.

> **Full site overview:** For every page in this documentation, read [https://developer.vippsmobilepay.com/llms.txt](https://developer.vippsmobilepay.com/llms.txt).