Skip to main content

Reports API

The Reports API lets merchants access completed transaction reports programmatically. It's designed for reconciliation, accounting, analytics, and compliance — without exposing any public storage links. Two secure endpoints are provided: List Reports (filtered, paginated list of finished reports with a secure download URL) and Download Report (authenticated binary file download).

The dashboard already shows reports, but this API enables automated systems (ERP, BI tools, finance scripts) to fetch and download reports safely.

Boost Your Integration

Ottu offers SDKs and tools to speed up your integration. See Getting Started for all available options.

When to Use​

  • Automated reconciliation — pull transaction reports into your ERP or accounting system on a schedule.
  • Analytics pipelines — feed reports into BI tools for trend analysis, fraud detection, or financial reporting.
  • Compliance & audit — download reports for regulatory requirements with full audit trail.
  • Manual download fallback — when dashboard access is unavailable or you need programmatic access.

Setup​

info

If you don't pass date filters, the List Reports API returns the last 30 days of finished reports, sorted newest first.

Guide​

Workflow​

  1. Call List Reports to get available reports — filter by date, interval, or source.
  2. Pick a report from the results array.
  3. Extract download_action.url — a pre-signed, secure download URL with an embedded token.
  4. Call that URL with the same authentication headers to download the file as binary.

Report Sources​

Reports are generated in two ways:

  • Auto reports — scheduled daily, weekly, monthly, or yearly.
  • Manual reports — created on demand via the dashboard.

Visibility & Security​

  • A merchant can only see their own reports (instance-isolated).
  • Only finished reports are returned — in-progress reports are excluded.
  • No public or raw storage URLs are ever exposed.
  • Reports use encrypted_id to prevent ID enumeration.
  • Every download attempt is audit-logged (success or failure).

Download Security​

Download URLs are secured with multiple layers:

  • Token-based — download tokens are UUIDs cached in Redis, not direct file paths.
  • Time-limited — tokens expire after a configurable TTL.
  • User-bound — each token is tied to the authenticated user who requested the list.
  • Rate-limited — downloads are rate-limited per user to prevent abuse.
  • Ownership verification — the server verifies the user owns the report before serving.

File Formats & Delivery​

FormatContent-TypeDetails
CSVtext/csvUTF-8 encoded, comma-delimited
XLSXapplication/vnd.openxmlformats-officedocument.spreadsheetml.sheetStandard Excel format

For S3-backed storage, the download returns a 302 redirect to a pre-signed S3 URL. For local storage, the file is served via X-Sendfile header.

Step-by-Step​

1. List available reports​

curl -X GET "https://sandbox.ottu.net/b/api/v1/reports/files/?limit=10" \
  -H "Api-Key: your_private_api_key"

The response includes completed reports, each with a secure download_action.url. Use query parameters (see API Reference) to filter by date, interval, or source.

2. Download a report​

Use the download_action.url from the response:

curl -X GET "https://<ottu-url>/b/api/v1/reports/files/{token}/download/" \
  -H "Api-Key: your_private_api_key" \
  -o report.csv

The file is returned as binary (CSV or XLSX).

3. Handle errors​

HTTPWhen
200 + empty resultsNo reports match your filters
401Invalid or missing credentials
403Basic Auth user lacks report.can_view_report
429Rate limit exceeded — backoff and retry

API Reference​

List Transaction Reports​

List Transaction Reports

GET 
/b/api/v1/reports/files/

Retrieve a paginated list of completed transaction reports. Returns only finished reports, ordered by creation date (newest first). Each report includes a secure download_action URL for downloading.

Request​

Responses​

Last updated on

Best Practices​

Use API Key for automation​

API Key auth is more stable and doesn't require per-user permission management for system integrations.

Always filter by date​

Avoid pulling large histories unintentionally. Use created_after and created_before to fetch only the period you need.

Respect pagination​

Use limit and offset (or cursor) until next is null. Don't assume all results fit in one response.

Handle empty results​

A valid response can return zero reports:

{ "count": 0, "next": null, "previous": null, "results": [] }

Log download tracking​

Even though Ottu logs every download, your system should store the report ID, download time, and success state for your own audit trail.

Retry safely​

On 429 rate_limited, implement exponential backoff before retrying.

FAQ​

What's Next?​

  • Checkout API — Create payment transactions that appear in reports
  • Operations — Refund, capture, or void transactions
Last updated on