Connect a Brazilian bank via Pluggy (free for personal use) Brasilianische Bank via Pluggy verbinden (kostenlos für privaten Gebrauch)

Pluggy aggregates Santander, Nubank, Itaú, Bradesco, BTG, XP, Banco Inter, Caixa, BB, and more. The personal-use path goes through MeuPluggy (a free consumer app from Pluggy) — no R$99/mo plan needed. ~15 minutes total. Pluggy bündelt Santander, Nubank, Itaú, Bradesco, BTG, XP, Banco Inter, Caixa, BB und mehr. Der private Pfad läuft über MeuPluggy (eine kostenlose Endkunden-App von Pluggy) — kein R$99/Monat-Tarif nötig. ~15 Minuten.

You'll need: a Brazilian bank account, ~15 minutes, two free Pluggy signups (consumer + developer). Du brauchst: ein brasilianisches Bankkonto, ~15 Minuten, zwei kostenlose Pluggy-Anmeldungen (Endkunde + Developer).

There are TWO Pluggy products — don't confuse them:Es gibt ZWEI Pluggy-Produkte — nicht verwechseln:

meu.pluggy.ai — consumer app, free, where you actually connect your bank accountEndkunden-App, kostenlos, hier verbindest du tatsächlich dein Bankkonto
dashboard.pluggy.ai — developer portal, where you get the API keys your tenant uses to pull data from MeuPluggyDeveloper-Portal, hier bekommst du die API-Keys, mit denen deine Instanz Daten aus MeuPluggy zieht

1Connect your bank in MeuPluggyBank in MeuPluggy verbinden

Open meu.pluggy.ai → Sign up (free). Press the main connect button → find your bank → run the bank's authorization flow (CPF (Brazilian tax ID) / Agência (branch number) / password / SMS, depending on the bank). Brazilian banks supporting Open Finance handle this in their own login UI; Pluggy never sees your password. Öffne meu.pluggy.ai → Registrieren (kostenlos). Auf den Hauptbutton klicken → deine Bank suchen → den Bank-Authorisierungs-Flow durchlaufen (CPF (brasilianische Steuer-ID) / Agência (Filialnummer) / Passwort / SMS, je nach Bank). Brasilianische Banken mit Open-Finance-Unterstützung machen den Login in ihrer eigenen UI; Pluggy bekommt dein Passwort nie zu sehen.

After authorization you'll see all your accounts (checking, savings, credit cards, transactions, loans) listed inside MeuPluggy. Repeat for each bank you want to track. Nach der Autorisierung siehst du alle deine Konten (Girokonto, Sparkonto, Kreditkarten, Transaktionen, Kredite) in MeuPluggy. Für jede weitere Bank wiederholen.

2Create a Pluggy Developer accountPluggy-Developer-Account anlegen

Open dashboard.pluggy.ai → Sign up. You'll get a 15-day trial — but per Pluggy's docs, you can keep pulling data after the trial expires as long as you stick to the MeuPluggy connector path. So personal use stays free. Öffne dashboard.pluggy.ai → Registrieren. Du bekommst einen 15-Tage-Trial — aber laut Pluggy-Doku kannst du nach Ablauf weiter Daten ziehen, solange du beim MeuPluggy-Connector bleibst. Privater Gebrauch bleibt also kostenlos.

3Add the MeuPluggy connector to your applicationMeuPluggy-Connector zur Anwendung hinzufügen

In dashboard.pluggy.ai → your application → Customize → connector list → enable MeuPluggy. By default it's not in the list; this is the step the Pluggy meu-pluggy tutorial flags as easy to miss. In dashboard.pluggy.ai → deine Anwendung → Customize → Connector-Liste → MeuPluggy aktivieren. Standardmäßig ist er nicht in der Liste; dies ist der Schritt, den die Pluggy-meu-pluggy-Anleitung als leicht zu übersehen markiert.

4Create a Development Application + grab keysDevelopment Application anlegen + Keys holen

In dashboard.pluggy.ai → your application's page → "Create Development Application". In dashboard.pluggy.ai → Anwendungs-Seite → "Create Development Application".
After creation you'll see Client ID and Client Secret. Copy both — the Client Secret is only shown once. Nach Erstellung siehst du Client ID und Client Secret. Beides kopieren — der Client Secret wird nur einmal angezeigt.

Add them to your Railway service env vars: Beide als Env-Vars in deinem Railway-Service hinzufügen:

PLUGGY_CLIENT_ID

From dashboard.pluggy.ai → your dev application → Client ID Von dashboard.pluggy.ai → deine Dev-Application → Client ID

PLUGGY_CLIENT_SECRET

From dashboard.pluggy.ai → your dev application → Client Secret (shown once) Von dashboard.pluggy.ai → deine Dev-Application → Client Secret (nur einmal angezeigt)

Railway redeploys automatically after the second variable is saved (~30s). Railway deployt automatisch neu, sobald die zweite Variable gespeichert ist (~30s).

5Authorize MeuPluggy → your dev application (per bank)MeuPluggy → deine Dev-Application autorisieren (pro Bank)

