Skip to content

:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.

feat(data-warehouse): add fintoc payment methods, disputes, and business account tables (#120213)

Tom Owersddaf578dc468
diff --git a/products/warehouse_sources/backend/temporal/data_imports/sources/COVERAGE_GAPS_APPENDIX.md b/products/warehouse_sources/backend/temporal/data_imports/sources/COVERAGE_GAPS_APPENDIX.md
index bdf6f2831a2a..a771f64fd5a8 100644
--- a/products/warehouse_sources/backend/temporal/data_imports/sources/COVERAGE_GAPS_APPENDIX.md
+++ b/products/warehouse_sources/backend/temporal/data_imports/sources/COVERAGE_GAPS_APPENDIX.md
@@ -4660,10 +4660,10 @@ Today (11): `accounts`, `charges`, `checkout_sessions`, `customers`, `invoices`,
Diffed against: <https://docs.fintoc.com/_llms/v2026-02-01/en/api-reference.txt>
-- [ ] `Business accounts (GET /v2/accounts)` — resolve account IDs on transfers and analyze business account balances separately from linked open banking accounts (high)
-- [ ] `Payment methods (GET /v2/payment_methods)` — resolve payment_method IDs on subscriptions and compare recurring payment instruments and mandate status (high)
-- [ ] `Business account movements (GET /v2/accounts/{account_id}/movements)` — reconcile transfer activity and business account balances with the complete account ledger (high)
-- [ ] `Disputes (GET /v1/disputes)` — measure disputed payment amounts, outcomes, and revenue losses (high)
+- [x] `Business accounts (GET /v2/accounts)` — resolve account IDs on transfers and analyze business account balances separately from linked open banking accounts (high)
+- [x] `Payment methods (GET /v2/payment_methods)` — resolve payment_method IDs on subscriptions and compare recurring payment instruments and mandate status (high)
+- [x] `Business account movements (GET /v2/accounts/{account_id}/movements)` — reconcile transfer activity and business account balances with the complete account ledger (high)
+- [x] `Disputes (GET /v1/disputes)` — measure disputed payment amounts, outcomes, and revenue losses (high)
- [ ] `Events (GET /v2/events)` — analyze payment, subscription, invoice, and transfer state changes over time (medium)
- [ ] `Account numbers (GET /v2/account_numbers)` — analyze virtual collection accounts, including accounts without transfers and their recent activity (medium)
- [ ] `Payout resources (GET /v1/payouts/{id}/resources)` — connect settlement payouts to the payments, charges, and refunds they include (medium)
diff --git a/products/warehouse_sources/backend/temporal/data_imports/sources/fintoc/canonical_descriptions.py b/products/warehouse_sources/backend/temporal/data_imports/sources/fintoc/canonical_descriptions.py
index 6b2cdf1d2d25..6ad87742152f 100644
--- a/products/warehouse_sources/backend/temporal/data_imports/sources/fintoc/canonical_descriptions.py
+++ b/products/warehouse_sources/backend/temporal/data_imports/sources/fintoc/canonical_descriptions.py
@@ -58,4 +58,45 @@ CANONICAL_DESCRIPTIONS: CanonicalDescriptions = {
"docs_url": "https://docs.fintoc.com/api/movements-api/movements/movements-list",
"columns": {"id": "Movement identifier.", "post_date": "Date the bank posts the movement."},
},
+ "payment_methods": {
+ "description": "Saved customer payment instruments, such as cards, bank transfers, and direct debit mandates.",
+ "docs_url": "https://docs.fintoc.com/api/payments-api/payment-methods/payment-methods-list",
+ "columns": {
+ "id": "Payment method identifier.",
+ "type": "Payment method type. Its details are under a column with the same name.",
+ "customer": "Identifier of the customer that owns the payment method.",
+ "created_at": "Time the payment method was created.",
+ },
+ },
+ "disputes": {
+ "description": "Disputes opened against payment intents, with their status and documentation deadline.",
+ "docs_url": "https://docs.fintoc.com/api/payments-api/disputes/disputes-list",
+ "columns": {
+ "id": "Dispute identifier.",
+ "amount": "Disputed amount, in the smallest currency unit.",
+ "resource_id": "Identifier of the disputed payment intent.",
+ "status": "Dispute status: waiting_documentation, in_review, won, lost, expired, or canceled.",
+ "created_at": "Time the dispute was created.",
+ },
+ },
+ "business_accounts": {
+ "description": "Fintoc business accounts of the organization, with their available balance and owner entity.",
+ "docs_url": "https://docs.fintoc.com/api/business-accounts-api/accounts/accounts-list",
+ "columns": {
+ "id": "Business account identifier.",
+ "available_balance": "Available balance, in the smallest currency unit.",
+ "status": "Account status: active, blocked, or closed.",
+ },
+ },
+ "business_account_movements": {
+ "description": "Every balance change of the business accounts, such as transfers, returns, and fees.",
+ "docs_url": "https://docs.fintoc.com/api/business-accounts-api/movements/movements-list",
+ "columns": {
+ "id": "Movement identifier.",
+ "account_id": "Identifier of the business account.",
+ "balance": "Account balance right after the movement, in the smallest currency unit.",
+ "resource_id": "Identifier of the resource that originated the movement, such as a transfer.",
+ "transaction_date": "Time Fintoc recorded the movement in the account.",
+ },
+ },
}
diff --git a/products/warehouse_sources/backend/temporal/data_imports/sources/fintoc/fintoc.py b/products/warehouse_sources/backend/temporal/data_imports/sources/fintoc/fintoc.py
index 4edd12e2314c..e620547e51de 100644
--- a/products/warehouse_sources/backend/temporal/data_imports/sources/fintoc/fintoc.py
+++ b/products/warehouse_sources/backend/temporal/data_imports/sources/fintoc/fintoc.py
@@ -1,5 +1,6 @@
import hashlib
from collections.abc import Iterator
+from functools import partial
from typing import TYPE_CHECKING, Any
from urllib.parse import parse_qsl, quote, urlencode, urlsplit, urlunsplit
@@ -17,6 +18,7 @@ from products.warehouse_sources.backend.temporal.data_imports.sources.common.res
rest_api_resource,
rest_api_resources,
)
+from products.warehouse_sources.backend.temporal.data_imports.sources.common.rest_source.resource import Resource
from products.warehouse_sources.backend.temporal.data_imports.sources.common.rest_source.typing import (
ClientConfig,
EndpointResource,
@@ -95,11 +97,11 @@ class FintocAPI:
try:
for token in tokens:
# Movements need an account ID, so probe the account before probing its child scope.
- probe_name = "accounts" if name == "movements" else name
- resource = self.resource(probe_name, page_size=1)
+ parent = ENDPOINTS[name].parent
+ resource = self.resource(parent or name, page_size=1)
config: RESTAPIConfig = {"client": self.client_config(token), "resources": [resource]}
page = next(iter(rest_api_resource(config, 0, "fintoc-validation", None)), [])
- if name == "movements" and page:
+ if parent and page:
config["resources"] = [self.resource(name, page_size=1, account_id=page[0]["id"])]
next(iter(rest_api_resource(config, 0, "fintoc-validation", None)), None)
except HTTPError as error:
@@ -114,19 +116,20 @@ class FintocAPI:
@staticmethod
def resource(name: str, page_size: int = 300, account_id: str | None = None) -> EndpointResource:
endpoint = ENDPOINTS[name]
- params: dict[str, Any] = {endpoint.page_size_param: page_size}
+ params: dict[str, Any] = {endpoint.page_size_param: page_size} if endpoint.page_size_param else {}
path = endpoint.path
if name == "movements":
params["confirmed_only"] = "false"
+ if endpoint.parent:
if account_id is not None:
path = path.format(account_id=quote(account_id, safe=""))
else:
- params["account_id"] = {"type": "resolve", "resource": "accounts", "field": "id"}
+ params["account_id"] = {"type": "resolve", "resource": endpoint.parent, "field": "id"}
resource: EndpointResource = {
"name": name,
"endpoint": {"path": path, "params": params, "data_selector": "$"},
}
- if name == "movements" and account_id is None:
+ if endpoint.parent and account_id is None:
resource["include_from_parent"] = ["id"]
return resource
@@ -161,8 +164,8 @@ class FintocAPI:
resource = self.resource(name)
resources: list[str | EndpointResource] = [resource]
- if name == "movements":
- resources = [self.resource("accounts"), resource]
+ if endpoint.parent:
+ resources = [self.resource(endpoint.parent), resource]
config: RESTAPIConfig = {"client": self.client_config(token), "resources": resources}
result = rest_api_resources(
config,
@@ -173,9 +176,9 @@ class FintocAPI:
initial_paginator_state=resume.paginator if resume else None,
)[-1]
for page in result:
- if name == "movements":
+ if endpoint.parent:
for row in page:
- row["account_id"] = row.pop("_accounts_id")
+ row["account_id"] = row.pop(f"_{endpoint.parent}_id")
yield page
token_manager.save_state(FintocResumeState(complete=True))
@@ -189,9 +192,12 @@ class FintocAPI:
if name not in ENDPOINTS:
raise ValueError("Unknown Fintoc table. Select a supported table.")
endpoint = ENDPOINTS[name]
+ # `rows` hands each page on as it arrives and holds no rows, so as a `Resource` it keeps the
+ # framework's checkpoints across fan-out requests that return empty pages.
+ items = Resource(partial(self.rows, name, link_tokens, inputs, manager), name=name, hints={})
return SourceResponse(
name=name,
- items=lambda: self.rows(name, link_tokens, inputs, manager),
+ items=lambda: items,
primary_keys=list(endpoint.primary_keys),
partition_keys=[endpoint.partition_key] if endpoint.partition_key else None,
partition_mode="datetime" if endpoint.partition_key else None,
diff --git a/products/warehouse_sources/backend/temporal/data_imports/sources/fintoc/settings.py b/products/warehouse_sources/backend/temporal/data_imports/sources/fintoc/settings.py
index b3b9341fd181..d837611fb4d8 100644
--- a/products/warehouse_sources/backend/temporal/data_imports/sources/fintoc/settings.py
+++ b/products/warehouse_sources/backend/temporal/data_imports/sources/fintoc/settings.py
@@ -7,10 +7,12 @@ API_VERSION = "2026-02-01"
@frozen
class FintocEndpoint:
path: str
- page_size_param: str = "limit"
+ page_size_param: str | None = "limit"
primary_keys: tuple[str, ...] = ("id",)
partition_key: str | None = "created_at"
requires_link_token: bool = False
+ # Name of the account endpoint whose IDs fill `{account_id}` in the path.
+ parent: str | None = None
webhook_object: str | None = None
webhook_events: tuple[str, ...] = ()
@@ -88,6 +90,17 @@ ENDPOINTS: dict[str, FintocEndpoint] = {
primary_keys=("account_id", "id"),
partition_key=None,
requires_link_token=True,
+ parent="accounts",
+ ),
+ "payment_methods": FintocEndpoint(path="/v2/payment_methods"),
+ # The disputes list documents no pagination parameters.
+ "disputes": FintocEndpoint(path="/v1/disputes", page_size_param=None),
+ "business_accounts": FintocEndpoint(path="/v2/accounts", partition_key=None),
+ "business_account_movements": FintocEndpoint(
+ path="/v2/accounts/{account_id}/movements",
+ primary_keys=("account_id", "id"),
+ partition_key="transaction_date",
+ parent="business_accounts",
),
}
diff --git a/products/warehouse_sources/backend/temporal/data_imports/sources/fintoc/source.py b/products/warehouse_sources/backend/temporal/data_imports/sources/fintoc/source.py
index a22eddd71c7f..838f55fcf293 100644
--- a/products/warehouse_sources/backend/temporal/data_imports/sources/fintoc/source.py
+++ b/products/warehouse_sources/backend/temporal/data_imports/sources/fintoc/source.py
@@ -76,7 +76,7 @@ class FintocSource(ResumableSource[FintocSourceConfig, FintocResumeState], Webho
docsUrl="https://posthog.com/docs/cdp/sources/fintoc",
keywords=["payments", "open banking", "fintech", "latam"],
caption="Enter your Fintoc secret API key. Test keys import test data; live keys import live data. "
- "Accounts and movements need link tokens saved when exchanging links. "
+ "Open banking accounts and movements need link tokens saved when exchanging links. "
"Full refresh includes all available records. Optional webhook sync imports only event-delivered changes after the initial backfill.",
fields=cast(
list[FieldType],
diff --git a/products/warehouse_sources/backend/temporal/data_imports/sources/fintoc/tests/test_fintoc.py b/products/warehouse_sources/backend/temporal/data_imports/sources/fintoc/tests/test_fintoc.py
index a93d131f0922..881b8ac086ad 100644
--- a/products/warehouse_sources/backend/temporal/data_imports/sources/fintoc/tests/test_fintoc.py
+++ b/products/warehouse_sources/backend/temporal/data_imports/sources/fintoc/tests/test_fintoc.py
@@ -103,6 +103,41 @@ def test_movements_fanout_keeps_account_keys_and_tokens_private(
)
+def test_business_account_movements_fan_out_with_api_key_only(
+ http_mock: MagicMock,
+ manager: MagicMock,
+ inputs: MagicMock,
+) -> None:
+ calls: list[tuple[str, dict[str, list[str]]]] = []
+
+ def respond(request: PreparedRequest) -> tuple[int, object, dict[str, str]]:
+ parts = urlsplit(request.url or "")
+ query = parse_qs(parts.query)
+ calls.append((parts.path, query))
+ assert request.headers["Authorization"] == "sk_test_example"
+ if parts.path == "/v2/accounts":
+ return 200, [{"id": "acc_one"}, {"id": "acc_two"}], {}
+ account = parts.path.split("/")[3]
+ if "starting_after" not in query:
+ return (
+ 200,
+ [{"id": f"mov_{account}_first", "account_id": account}],
+ {"Link": f'<https://api.fintoc.com{parts.path}?starting_after=mov_{account}_first>; rel="next"'},
+ )
+ return 200, [{"id": f"mov_{account}_last", "account_id": account}], {}
+
+ http_mock.side_effect = respond
+ result = FintocAPI("sk_test_example", "2026-02-01").source("business_account_movements", [], inputs, manager)
+ rows = [row for page in cast(Iterable[Any], result.items()) for row in page]
+ assert rows == [
+ {"id": f"mov_{account}_{position}", "account_id": account}
+ for account in ("acc_one", "acc_two")
+ for position in ("first", "last")
+ ]
+ assert result.primary_keys == ["account_id", "id"]
+ assert all("link_token" not in query and "confirmed_only" not in query for _, query in calls)
+
+
def test_movements_resume_restores_token_and_skips_finished_accounts(
http_mock: MagicMock,
manager: MagicMock,
diff --git a/products/warehouse_sources/backend/temporal/data_imports/sources/fintoc/tests/test_fintoc_source.py b/products/warehouse_sources/backend/temporal/data_imports/sources/fintoc/tests/test_fintoc_source.py
index cf7620f35d8e..5b6bd2f22fba 100644
--- a/products/warehouse_sources/backend/temporal/data_imports/sources/fintoc/tests/test_fintoc_source.py
+++ b/products/warehouse_sources/backend/temporal/data_imports/sources/fintoc/tests/test_fintoc_source.py
@@ -64,15 +64,22 @@ def test_bad_configuration_fails_before_http(
http_mock.assert_not_called()
-def test_movements_scope_probe_checks_child_access(http_mock: MagicMock) -> None:
+ "schema,child_path",
+ [
+ ("movements", "/v1/accounts/account_example/movements?"),
+ ("business_account_movements", "/v2/accounts/account_example/movements?"),
+ ],
+)
+def test_movements_scope_probe_checks_child_access(http_mock: MagicMock, schema: str, child_path: str) -> None:
http_mock.side_effect = [(200, [{"id": "account_example"}], {}), (403, {}, {})]
valid, message = FintocSource().validate_credentials(
FintocSourceConfig(api_key="sk_test_example", link_tokens="token_example"),
1,
- "movements",
+ schema,
)
assert not valid and message and "permissions" in message
- assert "/v1/accounts/account_example/movements?" in http_mock.call_args.args[0].url
+ assert child_path in http_mock.call_args.args[0].url
def test_unknown_pipeline_table_fails_clearly(inputs: MagicMock, manager: MagicMock) -> None:
diff --git a/products/warehouse_sources/backend/temporal/data_imports/sources/tests/source_contract_baseline.txt b/products/warehouse_sources/backend/temporal/data_imports/sources/tests/source_contract_baseline.txt
index 0567f8511fd3..f1ff82120f6a 100644
--- a/products/warehouse_sources/backend/temporal/data_imports/sources/tests/source_contract_baseline.txt
+++ b/products/warehouse_sources/backend/temporal/data_imports/sources/tests/source_contract_baseline.txt
@@ -94,7 +94,6 @@ Finage fail:stall-budget
FinancialModelling fail:rate-limit-budget,safe-point,stall-budget
Finnhub fail:rate-limit-budget,stall-budget
Finnworlds fail:rate-limit-budget,stall-budget
-Fintoc not-checkable:database
Firebase not-checkable:schemas
Flagsmith fail:safe-point,stall-budget
Formbricks fail:rate-limit-budget,safe-point,stall-budget