# Plaid Integration

![Plaid Bank Accounts](/assets/plaid.4853ed4ec356b78bdf719153759557101b000816f50ba0e97146d9b7d58d0622.fec90461.svg)

Finix and Plaid have partnered to let you add your customers' bank accounts to Finix's platform seamlessly and securely. Plaid instantly verifies bank account existence and ownership, providing a fast and secure way to board your customers onto Finix.

Finix offers multiple ways to add bank accounts with Plaid:

- Add bank accounts with an existing Plaid Account
- Use Finix's Hosted Onboarding Forms for sellers, which have Plaid Link embedded by default


## Example Use Cases

You can use Finix `payment_instruments` connected and verified with Plaid for:

- **[ACH Direct Debits](/guides/online-payments/bank-payments/ach-direct-debits):** debit buyer bank accounts for goods and services
- **[Bank Payouts](/guides/payouts/bank-payouts):** send money to recipients
- **[Onboarding Sellers](/guides/platform-payments/onboarding-sellers) and [Recipients](/guides/payouts/bank-payouts/):** onboard sellers and recipients with our APIs or onboarding forms


This guide explains how Plaid fits into those Finix use cases. Once you have a specific use case in mind, please refer to its respective guide to understand its full process (for example, how to [onboard a seller](/guides/platform-payments/onboarding-sellers)).

## Using Your Plaid Account

This section of the guide is for Finix customers who have existing Plaid accounts and want to use Finix for one of the payments use cases above. If you do not have a Plaid account and would like a referral to Plaid, please email `sales@finix.com`. A Finix Sales Representative will assist you.

### Step 1: Embed Plaid Link Into Your Application

