In order to access your consolidated settlement files, you will need to:

Merchant user login

Make a POST to log into the Settlement Reporting system and obtain an access token to access merchant settlement data and reports.

📘
Spreedly will provide the username and password to be used for the API call. This should be used as a daily login for merchant users to access settlement reports. A new token should be obtained when the previous one expires.
Unlike the Spreedly transactional API, Consolidated Settlement Reporting uses JWT (JSON Web Token)–based authentication aligned with OAuth 2.0 principles.

API Endpoint

POST /v1/auth/login

Example Request (cURL)

curl --location '/v1/auth/login' \
--header 'Content-Type: application/json' \
--data-raw '{
    "username": "User1",
    "password": "Test@123"
}'

Headers

Header	Value	Description
`Content-Type`	`application/json`	Media type of the request body

Request Fields

Field	Description
`username` (string, required)	The merchant user's username
`password` (string, required)	The merchant user's password

Example Response

{
  "status": "success",
  "data": {
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "token_type": "Bearer",
    "user": {
      "id": "user_456",
      "username": "User1",
      "merchant_id": "merchant_123",
      "role": "admin"
    }
  }
}

Response Fields

Field	Description
`access_token`	The authentication token scoped to the merchant user's permissions
`token_type`	Type of token associated with the access_token
`id`	Unique identifier of the user
`username`	The merchant user's username
`merchant_id`	Your merchant ID
`role`	Role assigned to the user based on permissions

Request a new settlement report

Make a POST to create a new settlement report configuration with scheduling, filtering, and webhook delivery options. Requires merchant user authentication.

For detailed information on each field value, view the settlement request field values guide

API Endpoint

POST /v1/settlement-reports

Example Request (cURL)

{
    "schedule_config": {
        "start_date": "12-02-2025",
        "end_date": "12-02-2025",
        "frequency": "once"
    },
    "webhook_config": {
        "url": "https://example.com"
    },
    "filter_config": {
        "filter_map": {
            "psp": [],
            "country": [""],
            "payment_method": [],
            "payment_method_type": [],
            "date_range": {
                "start_date": "2025-01-01",
                "end_date": "2025-01-31"
            }
        }
    }
}

Headers

Header	Value	Description
`Content-Type`	`application/json`	Media type of the request body
`X-Api-Key`	`Bearer {jwt_token}`	Your authentication token

Request Fields

Field	Type	Required	Description
`start_date`	string	yes	Report schedule start date (MM-DD-YYYY)
`end_date`	string	yes	Report schedule end date (MM-DD-YYYY)
`frequency`	string	yes	Report frequency: once, daily, weekly, monthly
`url`	string	yes	Webhook URL for report delivery
`psp`	array	no	Filter by payment service providers
`country`	array	no	Filter by country codes
`payment_method`	array	no	Filter by payment methods
`payment_method_type`	array	no	Filter by payment method types
`date_range`	object	yes	Transaction date range filter
`date_range.start_date`	string	yes	Filter start date (YYYY-MM-DD)
`date_range.end_date`	string	yes	Filter end date (YYYY-MM-DD)

Example Response

{
  "id": "report_789",
  "merchant_id": "merchant_123",
  "report_name": "Daily Settlement Summary",
  "frequency": "daily",
  "format": "csv",
  "status": "active",
  "created_at": "2024-01-15T12:00:00Z"
}

Response Fields

Field	Description
`id`	Unique identifier of requested report
`merchant_id`	ID of the merchant for this report configuration
`report_name`	Descriptive name for the report
`frequency`	Report frequency (e.g., "daily", "weekly", "monthly")
`format`	Report format (e.g., "csv")
`status`	Status of requested report
`created_at`	Date and time report was requested

Access settlement files

After requesting your SFTP credentials and receiving a completed status, access the file via the designated SFTP location.

📘
Consolidated files will be hosted and stored on Spreedly's SFTP server for 1 year.

Field mappings for each PSP can be found in the Normalization Field Mapping guide