This document outlines the field values and definitions for the Consolidated Settlement Reporting request.

1. Filter map
2. Schedule vs date validation rules
3. Validation error responses
4. Webhook configuration

Create Settlement Report Config – Request Format

{
    "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}
        }
    }

}

Filter map

Only the following keys are permitted. Any unknown key will cause request failure.

• country
• payment_method
• payment_method_type
• psp
• date_range

All filters are applicable across the following PSPs:

• dLocal
• Mercado Pago
• PayU

Field rules

country

Filter transactions based on country. While all countries are supported in the filter, Mercado Pago and PayU only process LATAM transactions, so filtering outside LATAM will not return results for these PSPs.

Field Mapping by PSP

Type: Array of strings

Format: ISO 3166‑1 alpha‑3 country codes

Example:

"country": ["IND", "USA"]

payment_method

Filter transactions based on the high-level payment method used.

Field mapping by PSP

*PayU does not directly provide the payment method. Instead, a payment type is received and mapped internally.

Type: Array of strings

Allowed values:

• credit_card
• debit_card
• bank_transfer
• cash_payment
• instant_payment
• account_money
• atm
• prepaid_card
• qr
• direct_debit

Example:

"payment_method": ["credit_card", "QR"]

payment_method_type

Filter transactions based on specific card networks or payment brands. Supported values vary based on PSP.

Type: Array of strings

Allowed values:

See normalized values in table above.

Example:

"payment_method_type": ["visa", "mastercard"]

psp

Filter transactions specific to one or more PSPs.

Type: Array of strings

Allowed values:

• payu
• mercado_pago
• d_local

Example:

"psp": ["payu"]

date_range

Filter transactions based on the settlement date. Returns all settlements that occurred between the provided start date and end date (inclusive).

Field mapping by PSP

Type: Object

Required keys: start_date, end_date

Format: YYYY-MM-DD or null

Rule: start_date ≤ end_date

Example (non-empty):

"date_range": {
  "start_date": "2025-01-01",
  "end_date": "2025-01-31"
}

Example (empty but valid):

"date_range": {
  "start_date": null,
  "end_date": null
}

Complete Valid Example (With Filters)

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

Schedule vs date validation rules

📘

The default timezone for consolidated reports will be UTC +00:00.

Frequency-based Date Rules

The behavior of start_date and end_date depends on schedule_config.frequency.

1. frequency = "once"

• start_date and end_date inside schedule_config should be removed or set to `null
• start_date and end_date inside filter_config are required
  • start_date must be equal to or before end_date

Valid:

{
    "schedule_config": {
        "start_date": null,
        "end_date": null,
        "frequency": "once"
    },
    "filter_config": {
        "filter_map": {
        "date_range": { "start_date": "2026-01-15", "end_date":"2026-01-15"}
        }
    }
}

Invalid (missing dates):

    "filter_config": {
        "filter_map": {
        "date_range": { "start_date": null, "end_date":null}

2. frequency = "daily", "weekly", or "monthly"

• Report date range will be automatically be derived based on frequency
• start_date and end_date inside schedule_config are required and must be in the future
• start_date and end_date inside filter_config should be removed or set to null

Valid:

"schedule_config": {
        "start_date": "2026-01-15",
        "end_date": "2026-01-30",
        "frequency": "daily"
}
"filter_config": {
        "filter_map": {
        "date_range": { "start_date": null, "end_date":null}
        }

Invalid (dates should not be passed):

    "filter_config": {
        "filter_map": {
        "date_range": { "start_date": "2026-01-15", "end_date":"2026-01-30"}

Validation error responses

Invalid PSP

Request snippet:

"psp": ["stripe"]

Response – 422:

{
  "status": false,
  "error": ["Filter map invalid psp values: stripe"]
}

Invalid Country Code

Request snippet:

"country": ["IN"]

Response – 422:

{
  "status": false,
  "error": ["Filter map invalid ISO 3166-1 alpha-3 country codes: IN"]
}

Non‑Array Value

Request snippet:

"payment_method": "credit_card"

Response – 422:

{
  "status": false,
  "error": ["Filter map payment_method must be an array"]
}

Invalid Date Range

Request snippet:

"date_range": {
  "start_date": "2025-02-01",
  "end_date": "2025-01-01"
}

Response – 422:

{
  "status": false,
  "error": ["Filter map start_date cannot be after end_date"]
}

Unknown Filter Key

Request snippet:

"currency": ["INR"]

Response – 422:

{
  "status": false,
  "error": ["Filter map contains invalid keys: currency"]
}

Webhook configuration

The merchant should include the url where Spreedly should send the webhook in order to receive the report status and SFTP path. View request fields for optional webhook request fields. Additional details available in the webhook can be found here.

📘

If additional filter values are required, please contact your Spreedly Account Executive