Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.encoreos.io/llms.txt

Use this file to discover all available pages before exploring further.

Purpose: Verify Plaid Transfer and Transfer UI against Plaid Sandbox (no real banks). Use for manual or CI runs when Sandbox credentials are available. See also: FA-20 Plaid Integration

​
Environment

Set these for Sandbox:
VariablePurpose
PLAID_ENVIRONMENTsandbox
PLAID_CLIENT_IDFrom Plaid Dashboard
PLAID_SECRETFrom Plaid Dashboard (Sandbox)
PLAID_ORIGINATION_ACCOUNT_IDFrom Plaid Dashboard → Transfer → Origination account (Sandbox)
For Transfer UI, in Plaid Dashboard create a Link customization with Account Select: Enabled for one account. Optionally set plaid_link_customization_name in fa_module_settings per org (or pass from frontend via TransferUIButton / useTransferUI).

​
Payroll (programmatic) flow

  • Use Sandbox credentials in the edge function (or local env when running functions locally).
  • In Sandbox, transfers stay pending until you simulate via Plaid Dashboard or API.
  • Automatic state transition: Use amount $11.11 to trigger automatic progression: pending → posted → settled → funds available for ACH debits. See Plaid Transfer Sandbox – Automatic Sandbox simulations.
  • Webhooks: In Sandbox, webhooks do not fire unless you call POST /sandbox/transfer/fire_webhook. For payroll webhook testing, use that endpoint to simulate the webhook after simulating transfer status in the Dashboard.

​
Transfer UI flow

  1. Create intent: Call plaid-transfer-intent-create with organization_id, mode, amount, description, ach_class, user. Backend uses Sandbox and returns transfer_intent_id. Note: The description parameter is subject to Plaid’s maximum length (8 characters for underlying transfers). Validate or truncate the description client- or server-side before calling this endpoint to avoid Sandbox validation errors.
  2. Link token: Call plaid-create-link-token with organization_id and transfer_intent_id (and optional link_customization_name). Receive link_token.
  3. Open Link: In the app, open Plaid Link with that token. In Sandbox use First Platypus Bank and test user to complete the flow.
  4. Confirm: Call plaid-transfer-intent-get with organization_id and transfer_intent_id to confirm status and transfer_id.

​
Optional: Script and conditional integration test

  • Script: Run scripts/plaid-sandbox-verify.ts when PLAID_SANDBOX_TESTS=1 and Supabase + Plaid Sandbox env vars are set. It invokes plaid-transfer-intent-create then plaid-transfer-intent-get and logs success/failure for manual verification.
  • Conditional integration test: In tests/integration/fa/plaid-transfer-intent-create.test.ts, the test “create then get (Sandbox) when PLAID_SANDBOX_TESTS=1 and credentials set” runs only when PLAID_SANDBOX_TESTS=1 and PLAID_CLIENT_ID, PLAID_SECRET, PLAID_ORIGINATION_ACCOUNT_ID are set. It creates an intent then calls intent-get and asserts a 200 response. CI without Sandbox secrets skips this test.

​
Checklist (manual)

  • Set PLAID_ENVIRONMENT=sandbox, PLAID_CLIENT_ID, PLAID_SECRET, PLAID_ORIGINATION_ACCOUNT_ID.
  • (Transfer UI) Create Link customization with Account Select for one account; set plaid_link_customization_name if desired.
  • (Payroll) Use amount $11.11 for automatic state transition; use Dashboard or POST /sandbox/transfer/fire_webhook for webhook testing.
  • (Transfer UI) Create intent → get link token → open Link in Sandbox (First Platypus Bank) → complete flow → call intent-get to confirm status/transfer_id.