The first step is embedding [Plaid Link](https://plaid.com/docs/link/) into your application. Link is a client-side experience that lets your customers connect their bank accounts securely and seamlessly through Plaid. After Link, you can use your customers' bank account connections to create Plaid `processor_tokens` and, ultimately, Finix `payment_instruments`.

To guide your integration, we recommend familiarizing yourself with [Plaid's guide to the Plaid + Finix integration](https://plaid.com/docs/auth/partnerships/finix/). Plaid's guide has information on how to embed Plaid Link into your application and create Plaid `proscessor_tokens`.

Creating the Plaid Link Token
Finix uses Plaid's Auth and Identity endpoints to tokenize Payment Instruments from Plaid tokens. You must include both `auth` and `identity` in the Plaid Link Token `products` array.

### Step 2: Create a Plaid Processor Token for the Finix Processor

With Plaid Link embedded into your application, you can exchange your customers' Plaid `access_tokens` for `processor_tokens` with `processor: finix`. Finix uses `processor_tokens` to get and save your customers' bank account details in the next step.


```shell Plaid Processor Token Request
curl "https://sandbox.plaid.com/processor/token/create" \
    -H 'Content-Type: application/json' \
    -X POST \
    -d '{
        "client_id": "${PLAID_CLIENT_ID}",
        "secret": "${PLAID_SECRET}",
        "access_token": "${ACCESS_TOKEN}",
        "account_id": "${ACCOUNT_ID}",
        "processor": "finix"
    }'
```


```json Plaid Processor Token
{
    "processor_token": "processor-sandbox-0asd1-a92nc",
    "request_id": "kxiMB5rN03wiLMD"
}
```

### Step 3: Create a Finix Payment Instrument

Now, you can use the Plaid `processor_token` to create a Finix `payment_instrument`:


```shell Payment Instrument Request
curl https://finix.sandbox-payments-api.com/payment_instruments \
    -H "Content-Type: application/json" \
    -H 'Finix-Version: 2022-02-01' \
    -u  USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e \
    -d '{
      "identity": "IDpYDM7J9n57q849o9E9yNrG",
      "third_party": "PLAID",
      "third_party_token": "processor-sandbox-0asd1-a92nc",
      "type": "BANK_ACCOUNT"
    }'
```


```json Payment Instrument
{
    "id": "PI3AbkuRR1JbT5kPiGQCXvD9",
    "created_at": "2022-10-11T01:42:53.29Z",
    "updated_at": "2022-10-11T01:42:53.29Z",
    "application": "APgPDQrLD52TYvqazjHJJchM",
    "created_via": "API",
    "currency": "USD",
    "enabled": true,
    "third_party": "PLAID",
    "third_party_token": "processor-sandbox-0asd1-a92nc",
    "fingerprint": "FPRd5moHxL3Ltuvk4cczxetCg",
    "identity": "IDpYDM7J9n57q849o9E9yNrG",
    "instrument_type": "BANK_ACCOUNT",
    "account_type": "PERSONAL_CHECKING",
    "bank_account_validation_check": "VALID",
    "bank_code": "123123123",
    "country": "USA",
    "masked_account_number": "XXXXX3123",
    "name": "John Doe",
    "tags": {},
    "type": "BANK_ACCOUNT",
    "_links": {}
}
```

This diagram summarizes that process across the Plaid and Finix platforms:

![Alt text](/assets/plaid-overview.2acc4375eb77b30e145f3593a8c5b176c44f6cd5d06a9c8f1e7cb359e55e5463.28b10c14.svg)

## Using Finix's Plaid Account

This section shows you how to use Finix’s Third Party Tokens API to Embed Plaid Link Into Your Application.This is for Finix customers that do not have a direct relationship with Plaid, but still want to offer a secure and seamless bank account connection experience.

There is a cost associated with adding bank accounts with Plaid. If you are interested in this solution, please contact your Finix point-of-contact for pricing information.

Finix's `Third Party Tokens` API lets you embed [Plaid Link](https://plaid.com/docs/link/) directly into your own application. Link is a client-side experience that lets your customers connect their bank accounts securely and seamlessly through Plaid. After your customers connect their bank accounts through Link, you can use Finix's `Third Party Tokens` API to get a `PLAID_PROCESSOR_TOKEN` and, afterward, create a Finix `payment_instrument`.

### Step 1: Get a Plaid Link Token with Finix's API

First, get a unique `PLAID_LINK_TOKEN` from Finix's `Third Party Tokens` API, specifying the allowed `countries` in the request. You'll use this token to open Plaid Link in your application.

USA

```shell Plaid Link Token Request (USA)
curl https://finix.sandbox-payments-api.com/third_party_tokens \
    -H 'Content-Type: application/json' \
    -H 'Finix-Version: 2022-02-01' \
    -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e \
    -X POST \
    -d '{
        "type": "PLAID_LINK_TOKEN",
        "countries": ["USA"],
        "language": "en"
    }'
```


```json Plaid Link Token (USA)
{
    "id": "third_party_token_mQA3yCNwp1jj86bFrNjS3U",
    "created_at": "2024-03-13T22:46:56.410108Z",
    "updated_at": "2024-03-13T22:46:56.410111Z",
    "type": "PLAID_LINK_TOKEN",
    "countries": ["US"],
    "language": "en",
    "token": "link-sandbox-206aa75b-c96f-48b0-a8b8-1060e992ec36",
    "expires_at": "2024-03-14T02:46:56Z"
}
```

CAN

```shell Plaid Link Token Request (CAN)
curl https://finix.sandbox-payments-api.com/third_party_tokens \
    -H 'Content-Type: application/json' \
    -H 'Finix-Version: 2022-02-01' \
    -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e \
    -X POST \
    -d '{
        "type": "PLAID_LINK_TOKEN",
        "countries": ["CAN"],
        "language": "en"
    }'
```


```json Plaid Link Token (CAN)
{
    "id": "third_party_token_qqV2rHtmssB5Cyv7QnvDTD",
    "created_at": "2024-03-13T22:48:12.810614Z",
    "updated_at": "2024-03-13T22:48:12.810617Z",
    "type": "PLAID_LINK_TOKEN",
    "countries": ["CA"],
    "language": "en",
    "token": "link-sandbox-d52d7dc4-af25-4c61-992b-054a98464e32",
    "expires_at": "2024-03-14T02:48:13Z"
}
```

### Step 2: Open Plaid Link

Next, use the `PLAID_LINK_TOKEN` to open Plaid Link in your application. Plaid offers [multiple ways](https://plaid.com/docs/link/#initializing-link) to embed and open Plaid Link in your application. For example, you can use Plaid's [JavaScript](https://plaid.com/docs/link/web/), [React](https://github.com/plaid/react-plaid-link), [iOS](https://plaid.com/docs/link/ios/), or [Android](https://plaid.com/docs/link/android/) SDKs.

Here is an example of how you can initalize Plaid Link with JavaScript:


```javascript JS Example
const handler = Plaid.create({
    onEvent: (eventName, metadata) => {},
    onExit: (err, metadata) => {},
    onLoad: () => {},
    onSuccess: (public_token, metadata) => {},
    token: "PLAID_LINK_TOKEN",
});
```


```javascript React Example
const config: PlaidLinkOptions = {
    onEvent: (eventName, metadata) => {}
    onExit: (err, metadata) => {}
    onSuccess: (public_token, metadata) => {}
    token: 'PLAID_LINK_TOKEN',
};
const { open, exit, ready } = usePlaidLink(config);
```

### Step 3: Exchange Public Token for Processor Token

After your users complete the Plaid Link experience, Plaid will give you a temporary `public_token`. Use Finix's `Third Party Tokens` API to exchange the `public_token` for a permanent `PLAID_PROCESSOR_TOKEN`. The `public_token` expires after 30 minutes, so we recommend creating the `PLAID_PROCESSOR_TOKEN` immediately.


```shell
curl https://finix.sandbox-payments-api.com/third_party_tokens \
    -H 'Content-Type: application/json' \
    -H 'Finix-Version: 2022-02-01' \
    -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e \
    -X POST \
    -d '{
        "plaid_public_token": "public-sandbox-49aa938e-a35c-45de-b388-9824a9fc9fde",
        "plaid_account_id": "NDDakaq8kyip1JqVryB5igvGy4R733cyawPov",
        "type": "PLAID_PROCESSOR_TOKEN"
    }'
```


```json
{
    "id": "third_party_token_xx",
    "created_at": "2022-10-11T01:42:53.29Z",
    "plaid_public_token": "public-sandbox-49aa938e-a35c-45de-b388-9824a9fc9fde",
    "token": "processor-sandbox-0asd1-a92nc", // [!code highlight]
    "type": "PLAID_PROCESSOR_TOKEN", // [!code highlight]
    "updated_at": "2022-10-11T01:42:53.29Z"
}
```

### Step 4: Create a Finix Payment Instrument

Finally, you can use the `PLAID_PROCESSOR_TOKEN` to create a Finix `payment_instrument`:


```shell Payment Instrument Request
curl https://finix.sandbox-payments-api.com/payment_instruments \
    -H "Content-Type: application/json" \
    -H 'Finix-Version: 2022-02-01' \
    -u  USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e \
    -d '{
        "identity": "IDpYDM7J9n57q849o9E9yNrG",
        "third_party": "PLAID",
        "third_party_token": "processor-sandbox-0asd1-a92nc",
        "type": "BANK_ACCOUNT"
    }'
```


```json Payment Instrument
{
    "id": "PI3AbkuRR1JbT5kPiGQCXvD9",
    "created_at": "2022-10-11T01:42:53.29Z",
    "updated_at": "2022-10-11T01:42:53.29Z",
    "application": "APgPDQrLD52TYvqazjHJJchM",
    "created_via": "API",
    "currency": "USD",
    "enabled": true,
    "third_party": "PLAID", // [!code highlight]
    "third_party_token": "processor-sandbox-0asd1-a92nc", // [!code highlight]
    "fingerprint": "FPRd5moHxL3Ltuvk4cczxetCg",
    "identity": "IDpYDM7J9n57q849o9E9yNrG",
    "instrument_type": "BANK_ACCOUNT",
    "account_type": "PERSONAL_CHECKING",
    "bank_account_validation_check": "VALID",
    "bank_code": "123123123",
    "country": "USA",
    "masked_account_number": "XXXXX3123",
    "name": "John Doe",
    "tags": {},
    "type": "BANK_ACCOUNT",
    "_links": {}
}
```

We recommend providing your customers a secondary path to providing their bank account details in the event they run into issues with Plaid Link, given Plaid may not support their specific financial institution. Typically, this involves letting customers provide their bank account and routing numbers manually if they cannot or do not want to use Plaid Link.

### Migrating Plaid Access Tokens

If you have previously connected your customers' bank accounts with Plaid, you can migrate those bank account connections onto Finix's platform. To do this, you will need to use Plaid's `/processor/token/create` endpoint to exchange each customer's Plaid `access_token` for a `processor_token` with `processor: finix`.

For more information on creating the `processor_token`, please see [Plaid's guide to the Plaid + Finix integration](https://plaid.com/docs/auth/partnerships/finix/).

## Seller Onboarding

If you prefer a low-code or no-code solution, you can use [Finix's Onboarding Forms](/guides/platform-payments/onboarding-sellers/seller-onboarding-forms) to let your sellers connect their bank accounts with Plaid during the Finix onboarding process. Finix's Onboarding Forms let sellers on your platform choose whether to connect their bank accounts through Plaid Link or manually, giving them the flexibility to pick the option that works best for them.

![Alt text](/assets/plaid-onboarding-forms.454ffcd1c766aed83e2853aaf35f970e68870eedb0c6c9c14449a885a3d7603a.08ff7529.png)

## Verifying Bank Accounts

When you create `payment_instruments` with Plaid `processor_tokens`, Finix uses Plaid Auth to securely get and save the account and routing numbers. In addition, Finix uses Plaid Identity to verify the ownership of the bank account, which is critical for mitigating fraud and protecting our customers.

Bank accounts connected and verified with Plaid will have `bank_account_validation_check: VALID`:


```json Plaid-Connected Payment Instrument
{
    "id": "PI3AbkuRR1JbT5kPiGQCXvD9",
    "created_at": "2022-10-11T01:42:53.29Z",
    "updated_at": "2022-10-11T01:42:53.29Z",
    "application": "APgPDQrLD52TYvqazjHJJchM",
    "created_via": "API",
    "currency": "USD",
    "enabled": true,
    "third_party": "PLAID",
    "third_party_token": "processor-sandbox-0asd1-a92nc",
    "fingerprint": "FPRd5moHxL3Ltuvk4cczxetCg",
    "identity": "IDpYDM7J9n57q849o9E9yNrG",
    "instrument_type": "BANK_ACCOUNT",
    "account_type": "PERSONAL_CHECKING",
    "bank_account_validation_check": "VALID", // [!code highlight]
    "bank_code": "123123123",
    "country": "USA",
    "masked_account_number": "XXXXX3123",
    "name": "John Doe",
    "tags": {},
    "type": "BANK_ACCOUNT",
    "_links": {}
}
```

## Plaid Benefits

Connecting bank accounts with Plaid is advantageous by offering:

- **Better customer experience:** Plaid lets your customers add their bank account details simply by logging into their bank account, rather than providing their bank account and routing numbers manually
- **Faster onboarding:** Plaid verifies bank account existence and ownership instantly, providing the fastest onboarding experience for your customers
- **Increased security**: Plaid limits the need for Finix customers to handle bank account data directly, which is preferable from a security standpoint


## Supported Bank Accounts

Finix supports U.S. and Canadian Plaid bank account connections. Finix uses Plaid's Auth API to create Payment Instruments with the following details.

### U.S. bank accounts

- Account Number
- Routing Number


### Canadian bank accounts

- Account Number
- Transit Number
- Institution Number