Plaid Module

The plaid module integrates with bank accounts via Plaid for ACH transfers, account linking, and wallet funding. Supports both sandbox and production environments with comprehensive connection management.

Import

const plaid = await brdzSDK.plaid;

Methods Overview

Method	Description	Auth Required	HTTP Endpoint
createLinkToken	Create Plaid link token	✅	POST /plaid/link-token/create
savePublicTokenFromFrontend	Save public token from frontend	✅	POST /plaid/link-token/exchange
exchangePublicTokenToAccessToken	Exchange public token to access token	✅	POST /plaid/item/public-token/exchange
checkPlaidConnection	Check wallet Plaid connection	✅	GET /plaid/:wallet_id/check
disconnectPlaidCombined	Disconnect Plaid connection	✅	DELETE /plaid/:wallet_id/plaid
getPlaidAccounts	Get linked bank accounts	✅	GET /plaid/:user_id/accounts
removePlaidItem	Remove Plaid item only	✅	POST /plaid/remove-item
getAccessTokenByWallet	Get access token by wallet	✅	GET /plaid/:wallet_id/access-token
ACHTransfer	Simulate ACH transfer (sandbox)	✅	POST /plaid/transfer
SEPAPayment	Simulate SEPA payment (sandbox)	✅	POST /plaid/payment
plaidTopup	Topup wallet via ACH	✅	POST /plaid/topup

Method Details

createLinkToken

Create a Plaid Link token for frontend connection flow.

const linkToken = await plaid.createLinkToken({
  wallet_id: 123,
  phone_number: "+1 415 5550123" // optional
});

Parameters:

• wallet_id (number, required): Wallet ID to associate with bank connection
• phone_number (string, optional): User phone number for verification

Returns: Link token and expiration

savePublicTokenFromFrontend

Save public token received from Plaid Link frontend component.

const result = await plaid.savePublicTokenFromFrontend({
  public_token: "public-sandbox-12345678-abcd-1234-5678-123456789abc",
  metadata: {
    institution: {
      name: "Chase",
      institution_id: "ins_3"
    }
  }
});

Parameters:

• public_token (string, required): Public token from Plaid Link
• metadata (object, optional): Institution metadata from Plaid Link

exchangePublicTokenToAccessToken

Exchange public token for permanent access token and save to database.

const accessData = await plaid.exchangePublicTokenToAccessToken({
  public_token: "public-sandbox-12345678-abcd-1234-5678-123456789abc",
  metadata: {
    institution: {
      name: "Chase",
      institution_id: "ins_3"
    }
  }
});

Parameters:

• public_token (string, required): Public token from Plaid Link
• metadata (object, optional): Institution metadata

Returns: Access token and item ID

checkPlaidConnection

Check if wallet is connected to Plaid.

const status = await plaid.checkPlaidConnection("123");
console.log(status.connected); // true/false

Parameters:

• wallet_id (string, required): Wallet ID to check

Returns: Connection status boolean

disconnectPlaidCombined

Remove Plaid item and delete connection from database.

const result = await plaid.disconnectPlaidCombined("123");

Parameters:

• wallet_id (string, required): Wallet ID to disconnect

getPlaidAccounts

Get bank accounts for connected user.

const accounts = await plaid.getPlaidAccounts("123");
console.log(accounts.accounts); // Array of bank accounts

Parameters:

• user_id (string, required): User ID to get accounts for

Returns: Array of bank account objects with balances

removePlaidItem

Remove Plaid item from Plaid service only (not from database).

const result = await plaid.removePlaidItem({
  access_token: "access-sandbox-12345678-abcd-1234-5678-123456789abc"
});

Parameters:

• access_token (string, required): Plaid access token

getAccessTokenByWallet

Get Plaid access token for specific wallet.

const tokenData = await plaid.getAccessTokenByWallet("123");
console.log(tokenData.access_token);

Parameters:

• wallet_id (string, required): Wallet ID

Returns: Access token string

ACHTransfer

Simulate ACH transfer events in sandbox environment.

const simulation = await plaid.ACHTransfer({
  transfer_id: "transfer_12345678abcd",
  event_type: "settled" // optional, default: "settled"
});

Parameters:

• transfer_id (string, required): Transfer ID to simulate
• event_type (string, optional): Event type (default: "settled")

SEPAPayment

Simulate SEPA payment completion in sandbox environment.

const simulation = await plaid.SEPAPayment({
  payment_id: "payment_12345678abcd"
});

Parameters:

• payment_id (string, required): Payment ID to simulate

plaidTopup

Fund wallet using connected bank account.

const topup = await plaid.plaidTopup({
  wallet_id: 123,
  amount: 500.00,
  currency: "USD" // optional, default: "USD"
});

Parameters:

• wallet_id (number, required): Wallet ID to fund
• amount (number, required): Amount to transfer
• currency (string, optional): Currency code (default: "USD")

Returns: Transaction ID

Complete Integration Example

// 1. Create link token for frontend
const linkToken = await plaid.createLinkToken({
  wallet_id: 123
});

// 2. Frontend: Initialize Plaid Link with token
// (This happens in your frontend application)

// 3. Save public token from frontend callback
await plaid.savePublicTokenFromFrontend({
  public_token: publicTokenFromCallback,
  metadata: metadataFromCallback
});

// 4. Exchange for permanent access token
const accessData = await plaid.exchangePublicTokenToAccessToken({
  public_token: publicTokenFromCallback,
  metadata: metadataFromCallback
});

// 5. Get user's bank accounts
const accounts = await plaid.getPlaidAccounts("123");

// 6. Fund wallet from bank account
const topup = await plaid.plaidTopup({
  wallet_id: 123,
  amount: 500.00
});

// 7. Check connection status anytime
const isConnected = await plaid.checkPlaidConnection("123");

// 8. Disconnect when needed
if (isConnected.connected) {
  await plaid.disconnectPlaidCombined("123");
}

Connection Management

// Check if wallet has Plaid connection
const checkConnection = async (walletId) => {
  const status = await plaid.checkPlaidConnection(walletId);
  return status.connected;
};

// Complete disconnection (removes from Plaid + database)
const disconnect = async (walletId) => {
  await plaid.disconnectPlaidCombined(walletId);
  console.log('Disconnected successfully');
};

// Get access token for direct Plaid API calls
const getToken = async (walletId) => {
  const tokenData = await plaid.getAccessTokenByWallet(walletId);
  return tokenData.access_token;
};

Sandbox Testing

// Simulate ACH transfer completion
const testACH = async () => {
  await plaid.ACHTransfer({
    transfer_id: "transfer_test_123",
    event_type: "settled"
  });
};

// Simulate SEPA payment completion
const testSEPA = async () => {
  await plaid.SEPAPayment({
    payment_id: "payment_test_123"
  });
};

Error Handling

try {
  const linkToken = await plaid.createLinkToken({
    wallet_id: 123
  });
} catch (error) {
  if (error.message.includes('wallet_id is required')) {
    console.error('Missing wallet ID');
  } else if (error.message.includes('User not found')) {
    console.error('Invalid wallet ID');
  }
}

Authentication

All methods require:

• Valid JWT token (Authorization: Bearer TOKEN)
• API key (x-api-key: KEY)

// Configure before using
const config = await brdzSDK.config;
config.setToken('your-jwt-token');
config.setApiKey('your-api-key');