Settlement reports

How Safepay Raast creates and tracks settlement report exports.

Safepay lets you generate settlement report exports so your team can reconcile settlement activity. Report exports are asynchronous: you seed a report request, and our settlement engine processes it in the background.

How settlement report exports work

Stage	What happens
Seed report request	You seed a report export request for an aggregator settlement scope.
Processing	Safepay queues and prepares the file in the background.
Read export	You fetch the export record to check status and file metadata.
Download file	Once completed, download the file from the URL returned in the export payload.

Create a settlement report export

1. Seed report request

   Call POST /v1/aggregators/{{aggregator_id}}/settlements/report-exports with your export filters.

2. Track export status

   Poll GET /v1/aggregators/{{aggregator_id}}/settlements/report-exports/{{report_export_id}} until processing is completed.

3. Download and reconcile

   Download the exported file and reconcile settlements in your reporting workflow.

cURL

curl --request POST "{{base_url}}/v1/aggregators/{{aggregator_id}}/settlements/report-exports" \
  --header "X-SFPY-AGGREGATOR-SECRET-KEY: {{secret_key}}" \
  --header "Content-Type: application/json" \
  --data '{
    "request_id": "{{request_id}}",
    "from_date": "2026-04-01",
    "to_date": "2026-04-15",
    "format": "CSV"
  }'

Report exports are generated asynchronously. Keep polling the read endpoint until status indicates REPORT_STATUS_SUCCEEDED, then use the returned file URL.

List settlement report exports

Lists report exports for auditing.

cURL

curl --request GET "{{base_url}}/v1/aggregators/{{aggregator_id}}/settlements/report-exports?limit=20&offset=0" \
  --header "X-SFPY-AGGREGATOR-SECRET-KEY: {{secret_key}}"

Read a settlement report export

Use this endpoint to retrieve the latest state of one export, including readiness and file details.

cURL

curl --request GET "{{base_url}}/v1/aggregators/{{aggregator_id}}/settlements/report-exports/{{report_export_id}}" \
  --header "X-SFPY-AGGREGATOR-SECRET-KEY: {{secret_key}}"

Key endpoints

Endpoint	Purpose
POST /v1/aggregators/{{aggregator_id}}/settlements/report-exports	Seed a settlement report export request.
GET /v1/aggregators/{{aggregator_id}}/settlements/report-exports	List settlement report export requests.
GET /v1/aggregators/{{aggregator_id}}/settlements/report-exports/{{report_export_id}}	Read one settlement report export request.

See also

• Ledger
• Webhooks