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

All Consolidated Settlement Reporting APIs utilize a base URL of https://settlement-reporting.spreedly.com

Merchant user login

Authenticates a merchant user and returns an authentication token for accessing their merchant's settlement data and APIs.

📘
Spreedly will provide the username and password to be used for the API call. 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 {{baseURL}}/v1/auth/login

Header

Content-Type: application/json

Request details

Request

{
    "username": "user123",
    "password": "Test@123"
}

Request fields

Field	Type	Required	Description
`username`	string	yes	The merchant user's username
`password`	string	yes	The merchant user's password

Response details

Response

{
    "message": "Authenticated successfully",
    "token": "eyJhbGciOiJIUz...",
    "user": {
        "id": "123",
        "username": "user123",
        "email": "[email protected]",
        "role": "User",
        "merchant": {
            "id": "123",
            "name": "merchant123",
            "email": "[email protected]"
        }
    }
}

Response fields

Field	Description
`token`	The authentication token scoped to the merchant user's permissions. Utilize the `token` within the `merchantAuthToken` header for API authentication
`id`	Unique identifier of the user
`username`	The merchant user's username
`role`	Role assigned to the user based on permissions
`merchant_id`	Your merchant ID

Error responses

401 Unauthorized: Invalid username or password
401 Unauthorized - Deactivated User: Cannot Login Deactivated User please reactive user

Request a new settlement report

Creates a new settlement report configuration with scheduling, filtering, and webhook delivery options.

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

API endpoint

POST {{baseURL}}/v1/settlement-reports

Authentication

See the merchant user login section for information on how to obtain the authentication token.

Header

X-Api-Key: Bearer {{merchantAuthToken}}

Request details

Request

{
    "schedule_config": {
        "start_date": "2026-01-01",
        "end_date": "2026-12-31",
        "frequency": "daily"
    },
    "webhook_config": {
        "url": "https://example.com"
    },
    "filter_config": {
        "filter_map": {
        "psp": ["d_local", "payu", "mercado_pago"],
        "country": [],
        "payment_method": [],
        "payment_method_type": [],
        "date_range": { "start_date": null, "end_date":null}
        }
    }

}

Request fields

Object	Field	Type	Required	Description
`schedule_config`	`start_date`	string	yes	Start date in yyyy-mm-dd format
	`end_date`	string	conditional	End date in yyyy-mm-dd format
	`frequency`	string	yes	Report generation frequency. Values: once, daily, weekly, monthly
`webhook_config`	`url`	string	yes	Webhook URL to receive report notifications (must be valid HTTP/HTTPS URL)
	`token`	string	no	Bearer token for webhook authentication
	`webhook_username`	string	no	Basic auth username for webhook
	`webhook_password`	string	no	Basic auth password for webhook
`filter_config`	`psp`	array	no	Payment service providers
	`country`	array	no	ISO 3166-1 alpha-3 country codes
	`payment_method`	array	no	Payment methods
	`payment_method_type`	array	no	Card brands/types
	`date_range.start_date`	string	conditional	Data start date in yyyy-mm-dd format
	`date_range.end_date`	string	conditional	Data end date in yyyy-mm-dd format

📘
See filter map values here

Frequency rules

"once": Generates a single report immediately.
- start_date and end_date inside filter_config are required
- start_date and end_date inside schedule_config should be removed or set to null
"daily", "weekly", and "monthly":
- start_date and end_date inside schedule_config are required must be in the future
- start_date and end_date inside filter_config should be removed or set to null

📘
See more details on how to set frequency rules here

Response details

Response

{
    "message": "Settlement report config created successfully",
    "settlement_report_config": {
        "id": "123...",
        "status": "active",
        "user_id": "123...",
        "created_by": "user123",
        "webhook_url": "https://example.com",
        "schedule_config": {
            "start_date": "2026-01-21",
            "end_date": "2026-12-31",
            "frequency": "daily",
            "next_report_generation": "2026-01-21"
        },
        "filter_config": {
            "filter_map": {
                "date_range": {
                    "start_date": [],
                    "end_date": []
                },
                "psp": [],
                "country": [],
                "payment_method": [],
                "payment_method_type": []
            }
        }
    }
}

