diff --git a/rules/signal_guide.md b/rules/signal_guide.md index 20e1ab6..7e658a0 100644 --- a/rules/signal_guide.md +++ b/rules/signal_guide.md @@ -186,7 +186,7 @@ Now that you have an access token and account ID, you can evaluate the risk of a } ``` -All of the above are REQUIRED properties +`access_token`, `account_id`, `client_transaction_id`, and `amount` are REQUIRED. The other properties are optional. ### 5.3 Sandbox Testing diff --git a/rules/transactions_guide.md b/rules/transactions_guide.md index ea17a57..6b66557 100644 --- a/rules/transactions_guide.md +++ b/rules/transactions_guide.md @@ -166,19 +166,25 @@ Save `next_cursor` to resume syncs. If `has_more` is `true`, repeat call with cu #### 4.3 Loop Example (Pseudo-code) ```python -cursor = "" +cursor = load_saved_cursor() # "" on the first sync +added, modified, removed = [], [], [] while True: response = transactions_sync(cursor) - process(response.added) + added += response.added + modified += response.modified + removed += response.removed + cursor = response.next_cursor if not response.has_more: break - cursor = response.next_cursor +# Apply all pages, then persist the final cursor +apply_updates(added, modified, removed) +save_cursor(cursor) ``` ## Additional Tips - Use `transactions/sync` to keep user data fresh. -- Retry on `PRODUCT_NOT_READY` errors. +- If data isn't ready yet, `/transactions/sync` returns no transactions and an empty `next_cursor` instead of an error. Wait for the `SYNC_UPDATES_AVAILABLE` webhook, then sync again. See [Transactions Sync migration guide](https://plaid.com/docs/transactions/sync-migration/). - Respect rate limits and add exponential backoff. ## Best Practice diff --git a/rules/transfer_guide.md b/rules/transfer_guide.md index aa0bc76..c07abed 100644 --- a/rules/transfer_guide.md +++ b/rules/transfer_guide.md @@ -60,7 +60,7 @@ Send a POST request to Plaid with the following JSON payload: **Optional Parameters:** -- `webhook`: URL to receive transfer webhooks (recommended in production). +- `webhook`: URL to receive Item webhooks. Transfer webhooks are configured separately in the Plaid Dashboard (see Step 6.2). - `redirect_uri`: Required only for OAuth-based institutions. ### 1.3 Example Response @@ -252,7 +252,7 @@ Transfers go through various status changes as they progress through the payment { "client_id": "", "secret": "", - "after_id": "" // Optional, to only get new events + "after_id": 0 // Required: the largest event_id fetched so far, or 0 initially } ``` @@ -262,9 +262,9 @@ Transfers go through various status changes as they progress through the payment { "transfer_events": [ { - "event_id": "event-id-1", + "event_id": 1, "timestamp": "2022-01-01T12:00:00Z", - "event_type": "TRANSFER_CREATED", + "event_type": "pending", "account_id": "account-id-xxx", "transfer_id": "transfer-id-xxx", "origination_account_id": "origination-account-id", @@ -272,9 +272,9 @@ Transfers go through various status changes as they progress through the payment "transfer_amount": "100.00" }, { - "event_id": "event-id-2", + "event_id": 2, "timestamp": "2022-01-02T15:30:00Z", - "event_type": "TRANSFER_STATUS_UPDATE", + "event_type": "posted", "account_id": "account-id-xxx", "transfer_id": "transfer-id-xxx", "origination_account_id": "origination-account-id", @@ -297,7 +297,12 @@ All possible values for `event_type` include: - **posted**: The transfer has been successfully submitted to the payment network. - **settled**: The transfer has been successfully completed by the payment network. - **funds_available**: Funds from the transfer have been released from hold and applied to the ledger's available balance. (Only applicable to ACH debits.) + - **guaranteed**: The transfer has been fully guaranteed by Plaid. - **returned**: A posted transfer was returned. + - **adjustment**: An adjustment was made to the transfer due to rare activity, such as a dishonor. Refer to `event_amount` for the amount adjusted. + - **guarantee_reimbursed**: Plaid reimbursed the client for the loss on a returned guaranteed transfer. + - **client_return_recovered**: The client reported recovering the loss on a returned transfer via `/transfer/return/recover`, and Plaid debited the recovered amount from the client's ledger. + - **plaid_return_recovered**: Plaid recovered the loss on a returned transfer by successfully reinitiating it. - **swept**: The transfer was swept to / from the sweep account. - **swept_settled**: Credits are available to be withdrawn or debits have been deducted from the customer's business checking account. - **return_swept**: Due to the transfer being returned, funds were pulled from or pushed back to the sweep account. @@ -323,7 +328,7 @@ All possible values for `event_type` include: ### 6.2 Webhook Method -Configure a webhook URL in your Link token creation to receive event notifications automatically. +Register a "Transfer event" webhook URL on the Webhooks page of the [Plaid Dashboard](https://dashboard.plaid.com/team/webhooks). Transfer webhooks tell you new events are available; call `/transfer/event/sync` to fetch them. See [Reconciling transfers](https://plaid.com/docs/transfer/reconciling-transfers/). ## Step 7: Sandbox Testing diff --git a/sandbox/README.md b/sandbox/README.md index 51f5a05..276bd69 100644 --- a/sandbox/README.md +++ b/sandbox/README.md @@ -104,37 +104,33 @@ For quick installation, use one of the one-click installation buttons below. [![Install with UV in VS Code](https://img.shields.io/badge/VS_Code-UV-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=plaid&inputs=%5B%7B%22type%22%3A%22promptString%22%2C%22id%22%3A%22client_id%22%2C%22description%22%3A%22Plaid%20Client%20ID%22%2C%22password%22%3Afalse%7D%2C%7B%22type%22%3A%22promptString%22%2C%22id%22%3A%22secret%22%2C%22description%22%3A%22Plaid%20Secret%22%2C%22password%22%3Atrue%7D%5D&config=%7B%22command%22%3A%22uvx%22%2C%22args%22%3A%5B%22mcp-server-plaid%22%5D%2C%22env%22%3A%7B%22PLAID_CLIENT_ID%22%3A%22%24%7Binput%3Aclient_id%7D%22%2C%22PLAID_SECRET%22%3A%22%24%7Binput%3Asecret%7D%22%7D%7D) [![Install with UV in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-UV-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=plaid&inputs=%5B%7B%22type%22%3A%22promptString%22%2C%22id%22%3A%22client_id%22%2C%22description%22%3A%22Plaid%20Client%20ID%22%2C%22password%22%3Afalse%7D%2C%7B%22type%22%3A%22promptString%22%2C%22id%22%3A%22secret%22%2C%22description%22%3A%22Plaid%20Secret%22%2C%22password%22%3Atrue%7D%5D&config=%7B%22command%22%3A%22uvx%22%2C%22args%22%3A%5B%22mcp-server-plaid%22%5D%2C%22env%22%3A%7B%22PLAID_CLIENT_ID%22%3A%22%24%7Binput%3Aclient_id%7D%22%2C%22PLAID_SECRET%22%3A%22%24%7Binput%3Asecret%7D%22%7D%7D&quality=insiders) -For manual installation, add the following JSON block to your User Settings (JSON) file in VS Code. You can do this by pressing `Ctrl + Shift + P` and typing `Preferences: Open Settings (JSON)`. +For manual installation, add the following JSON block to your user `mcp.json` file in VS Code. You can do this by pressing `Ctrl + Shift + P` and typing `MCP: Open User Configuration`. Optionally, you can add it to a file called `.vscode/mcp.json` in your workspace. This will allow you to share the configuration with others. -> Note that the `mcp` key is needed when using the `mcp.json` file. - ```json { - "mcp": { - "inputs": [ - { - "type": "promptString", - "id": "client_id", - "description": "Plaid Client ID", - "password": false - }, - { - "type": "promptString", - "id": "secret", - "description": "Plaid Secret", - "password": true - } - ], - "servers": { - "plaid": { - "command": "uvx", - "args": ["mcp-server-plaid"], - "env": { - "PLAID_CLIENT_ID": "${input:client_id}", - "PLAID_SECRET": "${input:secret}" - } + "inputs": [ + { + "type": "promptString", + "id": "client_id", + "description": "Plaid Client ID", + "password": false + }, + { + "type": "promptString", + "id": "secret", + "description": "Plaid Secret", + "password": true + } + ], + "servers": { + "plaid": { + "command": "uvx", + "args": ["mcp-server-plaid"], + "env": { + "PLAID_CLIENT_ID": "${input:client_id}", + "PLAID_SECRET": "${input:secret}" } } } @@ -196,7 +192,7 @@ npx @modelcontextprotocol/inspector uvx mcp-server-plaid --client-id YOUR_PLAID_ Or if you've installed the package in a specific directory or are developing on it: ``` -cd path/to/servers/src/plaid +cd sandbox npx @modelcontextprotocol/inspector uv run mcp-server-plaid --client-id YOUR_PLAID_CLIENT_ID --secret YOUR_PLAID_SECRET ``` diff --git a/sandbox/src/mcp_server_plaid/tools/pfm/tool_simulate_webhook.py b/sandbox/src/mcp_server_plaid/tools/pfm/tool_simulate_webhook.py index 014a464..1d26dba 100644 --- a/sandbox/src/mcp_server_plaid/tools/pfm/tool_simulate_webhook.py +++ b/sandbox/src/mcp_server_plaid/tools/pfm/tool_simulate_webhook.py @@ -36,15 +36,15 @@ "webhook_code": { "type": "string", "description": """The specific webhook event code to simulate (e.g., 'DEFAULT_UPDATE', 'SYNC_UPDATES_AVAILABLE', - 'TRANSACTIONS_REMOVED'). Common codes include 'DEFAULT_UPDATE' for new transactions, 'HISTORICAL_UPDATE' for - initial transaction fetch, and 'USER_PERMISSION_REVOKED' for revoked access. You can use the 'ask_bill' tool to - find appropriate values.""", + 'NEW_ACCOUNTS_AVAILABLE'). Common codes include 'SYNC_UPDATES_AVAILABLE' for new transactions, 'DEFAULT_UPDATE' + for product updates, and 'USER_PERMISSION_REVOKED' for revoked access. You can use the `search_documentation` + tool (powered by Ask Bill) to find appropriate values.""", }, "webhook_type": { "type": "string", "description": """The category of webhook to fire (e.g., 'TRANSACTIONS', 'ITEM', 'AUTH'). Must be compatible - with the webhook_code. For example, 'DEFAULT_UPDATE' requires 'TRANSACTIONS' type. You can use the 'ask_bill' tool - to find appropriate values.""", + with the webhook_code. For example, 'DEFAULT_UPDATE' requires 'TRANSACTIONS' type. You can use the `search_documentation` + tool (powered by Ask Bill) to find appropriate values.""", "default": "", }, },