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 | bankcsv | ofx — see Importing into your accounting software | | flavor | no | 3col (default) | 4col — statement-CSV column shape, ignored unless format=bankcsv | | dateFormat | no | iso (default) | dmy | mdy — statement-CSV date order, ignored unless format=bankcsv | | 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"

Importing into your accounting software

csv and json give you the full line model, which is what an accountant reconciles against. To load the same period into your accounting software, use one of the two statement formats — they describe the movements on a crypto clearing account, which is the shape every one of these tools imports.

| Your software | Use | Why | |---|---|---| | Xero, Zoho Books, Odoo | format=ofx | They ingest OFX natively — upload the file as-is, no column mapping | | QuickBooks Online | format=bankcsv&dateFormat=dmy | Import under Transactions → Bank transactions → Upload from file. Intuit's CSV guide documents dd/mm/yyyy, so that is what the dashboard sends; confirm the date format in the upload wizard | | Alegra | format=bankcsv&dateFormat=dmy | Alegra maps columns on its own upload screen but requires dd/mm/aaaa dates | | Anything else | format=bankcsv | A plain Date, Description, Amount statement |

format=quickbooks still works as an alias of bankcsv and returns identical bytes.

What the movements mean

| Line type | Direction | Why | |-----------|-----------|-----| | sale | money in | Customer payment received | | fee | money out | Payzum fee — a deductible expense | | payout, mass_payout | money out | Settled to your own wallet | | conversion | two entries that net to zero | A swap disposes of one asset and acquires another — in many jurisdictions a taxable disposition, so your accountant must see both legs |

Because the signs follow the same formula as the settlement summary, the clearing account's balance over a range equals the Net figure shown on the reports page for that same range — that equality is your reconciliation check. In OFX it is written straight into LEDGERBAL.

Every entry carries the line's stable id: in OFX as the FITID (so re-importing an overlapping period is a no-op — importers deduplicate on it), and in CSV at the end of the description in brackets, e.g. [sale:pzi_abc], with #out/#in for the two conversion legs.

For the statement CSV, pick the column shape your import wizard expects with flavor:

• 3col (default) — Date,Description,Amount, negative amounts for money out.
• 4col — Date,Description,Credit,Debit, both unsigned, with the unused side left empty.

# OFX for Xero / Zoho Books / Odoo
curl -o july.ofx \
  -H "x-api-key: $PAYZUM_API_KEY" \
  "$PAYZUM_BASE/v1/export/accounting?from=2026-07-01&to=2026-07-31&format=ofx"
 
# Statement CSV for QuickBooks Online
curl -o july.csv \
  -H "x-api-key: $PAYZUM_API_KEY" \
  "$PAYZUM_BASE/v1/export/accounting?from=2026-07-01&to=2026-07-31&format=bankcsv"

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"