Response fields

Field	Description
`status`	Status of report configuration. Values: active, inactive
`id`	The unique identifier (UUID) of the settlement report configuration
`webhook_url`	Webhook URL to receive report notifications
`next_report_generation`	Date of next report to be expected

ℹ️
Make sure to retain the id value of the report configuration request for your records

Error responses

422 Unprocessable Entity: date_range with start_date and end_date is required when frequency is 'once'

Access settlement files

After requesting your SFTP credentials, creating a new report request and receiving a completed status via webhook, access the file via the SFTP file_path.

📘
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

Webhook details can be found here.

Making Changes to Scheduled Reports

In order to change a scheduled report, you will need to create a new report request and then delete the existing configuration. See how to update webhook settings here.

Delete a Settlement Report Configuration

Allows merchant users to remove report configurations that are no longer needed, stopping all future scheduled report generation and delivery for that configuration.

API endpoint

DELETE {{baseURL}}/v1/settlement-reports/{settlement_report_config_id}

Authentication

See the merchant user login section for information on how to obtain the authentication token.

Header

X-Api-Key: Bearer {{merchantAuthToken}}

Request details

Request

No request body required for this endpoint.

Response details

Response

{
    "message": "Settlement report config deleted successfully"
}

Error Responses

404 Not Found: Settlement report config not found
422 Unprocessable Entity: Status transition is invalid

📘
Deleting a report configuration is permanent and cannot be undone. All future scheduled report generation for this configuration will stop immediately.

Update settlement report webhook settings

Updates an existing settlement report configuration's webhook settings.

API endpoint

PUT {{baseURL}}/v1/settlement-reports/{settlement_report_config_id}

Authentication

See the merchant user login section for information on how to obtain the authentication token.

Header

X-Api-Key: Bearer {{merchantAuthToken}}

Request details

Request

{
  "webhook_config": {
    "url": "https://api.merchant.com/webhooks/new-endpoint",
    "token": "Bearer new_webhook_token",
    "webhook_username": "new_user",
    "webhook_password": "new_password"
  }
}

Request fields

Field	Type	Required	Description
`url`	string	no	Updated webhook URL
`token`	string	no	Updated bearer token for webhook authentication
`webhook_username`	string	no	Updated basic auth username
`webhook_password`	string	no	Updated basic auth password

Response details

Response

{
  "message": "Settlement report config updated successfully",
  "settlement_report_config": {
    "id": 1,
    "status": "active",
    "webhook_url": "https://api.merchant.com/webhooks/new-endpoint",
    "schedule_config": {
      "start_date": "2024-02-01",
      "end_date": "2024-12-31",
      "frequency": "daily",
      "next_report_generation": "2024-02-02T00:00:00Z"
    },
    "filter_config": {
      "filter_map": {
        "psp": ["payu", "mercado_pago"],
        "country": ["BRA", "ARG"]
      }
    }
  }
}

Error responses

404 Not Found: Settlement report config not found"
422 Unprocessable Entity: url is not a valid URL

📘
Only webhook configuration can be updated. Schedule and filter configurations cannot be modified after creation.

Show settlement report configuration

Retrieves detailed information about a specific settlement report configuration including schedule, frequency, delivery method, and filter settings.

API endpoint

GET {{baseURL}}/v1/settlement-reports/{settlement_report_config_id}

Authentication

See the merchant user login section for information on how to obtain the authentication token.

Header

X-Api-Key: Bearer {{merchantAuthToken}}

Request details

Request

No request body required for this endpoint.

Response details

Response

