Connect a Brazilian bank via Pluggy (free for personal use) Brasilianische Bank via Pluggy verbinden (kostenlos für privaten Gebrauch) Conectar um banco brasileiro via Pluggy (grátis para uso pessoal)

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. A Pluggy agrega Santander, Nubank, Itaú, Bradesco, BTG, XP, Banco Inter, Caixa, BB e outros. O caminho para uso pessoal passa pelo MeuPluggy (um app gratuito de consumidor da Pluggy) — sem precisar do plano de R$99/mês. ~15 minutos no total.

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). Você vai precisar de: uma conta em banco brasileiro, ~15 minutos, dois cadastros gratuitos na Pluggy (consumidor + desenvolvedor).

There are TWO Pluggy products — don't confuse them:Es gibt ZWEI Pluggy-Produkte — nicht verwechseln:Existem DOIS produtos da Pluggy — não confunda:

meu.pluggy.ai — consumer app, free, where you actually connect your bank accountEndkunden-App, kostenlos, hier verbindest du tatsächlich dein Bankkontoapp de consumidor, grátis, é onde você efetivamente conecta sua conta bancária
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 ziehtportal do desenvolvedor, onde você pega as chaves de API que sua instância usa para puxar dados do MeuPluggy

1Connect your bank in MeuPluggyBank in MeuPluggy verbindenConecte seu banco no MeuPluggy

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. Abra meu.pluggy.ai → cadastre-se (grátis). Clique no botão principal de conectar → encontre seu banco → rode o fluxo de autorização do banco (CPF / Agência / senha / SMS, conforme o banco). Bancos brasileiros que suportam Open Finance fazem o login na própria UI deles; a Pluggy nunca vê sua senha.

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. Após a autorização, você verá todas as suas contas (conta corrente, poupança, cartões, transações, empréstimos) listadas no MeuPluggy. Repita para cada banco que quiser acompanhar.

2Create a Pluggy Developer accountPluggy-Developer-Account anlegenCrie uma conta de Desenvolvedor na Pluggy

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. Abra dashboard.pluggy.ai → cadastre-se. Você ganha 15 dias de trial — mas, conforme a documentação da Pluggy, você pode continuar puxando dados após o trial expirar desde que use o conector MeuPluggy. Ou seja, uso pessoal continua grátis.

3Add the MeuPluggy connector to your applicationMeuPluggy-Connector zur Anwendung hinzufügenAdicione o conector MeuPluggy à sua aplicação

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. Em dashboard.pluggy.ai → sua aplicação → Customize → lista de conectores → habilite MeuPluggy. Por padrão ele não está na lista; este é o passo que o tutorial da Pluggy meu-pluggy destaca como fácil de esquecer.

4Create a Development Application + grab keysDevelopment Application anlegen + Keys holenCrie uma Development Application + pegue as chaves

In dashboard.pluggy.ai → your application's page → "Create Development Application". In dashboard.pluggy.ai → Anwendungs-Seite → "Create Development Application". Em dashboard.pluggy.ai → página da sua aplicação → "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. Após a criação, você verá o Client ID e o Client Secret. Copie os dois — o Client Secret só é mostrado uma vez.

5Paste both keys into RailwayBeide Keys in Railway einfügenCole as duas chaves na Railway

Without these env vars set on your Railway service, the Pluggy sync silently no-ops — the /connections page will keep saying "Pluggy not configured". This is the most-missed step. Ohne diese Env-Vars in deinem Railway-Service passiert beim Pluggy-Sync nichts — die /connections-Seite zeigt weiter "Pluggy not configured". Der Schritt wird am häufigsten übersehen. Sem essas env vars no seu serviço da Railway, o sync da Pluggy não faz nada silenciosamente — a página /connections continua mostrando "Pluggy not configured". É o passo mais esquecido.

Open your Railway dashboard → your finances service → the Variables tab. Railway-Dashboard öffnen → dein finances-Service → Tab Variables. Abra o dashboard da Railway → seu serviço finances → aba Variables.
Click + New Variable. Add the first one: Auf + New Variable klicken. Erste Variable: Clique em + New Variable. Adicione a primeira:

PLUGGY_CLIENT_ID

Value: the Client ID you copied from dashboard.pluggy.ai → your dev application Wert: die Client ID aus dashboard.pluggy.ai → deine Dev-Application Valor: o Client ID que você copiou em dashboard.pluggy.ai → sua dev application

Click + New Variable again. Add the second: Nochmal + New Variable. Zweite Variable: Clique em + New Variable de novo. Adicione a segunda:

PLUGGY_CLIENT_SECRET

Value: the Client Secret (only shown once on creation — if you lost it, regenerate from the same dev application page) Wert: der Client Secret (nur einmal bei der Erstellung gezeigt — falls verloren, auf derselben Dev-Application-Seite neu erzeugen) Valor: o Client Secret (mostrado só uma vez na criação — se perdeu, regenere na mesma página da dev application)

