Exports & Reporting

Heron generates transfer reports asynchronously. Create a report with POST /v1/reports, poll GET /v1/reports/{reportId}, and request a 15-minute download URL 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 persist or queue 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 15 minutes. Generate a new URL if it expires; do not recreate the report.

Accepted reports remain PENDING while they await generation. Heron automatically recovers missed dispatches and retries transient generation failures; deterministic validation or data errors move the report to FAILED with a stable error code. Clients should continue polling the report resource rather than retrying creation with a different idempotency key.

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 asynchronous generation begins. Report creation and generation independently enforce both limits, so API clients cannot bypass them by skipping preview.

Every report records schemaVersion: heron.report.v1 and a format-specific profileVersion so integrations can pin their import mapping to a stable contract. Generation uses the stored profile version rather than the latest implementation implicitly, preventing an in-flight or retried report from silently changing format.

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, 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. 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. These reports require timestampBasis: STATUS_EVENT_AT. Execution-path detail is not available for status-history reports.

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 first 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.