Plaid Integration

Overview

Plaid lets customers link their bank accounts to financial institutions. Plaid handles the integration with banks across North America, giving customers access to:

Bank account information (PII)
Balance checking
Debits and credits

Cybrid integrates Plaid into the embedded experience to simplify customer onboarding and bank account connection. Partners can leverage Cybrid's Plaid integration to enable end-customers to connect their bank accounts and deposit or withdraw fiat currency on the Cybrid Platform.

Choose your approach

Choose one of two methods to create customer external bank accounts and drive deposits and withdrawals on the Cybrid Platform:

Method	Plaid account / branding	Description
Cybrid's Plaid integration	Cybrid	Initiate the Plaid process via the `/api/workflows` endpoint, then drive the user experience with the Plaid Link SDK. Gives more control over the user experience and integration at the app level.
Your own Plaid integration	Partner	The Partner owns the Plaid account and drives the entire experience. After a customer connects their bank account via Plaid, you pass the Plaid Processor Token to Cybrid, which enables Cybrid to trigger money movement on behalf of the customer. Offers the most flexibility, but requires you to pay for your own Plaid integration. See Plaid's processor token documentation; use `modern_treasury` as the `processor` value.

Prerequisites

Before integrating Plaid, ensure you have:

Created a customer via POST /api/customers
The customer GUID from the customer creation response
An OAuth bearer token (see Token Scopes)
For Method 1: a redirect_uri registered with Cybrid (contact support to register URIs)
For Method 2: a Plaid account with the ability to generate processor tokens

ℹ️
Environments
Examples in this guide use the sandbox base URL https://bank.sandbox.cybrid.app. For production, use https://bank.production.cybrid.app and https://id.production.cybrid.app for OAuth.

Method 1: Cybrid's Plaid integration

This is the most common approach. The complete workflow involves three steps.

Step 1: Generate a Plaid Link token

Create a workflow to obtain a plaid_link_token from Cybrid:

POST /api/workflows
Content-Type: application/json
Authorization: Bearer YOUR_TOKEN

{
  "type": "plaid",
  "kind": "link_token_create",
  "language": "en",
  "link_customization_name": "default",
  "customer_guid": "customer_guid",
  "redirect_uri": "https://yourapp.com/api/plaid-redirect-uri"
}

{
  "guid": "workflow_guid",
  "type": "plaid",
  "state": "storing",
  "customer_guid": "customer_guid",
  "created_at": "2026-01-01T16:01:58.074Z"
}

Poll GET /api/workflows/{workflow_guid} until state: completed, then read the plaid_link_token field:

{
  "guid": "workflow_guid",
  "type": "plaid",
  "state": "completed",
  "customer_guid": "customer_guid",
  "plaid_link_token": "plaid_link_token"
}

Key fields:

Field	Description
`type`	Must be `plaid`
`kind`	Use `link_token_create` for new accounts
`customer_guid`	The customer who will link their bank account
`redirect_uri`	Must be registered with Cybrid; contact support to register URIs
`android_package_name`	For Android apps, use instead of `redirect_uri`; register with Cybrid

Android apps:

For Android applications, register your app's package name (e.g., com.yourcompany.yourapp) with Cybrid instead of a redirect URI. Use the android_package_name field when creating a Plaid workflow:

{
  "type": "plaid",
  "kind": "link_token_create",
  "language": "en",
  "link_customization_name": "default",
  "customer_guid": "customer_guid",
  "redirect_uri": "https://yourapp.com/api/plaid-redirect-uri",
  "android_package_name": "com.yourcompany.yourapp"
}

⚠️
Sandbox redirect URIs
Sandbox only supports HTTPS redirect URIs. Separate registrations are required for sandbox and production environments.

Step 2: Initialize Plaid Link SDK

For supported platforms and presentation modes, see Plaid Link documentation.

Use the plaid_link_token from Step 1 in your frontend to initialize Plaid Link:

const handler = Plaid.create({
  token: plaid_link_token,  // From Step 1
  onSuccess: (public_token, metadata) => {
    // Extract the public_token and account_id
    const plaid_public_token = public_token;
    const plaid_account_id = metadata.accounts[0].id;
    // Send these to your backend to create the external bank account
    createExternalBankAccount(plaid_public_token, plaid_account_id);
  },
  onLoad: () => {
    console.log("Plaid Link loaded");
  },
  onExit: (err, metadata) => {
    if (err) {
      console.error("Plaid Link error:", err);
    }
  },
  onEvent: (eventName, metadata) => {
    console.log("Plaid event:", eventName);
  }
});

// Open Plaid Link
handler.open();

Step 3: Create the external bank account

Submit the plaid_public_token and plaid_account_id from Step 2 to Cybrid:

POST /api/external_bank_accounts
Content-Type: application/json
Authorization: Bearer YOUR_TOKEN

{
  "name": "Customer Checking Account",
  "account_kind": "plaid",
  "customer_guid": "customer_guid",
  "asset": "USD",
  "plaid_public_token": "plaid_public_token",
  "plaid_account_id": "plaid_account_id"
}

{
  "guid": "external_bank_account_guid",
  "name": "Customer Checking Account",
  "account_kind": "plaid",
  "customer_guid": "customer_guid",
  "asset": "USD",
  "state": "storing",
  "created_at": "2026-01-01T16:05:40.757Z"
}

Method 2: Your own Plaid integration

If you have your own Plaid account, generate a Plaid Processor Token in your Plaid integration and submit it to Cybrid via POST /api/external_bank_accounts with account_kind: plaid_processor_token. See Plaid's processor token documentation for details on generating tokens; use modern_treasury as the processor value.

POST /api/external_bank_accounts
Content-Type: application/json
Authorization: Bearer YOUR_TOKEN

{
  "name": "Customer Checking Account",
  "account_kind": "plaid_processor_token",
  "customer_guid": "customer_guid",
  "asset": "USD",
  "plaid_processor_token": "processor-production-xxxxx-xxxxx",
  "plaid_institution_id": "ins_123456",
  "plaid_account_mask": "0000",
  "plaid_account_name": "Plaid Checking"
}

{
  "guid": "external_bank_account_guid",
  "name": "Customer Checking Account",
  "account_kind": "plaid_processor_token",
  "customer_guid": "customer_guid",
  "asset": "USD",
  "plaid_institution_id": "ins_123456",
  "plaid_account_mask": "0000",
  "plaid_account_name": "Plaid Checking",
  "state": "storing",
  "created_at": "2026-01-01T16:05:40.757Z"
}

Plaid Integration

Overview

Choose your approach

Prerequisites

Environments

Method 1: Cybrid's Plaid integration

Step 1: Generate a Plaid Link token

Sandbox redirect URIs

Step 2: Initialize Plaid Link SDK

Step 3: Create the external bank account

Method 2: Your own Plaid integration

Next steps

Related resources