Save. Railway redeploys the service automatically (~30s — watch the deploy log). Speichern. Railway deployt das Service automatisch neu (~30s — Deploy-Log beobachten). Salve. A Railway faz redeploy do serviço automaticamente (~30s — acompanhe o log de deploy).
Verify by visiting /version on your tenant — under integrations you should see "PLUGGY_CLIENT_ID": { "configured": true }. Verifizieren mit /version auf deiner Instanz — unter integrations sollte "PLUGGY_CLIENT_ID": { "configured": true } stehen. Verifique acessando /version na sua instância — em integrations deve aparecer "PLUGGY_CLIENT_ID": { "configured": true }.

Heads up:Achtung:Atenção: If /version still says "configured": false after the redeploy, double-check there are no leading/trailing spaces in the values — Railway preserves them and Pluggy auth then 401s with a misleading "invalid credentials" error. Wenn /version nach dem Redeploy weiterhin "configured": false meldet, prüfe ob am Anfang/Ende der Werte Leerzeichen sind — Railway behält sie und Pluggy-Auth wirft dann einen irreführenden "invalid credentials"-401. Se /version continuar mostrando "configured": false após o redeploy, confira se não há espaços no começo/fim dos valores — a Railway preserva e a auth da Pluggy responde 401 com um "invalid credentials" enganoso.

6Authorize MeuPluggy → your dev application (per bank)MeuPluggy → deine Dev-Application autorisieren (pro Bank)Autorize MeuPluggy → sua dev application (por banco)

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. No dashboard.pluggy.ai, abra a Demo application (testador de conectores embutido na Pluggy). Inicie uma conexão → escolha o conector MeuPluggy → um fluxo OAuth abre e liga seu banco no meu.pluggy.ai à sua dev application.

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). Após a autorização, a Pluggy cria um Item — um conjunto de contas naquele banco, atualizado diariamente pelo MeuPluggy. Copie o Item ID (UUID, mostrado na página Items).

Important — one authorization per bank:Wichtig — eine Autorisierung pro Bank:Importante — uma autorização por banco: 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. Se você conectou vários bancos no MeuPluggy (Santander + Nubank, por exemplo), precisa repetir o passo OAuth do passo 5 uma vez para cada banco. Cada um recebe seu próprio Item ID.

7Register the Item in your tenantItem in deiner Instanz registrierenRegistre o Item na sua instância

Open your Steward tenant → Connections page → Add Pluggy Item → paste the Item ID + give it a friendly name (e.g. "Santander BR"). Save. Öffne deine Steward-Instanz → Connections-Seite → Add Pluggy Item → Item ID einfügen + einen sprechenden Namen vergeben (z.B. "Santander BR"). Speichern. Abra sua instância do Steward → página Connections → Add Pluggy Item → cole o Item ID + dê um nome amigável (ex.: "Santander BR"). Salve.

If you'd rather use the API directly: Falls du die API direkt nutzen willst: Se preferir usar a API direto:

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. include_cards é true por padrão. Defina como false se você sincroniza o mesmo cartão por outro agregador (Teller / upload de extrato Amex) — evita dupla contagem.

8Trigger the first syncErste Synchronisation auslösenDispare a primeira sincronização

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. Página Connections → botão "Sync now" ao lado do item Pluggy. Puxa todas as contas + os últimos 30 dias de transações. Sincronizações seguintes rodam automaticamente a cada 6 horas 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. Abra a página Accounts — você deve ver as contas conectadas com seus saldos atuais. Abra Transactions para a visão linha a linha.

Adding more banks:Weitere Banken hinzufügen:Adicionando mais bancos: 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. Repita os passos 3–4 para cada banco — cada banco recebe seu próprio Item. As mesmas PLUGGY_CLIENT_ID / SECRET funcionam para todos; você só registra um Item por banco.

?TroubleshootingFehlerbehebungSolução de problemas

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. CLIENT_ID ou CLIENT_SECRET errado. Copie de novo do dashboard da Pluggy. Confira se não tem espaço sobrando antes/depois.
"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. Erro de digitação no Item ID, ou o item foi deletado na Pluggy. Reconecte o banco na Pluggy → pegue um Item ID novo → atualize na página Connections.
Item shows as expiredItem ist abgelaufenItem aparece como expirado — 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). Bancos brasileiros invalidam a conexão da Pluggy a cada ~90 dias. Você precisa reautenticar via Pluggy Connect (o banco mostra o mesmo fluxo de login).
Wrong credit card balanceFalscher Kreditkarten-SaldoSaldo do cartão de crédito errado — 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. A Pluggy às vezes retorna o limite do cartão em vez do saldo. O app corrige automaticamente lendo a fatura mais recente em aberto via /credit-cards/:id/bills — não precisa fazer nada.

🔐What does Pluggy see vs. what we seeWas sieht Pluggy vs. was sehen wirO que a Pluggy vê vs. o que nós vemos

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. guarda o token de login do seu banco + lê suas transações sob demanda. Padrão para qualquer agregador de open banking.
Your Steward tenantDeine Steward-InstanzSua instância do Steward — 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. guarda tudo que a Pluggy retorna (transações, saldos, metadados das contas) no seu próprio Postgres na sua VPC da Railway.
Us (paired-minds)Wir (paired-minds)Nós (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. não vemos nada. Sua instância chama a Pluggy diretamente com as suas chaves; nada passa por infraestrutura controlada por nós.