From dashboard.pluggy.ai, open the Demo application (Pluggy's built-in connector tester). Run a connection → pick the MeuPluggy connector → an OAuth flow opens that links your meu.pluggy.ai bank to your dev app. In dashboard.pluggy.ai die Demo application öffnen (Pluggys eingebauter Connector-Tester). Eine Verbindung starten → den MeuPluggy-Connector wählen → ein OAuth-Flow öffnet sich und verbindet deine meu.pluggy.ai-Bank mit deiner Dev-App.

After successful authorization, Pluggy creates an Item — a bag of accounts at that bank, refreshed daily by MeuPluggy. Copy the Item ID (UUID, shown on the Items page). Nach erfolgreicher Autorisierung erzeugt Pluggy ein Item — ein Bündel aller Konten dieser Bank, täglich von MeuPluggy aktualisiert. Kopiere die Item ID (UUID, auf der Items-Seite).

Important — one authorization per bank:Wichtig — eine Autorisierung pro Bank: If you connected several banks in MeuPluggy (Santander + Nubank, say), you have to repeat the OAuth step in step 5 once per bank. Each gets its own Item ID. Wenn du mehrere Banken in MeuPluggy verbunden hast (z.B. Santander + Nubank), musst du den OAuth-Schritt in Schritt 5 für jede Bank einmal durchlaufen. Jede bekommt eine eigene Item ID.

6Register the Item in your tenantItem in deiner Instanz registrieren

Open your Finances tenant → Connections page → Add Pluggy Item → paste the Item ID + give it a friendly name (e.g. "Santander BR"). Save. Öffne deine Finances-Instanz → Connections-Seite → Add Pluggy Item → Item ID einfügen + einen sprechenden Namen vergeben (z.B. "Santander BR"). Speichern.

If you'd rather use the API directly: Falls du die API direkt nutzen willst:

curl -X POST https://<your-tenant>/api/pluggy/items \
  -H "Authorization: Bearer <API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"item_id":"","name":"Santander BR","include_cards":true}'

include_cards defaults to true. Set to false if you sync the same credit card via another aggregator (Teller / Amex statement upload) — prevents double-counting. include_cards ist standardmäßig true. Auf false setzen, falls du dieselbe Kreditkarte schon über einen anderen Aggregator (Teller / Amex-Auszug-Upload) syncst — verhindert Doppelbuchungen.

5Trigger the first syncErste Synchronisation auslösen

Connections page → "Sync now" button next to the Pluggy item. Pulls every account + the last 30 days of transactions. Subsequent syncs run automatically every 6 hours via cron. Connections-Seite → "Sync now"-Button neben dem Pluggy-Item. Zieht alle Konten + die letzten 30 Tage Transaktionen. Nachfolgende Syncs laufen automatisch alle 6 Stunden via Cron.

Open the Accounts page — you should see the connected accounts with their current balances. Open Transactions for the line-by-line view. Öffne die Accounts-Seite — du solltest die verbundenen Konten mit aktuellen Salden sehen. Über Transactions die zeilenweise Ansicht öffnen.

Adding more banks:Weitere Banken hinzufügen: Repeat steps 3–4 for each bank — every bank gets its own Item. The same PLUGGY_CLIENT_ID / SECRET work for all of them; you just register one Item per bank. Schritte 3–4 für jede Bank wiederholen — jede Bank bekommt ihr eigenes Item. Die gleiche PLUGGY_CLIENT_ID / SECRET funktioniert für alle; du registrierst nur ein Item pro Bank.

?TroubleshootingFehlerbehebung

401 Unauthorized — Wrong CLIENT_ID or CLIENT_SECRET. Re-copy from the Pluggy dashboard. Make sure no leading/trailing whitespace. Falsche CLIENT_ID oder CLIENT_SECRET. Aus dem Pluggy-Dashboard neu kopieren. Auf führende/abschließende Leerzeichen achten.
"Item not found" — Item ID typo, or the item was deleted from Pluggy. Reconnect the bank in Pluggy → get a fresh Item ID → update on Connections page. Tippfehler in der Item ID, oder das Item wurde in Pluggy gelöscht. Bank in Pluggy neu verbinden → neue Item ID holen → auf der Connections-Seite aktualisieren.
Item shows as expiredItem ist abgelaufen — Brazilian banks invalidate Pluggy's connection every ~90 days. You'll need to re-authenticate via Pluggy Connect (the bank shows you the same login flow). Brasilianische Banken invalidieren die Pluggy-Verbindung alle ~90 Tage. Du musst dich über Pluggy Connect erneut authentifizieren (gleicher Login-Flow).
Wrong credit card balanceFalscher Kreditkarten-Saldo — Pluggy occasionally returns the credit limit instead of the balance. The app auto-corrects by reading the most recent unpaid bill via /credit-cards/:id/bills — no action needed. Pluggy gibt gelegentlich den Kreditrahmen statt des Saldos zurück. Die App korrigiert das automatisch über die jüngste unbezahlte Rechnung via /credit-cards/:id/bills — keine Aktion erforderlich.

🔐What does Pluggy see vs. what we seeWas sieht Pluggy vs. was sehen wir

Pluggy — stores your bank login token + reads your transactions on demand. Standard for any open-banking aggregator. speichert deinen Bank-Login-Token + liest deine Transaktionen bei Bedarf. Standard für jeden Open-Banking-Aggregator.
Your Finances tenant — stores everything Pluggy returns (transactions, balances, account metadata) in your own Postgres in your own Railway VPC. speichert alles, was Pluggy liefert (Transaktionen, Salden, Konto-Metadaten), in deiner eigenen Postgres in deiner eigenen Railway-VPC.
Us (paired-minds)Wir (paired-minds) — see nothing. Your tenant calls Pluggy directly with your keys; nothing routes through any infrastructure we control. sehen nichts. Deine Instanz ruft Pluggy direkt mit deinen Keys auf; nichts läuft über Infrastruktur, die wir kontrollieren.