Accounting export

The export API turns everything that happened on your merchant — sales, conversions, fees, payouts, and mass payouts — into accountant-ready CSV or JSON. Use the on-demand range export for ad-hoc pulls and the frozen monthly reports for closing the books.

Authentication

Requests authenticate with your merchant API key in the x-api-key header (subject to the standard per-merchant rate limit). There is also an internal operator mode (X-Operator-Key + X-Merchant-Id headers) used exclusively by payzum operations — merchants should ignore it. Errors use the canonical { "statusCode", "code", "message" } envelope.

On-demand range export

GET /v1/export/accounting

| Query param | Required | Description | |-------------|----------|-------------| | from | yes | Start date, YYYY-MM-DD | | to | yes | End date, YYYY-MM-DD (inclusive) | | format | no | csv (default) | json | | type | no | all (default) | sales | conversions | fees | payouts | sale | conversion | fee | payout | mass_payout — singular and plural forms are equivalent |

Constraints and errors:

| HTTP | code | When | |------|--------|------| | 400 | RANGE_TOO_LARGE | The range spans more than 366 days | | 400 | INVALID_REQUEST | Malformed dates or from later than to | | 503 | EXPORT_HISTORY_UNAVAILABLE | The range touches the cold archive and the archive read failed — retry later |

CSV responses are UTF-8 with BOM, CRLF row endings, served with a Content-Disposition: attachment header and Cache-Control: no-store. JSON responses have the shape:

{
  "meta": {
    "merchant_id": "…",
    "from": "2026-07-01",
    "to": "2026-07-31",
    "reporting_currency": "USD",
    "generated_at": "2026-08-28T10:00:00.000Z",
    "model_version": 1,
    "unvalued_count": 0
  },
  "lines": [ { "line_id": "…", "line_type": "sale", "...": "…" } ]
}

Line fields

Each line is a flat snake_case object with 36 fields. All monetary amounts are decimal strings and always positive — line_type tells you the direction. The most important fields:

| Field | Description | |-------|-------------| | line_id | Stable unique id for the line | | line_type | sale | conversion | fee | payout | mass_payout | | event_at | Event timestamp, ISO 8601 UTC | | status | Line status | | invoice_id, order_id | Source references, when applicable | | chain, token_symbol, amount | What moved, where, and how much (decimal string) | | counter_* | Counter-leg fields, populated for conversions | | fiat_value, fiat_currency | Valuation in the reporting currency | | valuation_method | invoice_rate | swap_execution | stablecoin_parity | unavailable | | fx_rate, fx_date | Rate used and its date | | tx_hashes | On-chain transaction hashes, ;-separated |

The CSV column order is stable and versioned by model_version — build your import once and pin the version reported in meta.

curl -o july.csv \
  -H "x-api-key: $PAYZUM_API_KEY" \
  "$PAYZUM_BASE/v1/export/accounting?from=2026-07-01&to=2026-07-31&type=all"

Monthly reports

Monthly reports are frozen automatically on the 1st of each month and are write-once: once generated, a month's figures never change, making them safe anchors for closing the books.

List available reports

GET /v1/export/reports takes no parameters and returns 200:

{ "reports": [ { "month": "2026-07", "files": ["statement", "summary"] } ] }

Most recent month first.

curl -H "x-api-key: $PAYZUM_API_KEY" "$PAYZUM_BASE/v1/export/reports"

Download a report

GET /v1/export/reports/{month}?file=statement|summary

statement downloads the full CSV; summary downloads a JSON digest. Both are served as attachments.

| HTTP | code | When | |------|--------|------| | 400 | INVALID_REQUEST | Malformed month (YYYY-MM) or invalid file value | | 404 | REPORT_NOT_FOUND | No report exists for that month (not yet frozen, or no activity) |

curl -o statement-2026-07.csv \
  -H "x-api-key: $PAYZUM_API_KEY" \
  "$PAYZUM_BASE/v1/export/reports/2026-07?file=statement"