Skip to content

README.md

Latest commit

 

History

History
221 lines (148 loc) · 8.94 KB

README.md

File metadata and controls

221 lines (148 loc) · 8.94 KB

Plaid Pattern Europe - Account Funding

This is an example account funding app that outlines an end-to-end integration with Plaid. This app focusses on the Europe specific Payment Initiation product.

Plaid Pattern apps are provided for illustrative purposes and are not meant to be run as production applications.

Plaid Pattern Europe client

Requirements

Getting Started

  1. Clone the repo.

    git clone https://github.com/plaid/payment-initiation-pattern-app.git
cd payment-initiation-pattern-app

  2. Create the .env file.

    cp .env.template .env

    Update the .env file with your Plaid API keys.

  3. Verify Payment Initiation is enabled for your client ID through the Plaid Developer Dashboard in Sandbox and/or Production. If it is not enabled, contact your Plaid Account Executive or Account Manager.

  4. Make sure PostgreSQL is running.

    brew services start postgresql@16

  5. Install dependencies.

    make install

  6. Start the app.

    make start

  7. Open http://localhost:3002 in a web browser.

  8. When you're finished, press Ctrl+C in the terminal to stop, or run:

    make stop

Additional Commands

All available commands can be seen by calling make help.

Command Description
make install Install server and client dependencies
make start Start the server and client (initializes DB on first run)
make stop Stop the server and client
make sql Open an interactive psql session
make clear-db Drop and recreate all database tables

Architecture

Pattern consists of three components running as local processes:

  • client — a React-based single-page web frontend served by Vite on port 3002
  • server — a Node.js / Express backend on port 5001
  • database — a PostgreSQL instance on port 5432

The client proxies API requests to the server via Vite's dev server proxy (configured in client/vite.config.ts).

Client

The Pattern web client is written in TypeScript using React. It presents an example account funding workflow to the user.

Key concepts

Communicating with the server

All HTTP calls to the Pattern server are defined in src/services/api.js.

Webhooks and Websockets

The Pattern server sends a message over a websocket whenever it receives a webhook from Plaid. On the client side, websocket listeners in src/components/Sockets.jsx wait for these messages and update data in real time.

Server

The application server is written in JavaScript using Node.js and Express. It interacts with the Plaid API via the Plaid Node SDK, and with the database using node-postgres.

Key Concepts

Using webhooks with ngrok

To receive Plaid webhooks during local development, you can use ngrok to expose your local server to the internet:

brew install ngrok
ngrok http 5001

Browse to localhost:4040 to see the ngrok dashboard and inspect raw webhook payloads. This link is also available in the app's Developer Console.

Do NOT use ngrok in production! It's only included here as a convenience for local development.

ngrok's free account has a session limit of 2 hours. When your session expires, any previously linked Items will stop receiving webhooks because they're registered with the old ngrok URL.

Don't want to use ngrok? As long as you serve the app with an endpoint that is publicly exposed, all the Plaid webhooks will work.

Database

The database is a PostgreSQL instance running locally on port 5432.

The database name is plaid_payment_initiation. Username and password are configured in your .env file (defaults: postgres / password). Connect with psql -U postgres -d plaid_payment_initiation.

To clear all the data in the database:

make clear-db

Tables

The *.sql scripts in the database/init directory define the database schema. See the create.sql initialization script for table schemas.

The database is automatically initialized on the first make start if the tables don't exist yet.

Troubleshooting

Port already in use: Check what's using the port with lsof -i :5001 and either stop that process or change the PORT in your .env file.

PostgreSQL connection refused: Make sure PostgreSQL is running (brew services list). If you installed it via Homebrew, start it with brew services start postgresql@16.

Database authentication errors: The default .env uses postgres / password. If your local PostgreSQL has different credentials, update your .env file accordingly.

View Plaid server logs on the Dashboard.

Debugging

To run the server with the Node.js inspector:

cd server
npx nodemon --env-file=../.env --inspect index.js

Then attach your debugger to port 9229. In VS Code, use a "Node.js: Attach" launch configuration. See the VS Code docs for more information.

Testing with OAuth redirect URIs (optional)

On desktop, OAuth will work without a redirect URI configured. However, using redirect URIs is recommended for best conversion on mobile web, and mandatory when using a Plaid mobile SDK. For more details, see the documentation on redirect URIs on desktop and mobile web.

In Sandbox

Set PLAID_SANDBOX_REDIRECT_URI=http://localhost:3002/oauth-link in your .env file, then register this URI in your Plaid Dashboard.

To test the OAuth redirect URI flow you may use the Chrome browser to simulate a mobile device. Learn how to do this under "Mobile Device Viewport Mode" here: https://developer.chrome.com/docs/devtools/device-mode/

In Production

When running in Production, you must use an https:// URL. Set PLAID_PRODUCTION_REDIRECT_URI=https://localhost:3002/oauth-link in your .env file, then register this URI in your Plaid Dashboard.

To run localhost with https, create a self-signed certificate. Note that self-signed certificates should be used for testing purposes only.

macOS instructions for https with localhost

cd client
brew install mkcert
mkcert -install
mkcert localhost

This creates localhost.pem and localhost-key.pem in the client folder. Then update client/vite.config.ts to add HTTPS configuration to the server options:

server: {
  port: 3002,
  https: {
    key: './localhost-key.pem',
    cert: './localhost.pem',
  },
  // ... proxy config
}

After restarting, visit https://localhost:3002.

Additional Resources

License

Plaid Pattern is a demo app that is intended to be used only for the purpose of demonstrating how you can integrate with Plaid. You are solely responsible for ensuring the correctness, legality, security, privacy, and compliance of your own app and Plaid integration. The Pattern code is licensed under the MIT License and is provided as-is and without warranty of any kind. Plaid Pattern is provided for demonstration purposes only and is not intended for use in production environments.