{
  "settlement_report_config": {
    "id": 1,
    "status": "active",
    "webhook_url": "https://api.merchant.com/webhooks/settlements",
    "schedule_config": {
      "start_date": "2024-02-01",
      "end_date": "2024-12-31",
      "frequency": "daily",
      "next_report_generation": "2024-02-02T00:00:00Z"
    },
    "filter_config": {
      "filter_map": {
        "psp": ["payu", "mercado_pago"],
        "country": ["BRA", "ARG"],
        "payment_method": ["credit_card", "debit_card"]
      }
    }
  }
}

Response fields

Field	Type	Description
`id`	integer	Unique identifier for the settlement report configuration
`status`	string	Current status of the configuration (active, inactive)

Error responses

404 Not Found: Settlement report config not found

List settlement report configurations

Retrieves a list of settlement report configurations based on scope (merchant or user) with pagination.

API endpoint

GET {{baseURL}}/v1/settlement-reports

Authentication

See the merchant user login section for information on how to obtain the authentication token.

Header

X-Api-Key: Bearer {{merchantAuthToken}}

Request details

Request

GET /v1/settlement-reports?scope=merchant&page=1&per_page=10

Query parameters

Parameter	Type	Required	Description
`scope`	string	yes	Scope of report configs to retrieve. Values: `merchant` (all configs for merchant) or `user` (configs created by current user)
`page`	integer	no	Page number for pagination (default: 1)
`per_page`	integer	no	Number of items per page (default: 25, max: 100)

Response details

Response

{
  "scope": "merchant",
  "pagination": {
    "current_page": 1,
    "per_page": 10,
    "total_pages": 2,
    "total_count": 15,
    "next_page": 2,
    "prev_page": null
  },
  "settlement_report_configs": [
    {
      "id": 1,
      "status": "active",
      "webhook_url": "https://api.merchant.com/webhooks/settlements",
      "schedule_config": {
        "start_date": "2024-02-01",
        "end_date": "2024-12-31",
        "frequency": "daily",
        "next_report_generation": "2024-02-02T00:00:00Z"
      },
      "filter_config": {
        "filter_map": {
          "psp": ["payu", "mercado_pago"],
          "country": ["BRA", "ARG"]
        }
      }
    },
    {
      "id": 2,
      "status": "active",
      "webhook_url": "https://api.merchant.com/webhooks/weekly",
      "schedule_config": {
        "start_date": "2024-01-01",
        "end_date": "2024-06-30",
        "frequency": "weekly",
        "next_report_generation": "2024-01-08T00:00:00Z"
      },
      "filter_config": {
        "filter_map": {
          "psp": ["d_local"]
        }
      }
    }
  ]
}

Error responses

422 Unprocessable Entity - Invalid Scope

{
  "error": "Invalid scope parameter",
  "details": "Scope must be either 'merchant' or 'user'"
}

List settlement reports

Retrieves generated report records based on scope (merchant or user) with pagination.

API endpoint

GET {{baseURL}}/v1/reports

Authentication

See the merchant user login section for information on how to obtain the authentication token.

Header

X-Api-Key: Bearer {{merchantAuthToken}}

Request details

Request

GET /v1/reports?scope=merchant&page=1&per_page=10

Query parameters

Parameter	Type	Required	Description
`scope`	string	yes	Scope of reports to retrieve. Values: `merchant` (all reports for merchant) or `user` (reports from configs created by current user)
`page`	integer	no	Page number for pagination (default: 1)
`per_page`	integer	no	Number of items per page (default: 25, max: 100)

Response details

Response

