Skip to main content

Plaid

In order to initiate credit and debit bank transfers, a Program must register a user's bank account.

Registration involves creating a Plaid link token, which allows the Program to present a bank login screen to its user. The Program completes registration by requesting to create a Plaid item, which represents a set of bank accounts belonging to the same institution.

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"
}

Banks that support OAuth

Plaid with OAuth Docs

If a bank supports OAuth, they will need to work with their implementation contact to set-up an OAuth redirect link. The desired redirect url should then be sent in the request payload when generating a link_token.

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

Once Plaid Link has been initialized, the Plaid Link UI can be loaded in the client application and the user will have the ability to authenticate with their chosen bank. After a successful login, Plaid Link will fire an onSuccess callback containing the public_token that will be used to complete the link. A public_token is a one-time use token that expires after 30 minutes.

Plaid Link UI Initial Screen

The user selects the institution for the external bank account they want to link.

Plaid Link UI Bank Selection Screen

Through the Plaid Link UI, the user can input their login credentials for their desired bank.

Plaid Link UI Login Screen

Once the user has successfully logged in, the Plaid Link UI will show a list of all the bank accounts that the user could connect. Our Plaid Link UI will allow the user to only connect one bank account at a time.

Plaid Link UI Single Account Selection Screen

The user will obtain an public_token and link an external bank account through Plaid by providing the account ID of the account they selected to link, as well as their profile ID and public_token. An access token is a token that is associated with the Item data that is being requested.

The external bank account is obtained by providing the Plaid client ID and Plaid client secret associated with the program and the specific account ID that will be linked. This call will return the external bank account information that was requested - including account and routing numbers.

The linked external bank account will now be saved to allow for debit and credit 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
}
]
}

The user has successfully linked a bank account.

Plaid Link UI Success Screen

Retrieving 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
}
}

Retrieving all bank accounts by profile

GET /profiles/:profile_id/plaid/items

Response:

{
"items": [
{
"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
}
]
},
{
"plaid_item_id": "Ed6bjNrDLJfGvZWwnkQlfxwoNz54B5C97ejBr",
"plaid_institution_name": "Chase",
"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.

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.

POST /plaid/items/:item_id/links

{
"select_accounts": "true"
}

Response:

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

Updating bank accounts 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"
}
]
}