Exports & Reporting

Heron generates transfer reports asynchronously. Create a report with POST /v1/reports, poll GET /v1/reports/{reportId}, and request a download URL valid for up to 15 minutes from POST /v1/reports/{reportId}/download after the report reaches READY. Report creation requires an Idempotency-Key header; replaying the same key and request returns the original report.

Export workflow

1. Preview the export

Send the intended report body to POST /v1/reports/preview before creating it:

{
  "type": "TRANSFER_ACTIVITY",
  "format": "CSV",
  "detailLevel": "SUMMARY",
  "filters": {
    "from": "2026-08-01T00:00:00.000Z",
    "to": "2026-09-01T00:00:00.000Z",
    "timestampBasis": "CREATED_AT",
    "assetScope": "ALL",
    "includeFees": true
  }
}

The preview returns matchingTransferCount, outputRowCount, the active limits, and whether the request exceeds them. Previewing does not create a report.

2. Create the report

Send the same body to POST /v1/reports with a stable Idempotency-Key. Heron returns 202 Accepted and a report resource. Reuse the same key only when retrying the same logical export.

3. Wait for generation

Poll GET /v1/reports/{reportId} until the status is READY or FAILED. Continue polling the accepted report instead of creating replacements with new idempotency keys.

4. Download the artifact

When the report is READY, call POST /v1/reports/{reportId}/download. The returned URL is valid for up to 15 minutes, bounded by the report artifact expiry. Use the returned expiresAt. Generate a new URL if it expires while the artifact is still available; do not recreate the report.

Accepted reports remain PENDING until generation starts. Continue polling the same report; if it reaches FAILED, inspect its error code before retrying.

Output rows can outnumber transfers for CSV status-history and execution-path reports. For pain.002, outputRowCount is the number of transaction status entries. Counts reflect data at preview time and can change before generation begins. A preview within the limits does not guarantee that generation will succeed if the matching data grows before the report runs.

Every report records schemaVersion: heron.report.v1 and a format-specific profileVersion so integrations can pin their import mapping to a stable contract. An existing report retains its profile version if generation is retried.

Report artifacts expire after seven days. The report record remains available for audit and diagnostics after its artifact expires.

CSV Profiles

TRANSFER_ACTIVITY with SUMMARY creates one row per transfer. It keeps quoted and actual amounts in separate columns, includes the canonical transfer_purpose, classifies the destination as OWN_ACCOUNT_TRANSFER or BENEFICIARY_PAYMENT, and includes the ordered execution-provider names and customer-safe provider references.

TRANSFER_ACTIVITY with EXECUTION_PATH creates one row per provider leg. Each row repeats the transfer's canonical transfer_purpose. This profile is intended for investigation and detailed reconciliation across an aggregated execution path.

TRANSFER_STATUS_HISTORY with SUMMARY creates one row per transfer status transition in the selected UTC window and includes the canonical transfer_purpose. These reports require timestampBasis: STATUS_EVENT_AT. Execution-path detail is not available for status-history reports.

The current CSV profiles are heron.transfer_activity.v2, heron.transfer_execution_path.v2, and heron.transfer_status_history.v2. Version 2 adds the transfer_purpose column. Already-created version 1 reports keep their original layouts when they are generated or retried, so pinned imports do not change shape.

For transfer activity reports using STATUS_EVENT_AT, the summary status, reason, blocking party, and update timestamp come from the latest matching status event inside the requested window. This keeps historical reconciliation exports from being rewritten by later transfer transitions.

All report windows are half-open: the start is included and the end is excluded.

CSV exports never contain provider credentials, provider account identifiers, quote internals, raw requests or responses, or provider diagnostic payloads.

ISO 20022

The supported ISO profile is pain.002.001.03. It is available only for fiat summary transfer status-history reports and maps supported Heron statuses to ISO payment statuses.

Heron status	pain.002 transaction status
PENDING_SETUP, READY_TO_FUND, AWAITING_FUNDS	PDNG
IN_PROGRESS, IN_REVIEW	ACSP
COMPLETED	ACSC
FAILED, CANCELED	RJCT

Returned and refunded transfers are not relabeled as a different ISO status. Requests containing an unsupported status fail instead of producing a misleading status report. ISO requests must select at least one supported status explicitly. For each included transfer, the emitted status comes from its latest status event in the requested window; if that latest event is unsupported, generation fails rather than emitting an earlier, stale status.

Each included transfer must have paymentReferences supplied at transfer creation:

{
  "paymentReferences": {
    "sourceSystem": "sap-s4",
    "originalMessageId": "MSG-2026-00042",
    "originalMessageNameId": "pain.001.001.03",
    "originalPaymentInformationId": "PMT-2026-00042",
    "originalInstructionId": "INSTR-00042",
    "originalEndToEndId": "E2E-00042"
  }
}

These values must match the original payment instruction imported by the treasury or ERP system. Set filters.originalMessageId when creating the ISO report. One pain.002 document corresponds to one original message group; a status report without those identifiers cannot be reconciled reliably.

Compatibility

System	Recommended first profile	Notes
SAP S/4HANA	pain.002.001.03 or CSV	SAP supports pain.002 imports, but bank and implementation profiles must be tested with the customer.
Oracle Fusion Cloud ERP	pain.002.001.03 or CSV	Oracle documents this pain.002 version; bilateral bank/profile configuration still applies.
Kyriba	CSV, then customer-tested pain.002	Public profile requirements vary by bank and Kyriba configuration. Do not assume generic XML acceptance.
NetSuite	CSV	NetSuite payment-file support does not establish generic pain.002 import compatibility. Use a mapped CSV profile unless the customer's implementation confirms otherwise.

CSV is the default interoperable format. ISO compatibility is a profile claim, not a guarantee that every bank, ERP, or treasury configuration accepts the same file unchanged.

Permissions

Report reads and downloads require reports:read. Creating and retrying reports require reports:write. Because the dashboard export workflow creates, polls, and downloads a report, dashboard users need both permissions. The organization must also have the reports feature enabled.