{
  "scope": "merchant",
  "pagination": {
    "current_page": 1,
    "per_page": 10,
    "total_pages": 5,
    "total_count": 48,
    "next_page": 2,
    "prev_page": null
  },
  "reports": [
    {
      "id": 1,
      "status": "completed",
      "created_at": "2024-02-01T06:00:00Z",
      "updated_at": "2024-02-01T06:15:00Z",
      "settlement_report_config_id": 1,
      "sftp_upload_success": true,
      "sftp_uploaded_file_path": "/merchants/acme/reports/2024-02-01_settlement.csv",
      "generation_errors": null,
      "metadata": {
        "records_count": 1250,
        "file_size_bytes": 245678
      },
      "raw_format": "csv",
      "psp_availability": {
        "payu": true,
        "mercado_pago": true
      },
      "created_by": "john.doe"
    },
    {
      "id": 2,
      "status": "failed",
      "created_at": "2024-02-02T06:00:00Z",
      "updated_at": "2024-02-02T06:05:00Z",
      "settlement_report_config_id": 1,
      "sftp_upload_success": false,
      "sftp_uploaded_file_path": null,
      "generation_errors": ["No data available for the specified date range"],
      "metadata": null,
      "raw_format": null,
      "psp_availability": {
        "payu": false,
        "mercado_pago": false
      },
      "created_by": "john.doe"
    }
  ]
}

Response fields

Field	Type	Description
`id`	integer	Unique identifier for the report generation
`status`	string	Current status (`pending`, `processing`, `completed`, `failed`)
`settlement_report_config_id`	integer	Associated settlement report config ID
`sftp_upload_success`	boolean	Whether the file was successfully uploaded to SFTP
`sftp_uploaded_file_path`	string	Path where the report file was uploaded
`generation_errors`	array	List of errors if generation failed
`metadata`	object	Additional information about the generated report
`raw_format`	string	Format of the raw data (e.g., csv)
`psp_availability`	object	Availability status of each PSP's data
`created_by`	string	Username who created the associated config

Error responses

422 Unprocessable Entity - Invalid Scope

{
  "error": "Invalid scope parameter",
  "details": "Scope must be either 'merchant' or 'user'"
}

403 Forbidden

{
  "error": "Merchant not found",
  "details": "This endpoint is only available for merchant users"
}

Show report

Retrieves detailed information about a specific generated report, including its associated settlement report configuration.

API endpoint

GET {{baseURL}}/v1/reports/{report_id}

Authentication

See the merchant user login section for information on how to obtain the authentication token.

Header

X-Api-Key: Bearer {{merchantAuthToken}}

Request details

Request

No request body required for this endpoint.

Response details

Response

{
  "report": {
    "id": 1,
    "status": "completed",
    "created_at": "2024-02-01T06:00:00Z",
    "updated_at": "2024-02-01T06:15:00Z",
    "settlement_report_config_id": 1,
    "sftp_upload_success": true,
    "sftp_uploaded_file_path": "/merchants/acme/reports/2024-02-01_settlement.csv",
    "generation_errors": null,
    "metadata": {
      "records_count": 1250,
      "file_size_bytes": 245678
    },
    "raw_format": "csv",
    "psp_availability": {
      "payu": true,
      "mercado_pago": true
    },
    "created_by": "john.doe",
    "settlement_report_config": {
      "id": 1,
      "status": "active",
      "created_at": "2024-01-15T10:00:00Z",
      "updated_at": "2024-01-15T10:00:00Z",
      "created_by": "john.doe",
      "schedule_config": {
        "start_date": "2024-02-01",
        "end_date": "2024-12-31",
        "frequency": "daily",
        "next_report_generation": "2024-02-03T00:00:00Z"
      },
      "webhook_config": {
        "url": "https://api.merchant.com/webhooks/settlements",
        "token": "[REDACTED]",
        "webhook_username": "webhook_user",
        "webhook_password": "[REDACTED]"
      },
      "filter_config": {
        "filter_map": {
          "psp": ["payu", "mercado_pago"],
          "country": ["BRA", "ARG"]
        }
      }
    }
  }
}

Error responses

404 Not Found

{
  "error": "Report not found",
  "details": "The requested report generation does not exist or you don't have access to it"
}

403 Forbidden

{
  "error": "Merchant not found",
  "details": "This endpoint is only available for merchant users"
}

Common response codes

Status Code	Description
200 OK	Request successful
201 Created	Resource created successfully
400 Bad Request	Invalid request parameters
401 Unauthorized	Missing or invalid authentication token
403 Forbidden	Insufficient permissions
404 Not Found	Resource not found
500 Internal Server Error	Server error occurred