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
Name | Definition | Use |
---|---|---|
link token | A short-lived, one-time use token | Determines the effects of a login by a user (e.g. account registration, account changes, authentication renewal) |
public token | A short-lived one-time use token, returned after a user authenticates | Represents a successful login; can be exchanged for an access token that authorizes business functions |
Create a link token
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
Contact your program coordinator to register a redirect URI and or Android package name.
When creating a link token provide one of the following 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"
}
Display the Plaid Link UI
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.
The user selects their bank.
The user inputs their login credentials.
Upon successful login, the Plaid Link UI displays a list of bank accounts that the user may select.
The user has successfully linked their bank accounts.
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
}
]
}
]
}
Create a link token for re-authenticating
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"
}
Create a link token for updating a Plaid item
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"
}
]
}