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": "2025-12-02",
    "end_date": "2025-12-02",
    "frequency": "once"
  },
  "webhook_config": {
    "url": "<https://example.com/webhook">
  },
  "filter_config": {
    "filter_map": {
      "psp": [],
      "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

Mercado_Pago country codes

The official API endpoint GET https://api.mercadolibre.com/sites returns the full list of supported sites (site codes + metadata). developers.mercadolibre.com.ni+1

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:

• american_express
• argencard
• cabal
• caixa_virtual_debit
• cmr
• codensa
• creditel
• cencosud
• diners
• diners_club
• elo
• hipercard
• lider
• magna
• maestro
• naranja
• oca
• presto
• redcompra
• shopping
• tarjeta_shopping
• visa
• mastercard

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"

• schedule_config.start_date is required
• schedule_config.end_date is required
• start_date must be equal to or before end_date

Valid:

"schedule_config": {
  "frequency": "once",
  "start_date": "2025-12-02",
  "end_date": "2025-12-02"
}

Invalid (missing dates):

"schedule_config": {
  "frequency": "weekly"
}

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

• schedule_config.start_date must NOT be sent
• schedule_config.end_date must NOT be sent
• Report date range will be automatically derived based on frequency

Valid:

"schedule_config": {
  "frequency": "weekly"
}

Invalid (dates should not be passed):

"schedule_config": {
  "frequency": "monthly",
  "start_date": "2025-12-01",
  "end_date": "2025-12-31"
}

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 report status and SFTP path.