Skip to main content

Plaid

In order to initiate bank transfers on behalf of a user, a Program must register one or more of the user's bank accounts.

Registration involves creating a Plaid link token, which allows the Program to present a login screen for the user's bank. The Program completes registration by creating a Plaid item, which represents bank accounts belonging to the same bank.

Tokens

NameDefinitionUse
link tokenA short-lived, one-time use tokenDetermines the effects of a login by a user (e.g. account registration, account changes, authentication renewal)
public tokenA short-lived one-time use token, returned after a user authenticatesRepresents a successful login; can be exchanged for an access token that authorizes business functions

Create a link_token to be associated with a profile.

POST /plaid/links

{
"profile_id": "db6e63c8-495d-440e-9fdf-8be68cd4378d"
}

Response:

{
"link_token": "link-sandbox-06f3ebca-2d62-48af-8512-2qa45e740cc8"
}

OAuth support

Plaid with OAuth Docs

If OAuth is required during authentication, then provide one of the following optional fields: android_package_name or redirect_uri.

POST /plaid/links

{
"profile_id": "db6e63c8-495d-440e-9fdf-8be68cd4378d",
"redirect_uri": "https://example.com/callback"
}

Response:

{
"link_token": "link-sandbox-06f3ebca-2d62-48af-8512-2qa45e740cc8"
}

The Plaid Link docs can be found: Plaid Link Docs

After creating a Plaid Link token, the Plaid Link UI can be loaded by the client application, allowing the user to login to their desired bank. Plaid Link will then return a public_token that can be used to create a Plaid item.

Begin by invoking the Plaid Link UI.

Plaid Link UI Initial Screen

The user selects their bank.

Plaid Link UI Bank Selection Screen

The user inputs their login credentials.

Plaid Link UI Login Screen

Upon successful login, the Plaid Link UI displays a list of bank accounts that the user may select.

Plaid Link UI Single Account Selection Screen

The user has successfully linked their bank accounts.

Plaid Link UI Success Screen

Create a Plaid item

The public_token, bank account ID's, and institution details returned during the Plaid Link login will be used in conjunction with the user's profile ID to create a Plaid item.

The bank accounts can then be used for credit and debit bank transfers.

POST /plaid/items

{
"profile_id": "db6e63c8-495d-440e-9fdf-8be68cd4378d",
"plaid_public_token": "public-sandbox-eef1c237-adee-4983-bf0e-8540914447d5",
"plaid_institution": {
"id": "ins_1",
"name": "Bank of America"
},
"plaid_account_ids": [
"oz5o8yWaXphZjJVx9A8aSQPxzyjdJ5URx5b71"
]
}

Response:

{
"plaid_item_id": "M5eVJqLnv3tbzdngLDp9FL5OlDNxlNhlE55op",
"plaid_institution_name": "Bank of America",
"bank_accounts": [
{
"id": "944e7d4c-9ce9-4e2b-aedb-7f3bec513517",
"account_number_last_four": "1234",
"routing_number": "100098765",
"profile_id": "db6e63c8-495d-440e-9fdf-8be68cd4378d",
"type": SAVINGS,
"status": OPEN
}
]
}

Retrieve a bank account

GET /plaid/accounts/:account_id

Response:

{
"plaid_item_id": "M5eVJqLnv3tbzdngLDp9FL5OlDNxlNhlE55op",
"plaid_institution_name": "Bank of America",
"bank_account": {
"id": "944e7d4c-9ce9-4e2b-aedb-7f3bec513517",
"account_number_last_four": "1234",
"routing_number": "100098765",
"profile_id": "db6e63c8-495d-440e-9fdf-8be68cd4378d",
"type": SAVINGS,
"status": OPEN
}
}

Retrieve bank accounts by profile

Use the optional query parameter include_login_status to determine if an active item requires the end user to re-authenticate. When not provided, the corresponding field in the response object is_login_required will be null.

GET /profiles/:profile_id/plaid/items?include_login_status=true

Response:

{
"items": [
{
"plaid_item_id": "M5eVJqLnv3tbzdngLDp9FL5OlDNxlNhlE55op",
"plaid_institution_name": "Bank of America",
"is_login_required": "false",
"bank_accounts": [
{
"id": "944e7d4c-9ce9-4e2b-aedb-7f3bec513517",
"account_number_last_four": "1234",
"routing_number": "100098765",
"profile_id": "db6e63c8-495d-440e-9fdf-8be68cd4378d",
"type": SAVINGS,
"status": OPEN
}
]
},
{
"plaid_item_id": "Ed6bjNrDLJfGvZWwnkQlfxwoNz54B5C97ejBr",
"plaid_institution_name": "Chase",
"is_login_required": "true",
"bank_accounts": [
{
"id": "dcc76b63-770f-412a-9f70-29df39846482",
"account_number_last_four": "7001",
"routing_number": "020064246",
"profile_id": "db6e63c8-495d-440e-9fdf-8be68cd4378d",
"type": SAVINGS,
"status": OPEN
}
]
}
]
}

A program can re-authorize access to a user's bank accounts by creating a link token for the corresponding Plaid item and having the user re-authenticate. If OAuth is required during authentication, then provide one of the following optional fields, either android_package_name or redirect_uri.

POST /plaid/items/:item_id/links

{
"select_accounts": "false"
}

Response:

{
"link_token": "link-sandbox-06f3ebca-2d62-48af-8512-2qa45e740cc8"
}

The select_accounts option creates a link token that displays an account selection screen to a user. If OAuth is required during authentication, then provide one of the following optional fields, either android_package_name or redirect_uri.

POST /plaid/items/:item_id/links

{
"select_accounts": "true"
}

Response:

{
"link_token": "link-sandbox-06f3ebca-2d62-48af-8512-2qa45e740cc8"
}

Update which bank accounts are associated with a Plaid item

A Program can change the bank accounts associated with a Plaid item by providing the selected account ID's to the PATCH /plaid/items/:item_id endpoint.

PATCH /plaid/items/:item_id

{
"plaid_bank_account_ids": [
"oz5o8yWaXphZjJVx9A8aSQPxzyjdJ5URx5b71",
"ee103f78-816a-42e9-902a-daef4b6662f6"
]
}

Response:

{
"plaid_item_id": "M5eVJqLnv3tbzdngLDp9FL5OlDNxlNhlE55op",
"plaid_institution_name": "Bank of America",
"bank_accounts": [
{
"id": "dcc76b63-770f-412a-9f70-29df39846482",
"routing_number": "100012345",
"account_number_last_four": "6789",
"profile_id": "3c595032-6898-4fd9-bd2d-1053763989b2",
"type": "SAVINGS",
"status": "OPEN"
},
{
"id": "9afe42d9-7491-4c1e-a35e-9d329ddb",
"routing_number": "100012345",
"account_number_last_four": "4259",
"profile_id": "3c595032-6898-4fd9-bd2d-1053763989b2",
"type": "SAVINGS",
"status": "OPEN"
}
]
}