Plaid Integration

PayStream integrates with Plaid for instant bank account verification, eliminating the need for micro-deposit verification.

Benefits

Feature	With Plaid	Without Plaid
Verification Time	Instant (seconds)	1-3 business days
User Experience	Familiar Plaid UI	Manual entry
PCI Scope	Reduced	Higher

Setup

1. Get Plaid Credentials

1. Sign up at plaid.com
2. Create a sandbox application
3. Copy your client_id and secret

2. Configure PayStream

Add Plaid credentials to your environment:

PLAID_CLIENT_ID=your_client_id
PLAID_SECRET=your_secret
PLAID_ENV=sandbox

3. Create Link Token

curl -X POST https://api.paystream.fi/api/v1/plaid/link-token \
  -H "Authorization: Bearer psk_test_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "purpose": "payment_method",
    "recipientId": "rec_abc123"
  }'

Response:

{
  "data": {
    "linkToken": "link-sandbox-xxxxxx",
    "expiration": "2026-02-19T01:00:00Z"
  }
}

Frontend Integration

Initialize Plaid Link in your frontend:

const linkHandler = Plaid.create({
  token: linkToken,
  onSuccess: (publicToken, metadata) => {
    // Send publicToken to your backend
    exchangeToken(publicToken, metadata.account_id);
  },
  onExit: (err, metadata) => {
    console.log('User exited Plaid Link');
  }
});

linkHandler.open();

Exchange Token

Exchange the public token for a processor token:

curl -X POST https://api.paystream.fi/api/v1/plaid/exchange-token \
  -H "Authorization: Bearer psk_test_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "publicToken": "public-sandbox-xxxxxx",
    "accountId": "account-sandbox-xxxxxx"
  }'

Response:

{
  "data": {
    "processorToken": "processor-sandbox-xxxxxx",
    "accountId": "account-sandbox-xxxxxx"
  }
}

Create Payment Method

Use the processor token to create a verified payment method:

curl -X POST https://api.paystream.fi/api/v1/recipients/rec_abc123/payment-methods \
  -H "Authorization: Bearer psk_test_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "plaidProcessorToken": "processor-sandbox-xxxxxx",
    "plaidAccountId": "account-sandbox-xxxxxx",
    "accountHolderName": "John Driver"
  }'

Test Credentials

Use these Plaid sandbox credentials for testing:

Item	Username	Password
Standard	user_good	pass_good
MFA Required	user_good	pass_good (then 1234)

Webhooks

Plaid sends webhooks for account updates:

Event	Description
Item error	Account connection issue
Account balance updated	Balance refresh complete

Configure Plaid webhooks to point to:

https://api.paystream.fi/webhooks/plaid