Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion rules/signal_guide.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
14 changes: 10 additions & 4 deletions rules/transactions_guide.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
19 changes: 12 additions & 7 deletions rules/transfer_guide.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -252,7 +252,7 @@ Transfers go through various status changes as they progress through the payment
{
"client_id": "<your-client-id>",
"secret": "<your-sandbox-secret>",
"after_id": "<last-event-id>" // Optional, to only get new events
"after_id": 0 // Required: the largest event_id fetched so far, or 0 initially
}
```

Expand All @@ -262,19 +262,19 @@ 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",
"transfer_type": "debit",
"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",
Expand All @@ -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.
Expand All @@ -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

Expand Down
50 changes: 23 additions & 27 deletions sandbox/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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}"
}
}
}
Expand Down Expand Up @@ -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
```

Expand Down
10 changes: 5 additions & 5 deletions sandbox/src/mcp_server_plaid/tools/pfm/tool_simulate_webhook.py
Original file line number Diff line number Diff line change
Expand Up @@ -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": "",
},
},
Expand Down
Loading