Skip to content

Open-source personal finance manager. Self-hosted, privacy-first.

fix(pluggy): date future installments in the month they are billed (#1111)

Gustavo Marques da Silva528f6d81823c
diff --git a/backend/app/providers/pluggy.py b/backend/app/providers/pluggy.py
index dae0bfb0..d90e4e19 100644
--- a/backend/app/providers/pluggy.py
+++ b/backend/app/providers/pluggy.py
@@ -1,4 +1,5 @@
import asyncio
+import calendar
import hashlib
import json
import logging
@@ -67,6 +68,14 @@ def _compe_from_transfer_number(transfer_number) -> Optional[str]:
return code.zfill(3) if code.isdigit() else None
+def _add_months(d: date, months: int) -> date:
+ """Advance a date by N months, clamping the day to the target month's length."""
+ month_index = d.month - 1 + months
+ year = d.year + month_index // 12
+ month = month_index % 12 + 1
+ return date(year, month, min(d.day, calendar.monthrange(year, month)[1]))
+
+
# Public, community-maintained mirror of the Bacen (Central Bank) COMPE
# participant registry — free, no API key, no rate limits seen in practice.
# https://brasilapi.com.br/api/banks/v1/{code}
@@ -620,6 +629,24 @@ class PluggyProvider(BankProvider):
inst_purchase_date = date.fromisoformat(str(inst_purchase_date_raw)[:10])
except ValueError:
inst_purchase_date = None
+ # Mercado Pago reports every installment not billed yet
+ # with the purchase timestamp as its date, so a 10x
+ # purchase lands whole in the month it was made. The
+ # tell is `date` being an exact copy of `purchaseDate`,
+ # time included: connectors that schedule installments
+ # (Nubank) send a date of their own, even on the same
+ # day. Such a row moves to the purchase day N-1 months
+ # on, where Nubank puts the same installment. Posted rows
+ # are never moved: Itaú sends billed installments with a
+ # purchaseDate equal to their own charge date.
+ if (
+ status == "pending"
+ and isinstance(inst_number, int)
+ and inst_number > 1
+ and inst_purchase_date is not None
+ and txn.get("date") == inst_purchase_date_raw
+ ):
+ txn_date = _add_months(inst_purchase_date, inst_number - 1)
inst_total_amount_dec = (
Decimal(str(abs(inst_total_amount)))
if inst_total_amount is not None
diff --git a/backend/tests/test_providers_pluggy.py b/backend/tests/test_providers_pluggy.py
index 1bb6840c..863f82f0 100644
--- a/backend/tests/test_providers_pluggy.py
+++ b/backend/tests/test_providers_pluggy.py
@@ -286,6 +286,85 @@ async def test_parser_missing_purchase_date_only():
assert tx.installment_purchase_date is None
+# ---------------------------------------------------------------------------
+# Future installments reported at the purchase date (Mercado Pago)
+# ---------------------------------------------------------------------------
+
+
+def _installment(number: int, total: int, txn_date: str, purchase_date: str) -> dict:
+ return {
+ "id": f"tx-{number}",
+ "description": "MERCADOLIVRE*MERCADOLIVRE",
+ "amount": -56.99,
+ "date": txn_date,
+ "type": "DEBIT",
+ "status": "PENDING",
+ "creditCardMetadata": {
+ "installmentNumber": number,
+ "totalInstallments": total,
+ "purchaseDate": purchase_date,
+ },
+ }
+
+
+async def test_future_installment_at_purchase_date_moves_to_its_month():
+ """Installment 5 of a 6 June purchase belongs in October, not June."""
+ result = await _fetch([
+ _installment(5, 10, "2026-06-06T13:26:40.000Z", "2026-06-06T13:26:40.000Z"),
+ ])
+ assert result[0].date == date(2026, 10, 6)
+ assert result[0].installment_purchase_date == date(2026, 6, 6)
+
+
+async def test_future_installment_crosses_into_the_next_year():
+ result = await _fetch([
+ _installment(18, 18, "2025-11-01T14:49:23.000Z", "2025-11-01T14:49:23.000Z"),
+ ])
+ assert result[0].date == date(2027, 4, 1)
+
+
+async def test_future_installment_day_is_clamped_to_a_shorter_month():
+ result = await _fetch([
+ _installment(2, 3, "2026-01-31", "2026-01-31"),
+ ])
+ assert result[0].date == date(2026, 2, 28)
+
+
+async def test_first_installment_keeps_the_purchase_date():
+ result = await _fetch([
+ _installment(1, 10, "2026-06-06T13:26:40.000Z", "2026-06-06T13:26:40.000Z"),
+ ])
+ assert result[0].date == date(2026, 6, 6)
+
+
+async def test_installment_the_connector_already_dated_is_kept():
+ """A date of the connector's own is left alone, even when it is not
+ exactly the purchase day N-1 months on."""
+ result = await _fetch([
+ _installment(2, 10, "2026-07-12T03:00:00.000Z", "2026-06-06T13:26:40.000Z"),
+ ])
+ assert result[0].date == date(2026, 7, 12)
+
+
+async def test_scheduled_installment_on_its_purchase_day_is_kept():
+ """Nubank sometimes reports a scheduled installment with a purchaseDate on
+ the installment's own day. Same day, different timestamp: it is already
+ in its month, and moving it would push it N-1 months too far."""
+ result = await _fetch([
+ _installment(3, 5, "2026-11-10T03:00:00.000Z", "2026-11-10T00:00:00.001Z"),
+ ])
+ assert result[0].date == date(2026, 11, 10)
+
+
+async def test_posted_installment_at_its_purchase_date_is_kept():
+ """Itaú sends billed installments with a purchaseDate equal to their own
+ charge date. A posted row is the bank's record of when it was charged."""
+ installment = _installment(8, 12, "2026-07-09T03:00:00.000Z", "2026-07-09T03:00:00.000Z")
+ installment["status"] = "POSTED"
+ result = await _fetch([installment])
+ assert result[0].date == date(2026, 7, 9)
+
+
# ---------------------------------------------------------------------------
# v2 cursor pagination (GET /v2/transactions)
# ---------------------------------------------------------------------------