Skip to content

A local-first personal finance app

Pluggy docs (#667)

lelemm6e4a06528bf9
diff --git a/.github/actions/spelling/expect.txt b/.github/actions/spelling/expect.txt
index c53b4fd09a..9894147962 100644
--- a/.github/actions/spelling/expect.txt
+++ b/.github/actions/spelling/expect.txt
@@ -98,3 +98,5 @@ websecure
WOR
youngcw
OIDC
+pluggyai
+Copiar
\ No newline at end of file
diff --git a/docs-sidebar.js b/docs-sidebar.js
index 342f29bdbe..3302302c32 100644
--- a/docs-sidebar.js
+++ b/docs-sidebar.js
@@ -213,6 +213,7 @@ const sidebars = {
'experimental/oauth-auth',
'experimental/multi-user',
'experimental/rule-templating',
+ 'experimental/pluggyai',
],
},
'getting-started/tips-tricks',
diff --git a/docs/advanced/bank-sync.md b/docs/advanced/bank-sync.md
index 237467ec89..09ab646677 100644
--- a/docs/advanced/bank-sync.md
+++ b/docs/advanced/bank-sync.md
@@ -15,3 +15,13 @@ Here are a couple of considerations to know about before making the decision to
* GoCardless (European Banks)
* SimpleFIN Bridge (North American Banks)
+* Pluggy.ai (Brazilian Banks - [**Experimental feature**](/docs/experimental/pluggyai))
+
+### Retrieve Transactions
+
+Actual does **not** sync bank data automatically. To fetch new transactions manually:
+
+- To sync all accounts: click **All Accounts** in the sidebar, then click **Sync**.
+- To sync a single account: open the account and click the sync button.
+
+ ![](/static/img/connecting-your-bank/connecting-your-bank-simplefin-10.png)
diff --git a/docs/advanced/bank-sync/simplefin.md b/docs/advanced/bank-sync/simplefin.md
index 605dc8fdcf..bb0cdca7ad 100644
--- a/docs/advanced/bank-sync/simplefin.md
+++ b/docs/advanced/bank-sync/simplefin.md
@@ -74,15 +74,6 @@ Server Version 24.10.0 or higher are required for this feature.
5. When you've mapped all your accounts that you wish to, click the "Link Account" button.
-### Retrieve Transactions
-
-Actual does not automatically perform syncs.
-You will need to manually request a sync to pull new transactions from SimpleFIN.
-To sync all accounts, click on "All Accounts" in the side menu, and then click "Sync", below the "All Accounts" header.
-If you wish to only sync one account, view the desired account and click the sync button.
-
- ![](/static/img/connecting-your-bank/connecting-your-bank-simplefin-10.png)
-
### SimpleFIN Considerations
1. Currently, the sync pulls at most 90 days of data from each linked account. The amount of data SimpleFIN can get from each account may vary, so not all accounts may have 90 days of historical transactions that can be imported.
diff --git a/docs/experimental/pluggyai.md b/docs/experimental/pluggyai.md
new file mode 100644
index 0000000000..99d4529028
--- /dev/null
+++ b/docs/experimental/pluggyai.md
@@ -0,0 +1,97 @@
+# Pluggy.ai Setup
+
+:::note
+Client Version 25.4.0 and
+Server Version 25.4.0 or higher are required to use this feature.
+:::
+
+### Create CLIENT ID and CLIENT SECRET for Actual
+
+1. Create an account at [https://pluggy.ai](https://pluggy.ai).
+2. Sign in to the [Pluggy Console](https://console.pluggy.ai/) and create a new team.
+
+ ![](/static/img/connecting-your-bank/pluggy-console-01.png)
+
+3. In the Pluggy Console, create an **Application** before generating API keys:
+ - Click **Applications** in the top bar and create a new application.
+ - Once created, you will see the **Client ID** and **Client Secret**.
+
+ ![](/static/img/connecting-your-bank/pluggy-console-02.png)
+
+4. Store both values securely. You will need them in Actual.
+
+---
+
+### Setup Meu Pluggy
+
+*Meu Pluggy* is a free integration provided by Pluggy.ai for developers. You need to sync your bank using this tool to access it for free.
+
+1. Visit [Meu Pluggy](https://meu.pluggy.ai) and log in or sign up.
+2. Follow the instructions provided on the official [github repository](https://github.com/pluggyai/meu-pluggy).
+3. After completing the steps in *item 2*, return to the Pluggy Console. Go to the application you created and click "Ir para Demo" to open the demo app.
+4. In the top right corner, open the three-dot menu. Open it and click **Copiar Item ID** from your bank sync to the clipboard. You'll need this to complete your Pluggy.ai bank sync setup.
+
+![](/static/img/connecting-your-bank/pluggy-console-03.png)
+
+---
+
+### Set Up Pluggy in Actual
+
+1. In Actual, click **“+ Add account”** at the bottom of the sidebar.
+
+ ![](/static/img/connecting-your-bank/connecting-your-bank-02.png)
+
+2. Select **“Set-up Pluggy for bank-sync.”**
+
+ ![](/static/img/connecting-your-bank/pluggy-setup-modal-setup.png)
+
+3. In the dialog that appears, enter:
+ - **Client ID**: From your Pluggy Console
+ - **Client Secret**: From your Pluggy Console
+ - **Item IDs**: Comma-separated if entering more than one
+
+ ![](/static/img/connecting-your-bank/pluggy-setup-modal.png)
+
+4. Click **Save**. The credentials will be securely stored on the server.
+
+---
+
+### Link Accounts with Pluggy
+
+1. In Actual, link a bank account (existing or new):
+ - For an **existing account**, click it, then click the `...` (kebab menu) and choose **Link Account**.
+
+ ![](/static/img/connecting-your-bank/connecting-your-bank-01.png)
+
+ - For a **new account**, click **“+ Add account”** in the sidebar.
+
+ ![](/static/img/connecting-your-bank/connecting-your-bank-02.png)
+
+2. Select **Link your bank account** with Pluggy.ai.
+
+ ![](/static/img/connecting-your-bank/pluggy-setup-add-account.png)
+
+3. A list of accounts from your Pluggy connection will appear.
+4. Click **Set up bank-sync** next to the one you want to sync.
+
+ ![](/static/img/connecting-your-bank/pluggy-setup-modal-link-account.png)
+
+---
+
+### Pluggy Notes & Limitations
+
+1. Item IDs are associated with user-authorized connections and will expire if access is revoked or the token expires.
+2. Use the sandbox environment for testing — test credentials are available in the [Pluggy Docs](https://docs.pluggy.ai/docs/quick-pluggy-introduction#sandbox-environment).
+3. Data refresh frequency may vary by financial institution.
+
+---
+
+### Resetting Pluggy Credentials
+
+To reset your Pluggy connection:
+
+1. In Actual, click **Add Account**.
+2. Next to “Set-up Pluggy for bank-sync”, open the three-dot menu.
+3. Click **Reset Pluggy credentials**.
+
+You'll then need to generate a new API key and obtain a new Item ID to reconnect.
\ No newline at end of file
diff --git a/static/img/connecting-your-bank/pluggy-console-01.png b/static/img/connecting-your-bank/pluggy-console-01.png
new file mode 100644
index 0000000000..75e54386e9
Binary files /dev/null and b/static/img/connecting-your-bank/pluggy-console-01.png differ
diff --git a/static/img/connecting-your-bank/pluggy-console-02.png b/static/img/connecting-your-bank/pluggy-console-02.png
new file mode 100644
index 0000000000..8b428b1c20
Binary files /dev/null and b/static/img/connecting-your-bank/pluggy-console-02.png differ
diff --git a/static/img/connecting-your-bank/pluggy-console-03.png b/static/img/connecting-your-bank/pluggy-console-03.png
new file mode 100644
index 0000000000..6bf4fb1a76
Binary files /dev/null and b/static/img/connecting-your-bank/pluggy-console-03.png differ
diff --git a/static/img/connecting-your-bank/pluggy-setup-add-account.png b/static/img/connecting-your-bank/pluggy-setup-add-account.png
new file mode 100644
index 0000000000..1ec6e5ce65
Binary files /dev/null and b/static/img/connecting-your-bank/pluggy-setup-add-account.png differ
diff --git a/static/img/connecting-your-bank/pluggy-setup-modal-link-account.png b/static/img/connecting-your-bank/pluggy-setup-modal-link-account.png
new file mode 100644
index 0000000000..30ceb5c5de
Binary files /dev/null and b/static/img/connecting-your-bank/pluggy-setup-modal-link-account.png differ
diff --git a/static/img/connecting-your-bank/pluggy-setup-modal-setup.png b/static/img/connecting-your-bank/pluggy-setup-modal-setup.png
new file mode 100644
index 0000000000..238337775e
Binary files /dev/null and b/static/img/connecting-your-bank/pluggy-setup-modal-setup.png differ
diff --git a/static/img/connecting-your-bank/pluggy-setup-modal.png b/static/img/connecting-your-bank/pluggy-setup-modal.png
new file mode 100644
index 0000000000..3ea0098a69
Binary files /dev/null and b/static/img/connecting-your-bank/pluggy-setup-modal.png differ