Core resources

Plaid Account Link

38min

Overview
For publishers who do not have a Plaid account,  leverages it's Plaid partnership to enable publishers to track transactions for card-linked offers. To redeem these offers, each user must be linked to Plaid. See Get new link token﻿ for API details.
Link user account with Plaid
Plaid linking steps
﻿
Step 1: Link Card with Plaid
Step 2: Register Plaid token with Connect
Step 1 illustrates how a card is linked to Plaid and a public token is retrieved
The user initiates card linking by selecting the link-a-card option in the Publisher’s frontend (FE) application (app).
The Publisher’s FE app makes a call to the Publisher’s BE to request a link token.
The Publisher’s BE sends a request to  when a GET /plaid/link-token/{publisher_user_id} is made to get a link token. For more information, see Get new link token﻿ on how to do this.
﻿ processes the request and returns the Plaid link token to the Publisher’s BE.
The Publisher’s BE forwards the received link token to the Publisher FE app.
The Publisher’s FE app uses the link token to render the Plaid interface for the user.
﻿
Step 2 shows how the Plaid token is registered with :
After the user completes the linking process, the Publisher’s FE app sends the resulting public token to the Publisher BE.
The Publisher’s BE forwards the public token to  when a POST /plaid/public-token/{publisher_user_id} is made. For more information, see Save access token﻿ on how to do this.
﻿ validates the public token and sends a response to the Publisher’s BE to indicate that the linking of the card was successful.
The Publisher’s BE forwards the response to the Publisher’s FE app.
Integrate Finfare Connect API with Plaid
The table below outlines the available API calls and actions for Plaid.
Action
API call
Description
﻿Get new link token﻿ 
GET /plaid/link-token/{publisher_user_id}
Gets a Plaid link token to initiate the initial card linking process with Plaid for a specific user.
﻿ Get link token for re-authentication﻿ 
GET /plaid/auth-token/{institution_id}/{publisher_user_id}
Re-authenticates users with Plaid in the even that a user is no longer linked through Plaid.
﻿Save access token﻿ 
POST /plaid/public-token/{publisher_user_id}
Exchanges the public token for the access token.
﻿Remove access token﻿ 
DELETE /plaid/access-token/{publisher_user_id}/{institution_id}
Removes a saved access token from the  system.
﻿Get all linked cards﻿ 
GET /plaid/linked-cards/{publisher_user_id}
Get all linked cards for a specific user.
﻿Get linked cards for the institution﻿ 
GET /plaid/linked-cards/{publisher_user_id}/{institution_id}
Gets a user's linked cards for a specific institution.
﻿Send user Plaid access token to Finfare﻿ 
POST /plaid/access-token
Sends user's Plaid access token to  for instances where a Publisher is conducting their own plaid integration.
﻿
﻿GET /plaid/link-token/{publisher_user_id}﻿
Gets a Plaid link token to initiate the initial card linking process with Plaid for a specific user. 
To test the API, see Get new link token﻿. 
Path parameters
﻿
Name
Data type
Description
﻿{publisher_user_id}
﻿REQUIRED﻿
string
Unique identifier for the user sent by the publisher, to identify a user in the publisher’s system.
Query parameters
﻿
Name
Data type
Description
redirect_uri
string
The redirect_uri specifies the destination where users are forwarded after completing the Link flow, primarily supporting OAuth authentication flows when launching Link in a browser or webview. This  applies to iOS platform.

Requirements:
The redirect_uri should not contain query parameters.
In both Production and Sandbox, the URI must use https.
To specify any subdomain, use * as a wildcard (e.g., https://_*.example.com/oauth.html).
Finfare needs add the redirect_uri to the whitelist.
If initializing on Android, use android_package_name instead, and leave redirect_uri blank.
﻿
android_package_name
string
The android_package_name specifies the Android package name of your application and is required when using a link_token to initialize Link on an Android device.
Requirements:
Must be provided when initializing Link on Android.
Finfare needs add the android_package_name to the whitelist.
﻿
Responses
﻿
HTTP status 200
Returns the response that contains the link_token needed to link the user's card with Plaid. For more information, see Status and response codes﻿. 
﻿
LinkTokenResponse
Name
Data type
Description
link_token
string
Plaid token needed to link the user's card.
﻿
﻿GET /plaid/auth-token/{institution_id}/{publisher_user_id}﻿
Re-authenticates users with Plaid in the event that a user is no longer linked through Plaid. Unlinking with Plaid can happen when a user changes their password with financial institutions. Once re-authentication has been completed,  will have the user's latest token. 
To test the API, see Get link token for re-authentication﻿.
Path parameters
﻿
Name
Data type
Description
﻿{institution_id}
﻿REQUIRED﻿
string
The ID of the institution whose link needs to be re-established with Plaid. This is the ID for the financial institution in Plaid.
﻿{publisher_user_id}
﻿REQUIRED﻿
string
Unique identifier for the user sent by the publisher, to identify a user in the publisher’s system.
﻿
﻿
﻿
Responses
﻿
HTTP status 200
Returns a 200 response if the user has successfully re-authenticated and is linked to Plaid again. For more information, see Status and response codes﻿. 
﻿
Body
Name
Data type
Description
link_token
string
Plaid token needed to link the user's card.
﻿
﻿POST /plaid/public-token/{publisher_user_id}﻿
Exchanges the public token for the access token.
To test this API, see Save access token﻿. 
Path parameters
﻿
Name
Data type
Description
﻿{publisher_user_id}
﻿REQUIRED﻿
string
Unique identifier for the user sent by the publisher, to identify a user in the publisher’s system.
Body parameters
﻿
Name
Data type
Description
public_token
REQUIRED﻿
string
The token that the caller obtained once the user has successfully linked their account to Plaid.
institution_id
REQUIRED﻿
string
Plaid's institution ID.
institution_name
REQUIRED﻿
string
The financial institution name.
Responses
﻿
HTTP status 200
Returns a 200 response to indicate that the public token was validated and that the linking of the card was successful. For more information, see Status and response codes﻿. 
﻿
﻿DELETE /plaid/access-token/{publisher_user_id}/{institution_id}﻿
Removes a saved access token from the  system. This API can be used if a user wants to delete their account or unlink their account.
To test this API, see Remove access token﻿. Path parameters
﻿
Name
Data type
Description
﻿{publisher_user_id}
﻿REQUIRED﻿
string
Unique identifier for the user sent by the publisher, to identify a user in the publisher’s system.
﻿{institution_id}
REQUIRED﻿
string
The id of the institution whose token needs to be removed. This is the ID for the financial institution in Plaid.
﻿
Responses
﻿
HTTP status 200
Returns a 200 response to indicate that the token was successfully removed. For more information, see Status and response codes﻿. 
﻿
﻿GET /plaid/linked-cards/{publisher_user_id}﻿
Get all linked cards for a specific user. The response only returns active cards that are currently linked in Plaid. If a card is unlinked for any reason, that card will not appear in the response.
To test the API, see Get all linked cards﻿. 
Path parameters
﻿
Name
Data type
Description
﻿{publisher_user_id}
﻿REQUIRED﻿
string
Unique identifier for the user sent by the publisher, to identify a user in the publisher’s system.
Responses
﻿
HTTP status 200
Returns a 200 response to indicates success. For more information, see Status and response codes﻿. 
﻿
Body
linked_institutions
Name
Data type
Description
institution_id
string
The ID of the institution whose link needs to be re-established with Plaid. This is the ID for the financial institution in Plaid.
institution_name
string
The financial institution name.
logo
string
base64  image
The financial institution's logo.
logo_url
string
The URL for the financial institution's logo.
color
string
Color of the financial institution's logo.
linked_cards
Name
Data type
Description
account_id
string
The unique ID of the account type of the institution, for example, savings or checking.
name
string
Account name given by the institution.
mask
string
﻿
The last 4 digits of the account.
error
string
Possible values:
NEED_AUTHENTICATION - Plaid account needs to be re-authorized.
UNKNOWN - N/A contact support.
﻿
﻿GET /plaid/linked-cards/{publisher_user_id}/{institution_id}﻿
Gets a user's linked cards for a specific institution.
To test the API, see Get linked cards for the institution﻿. 
Path parameters
﻿
Name
Data type
Description
﻿{publisher_user_id}
REQUIRED﻿
string
Unique identifier for the user sent by the publisher, to identify a user in the publisher’s system.
﻿{institution_id}
REQUIRED﻿
string
The ID of the institution whose token needs to be removed. This is the ID for the financial institution in Plaid.
﻿
Responses
﻿
HTTP status 200
Returns a 200 response to indicates success. For more information, see Status and response codes﻿. 
﻿
Body
Institution
Name
Data type
Description
institution_id
string
The ID of the institution whose link needs to be re-established with Plaid. This is the ID for the financial institution in Plaid.
institution_name
string
The financial institution name.
logo
string
base64  image
The financial institution's logo.
logo_url
string
The URL for the financial institution's logo.
color
string
Color of the financial institution's logo.
linked_cards
Name
Data type
Description
account_id
string
The unique ID of the account type of the institution, for example, savings or checking.
name
string
Account name given by the institution.
mask
string
﻿
The last 4 digits of the account.
error
string
Possible values:
NEED_AUTHENTICATION - Plaid account needs to be re-authorized.
UNKNOWN - N/A contact support.
﻿
﻿POST /plaid/access-token
Sends user's Plaid access token to  for instances where a Publisher is conducting their own plaid integration.
To test the API, see Send user Plaid access token to Finfare﻿.
Body parameters
﻿
Name
Data type
Description
publisher_user_id
REQUIRED﻿
string
Unique identifier for the user sent by the publisher, to identify a user in the publisher’s system.
institution_id
REQUIRED﻿
string
The ID of the institution whose token needs to be removed. This is the ID for the financial institution in Plaid.
institution_name
REQUIRED﻿
string
The financial institution name.
plaid_access_token
REQUIRED﻿
string
The secret access token for Plaid.
Responses
﻿
HTTP status 200
Returns a 200 response to indicates success. For more information, see Status and response codes﻿. 

Action	API call	Description
Get new link token	GET /plaid/link-token/{publisher_user_id}	Gets a Plaid link token to initiate the initial card linking process with Plaid for a specific user.
Get link token for re-authentication	GET /plaid/auth-token/{institution_id}/{publisher_user_id}	Re-authenticates users with Plaid in the even that a user is no longer linked through Plaid.
Save access token	POST /plaid/public-token/{publisher_user_id}	Exchanges the public token for the access token.
Remove access token	DELETE /plaid/access-token/{publisher_user_id}/{institution_id}	Removes a saved access token from the system.
Get all linked cards	GET /plaid/linked-cards/{publisher_user_id}	Get all linked cards for a specific user.
Get linked cards for the institution	GET /plaid/linked-cards/{publisher_user_id}/{institution_id}	Gets a user's linked cards for a specific institution.
Send user Plaid access token to Finfare	POST /plaid/access-token	Sends user's Plaid access token to for instances where a Publisher is conducting their own plaid integration.

Name	Data type	Description
{publisher_user_id} REQUIRED	string	Unique identifier for the user sent by the publisher, to identify a user in the publisher’s system.

Name	Data type	Description
redirect_uri	string	The redirect_uri specifies the destination where users are forwarded after completing the Link flow, primarily supporting OAuth authentication flows when launching Link in a browser or webview. This applies to iOS platform. Requirements: The redirect_uri should not contain query parameters. In both Production and Sandbox, the URI must use https. To specify any subdomain, use * as a wildcard (e.g., https://_*.example.com/oauth.html). Finfare needs add the redirect_uri to the whitelist. If initializing on Android, use android_package_name instead, and leave redirect_uri blank.
android_package_name	string	The android_package_name specifies the Android package name of your application and is required when using a link_token to initialize Link on an Android device. Requirements: Must be provided when initializing Link on Android. Finfare needs add the android_package_name to the whitelist.

Name	Data type	Description
link_token	string	Plaid token needed to link the user's card.

Name	Data type	Description
{institution_id} REQUIRED	string	The ID of the institution whose link needs to be re-established with Plaid. This is the ID for the financial institution in Plaid.
{publisher_user_id} REQUIRED	string	Unique identifier for the user sent by the publisher, to identify a user in the publisher’s system.

Name	Data type	Description
link_token	string	Plaid token needed to link the user's card.

Name	Data type	Description
{publisher_user_id} REQUIRED	string	Unique identifier for the user sent by the publisher, to identify a user in the publisher’s system.

Name	Data type	Description
public_token REQUIRED	string	The token that the caller obtained once the user has successfully linked their account to Plaid.
institution_id REQUIRED	string	Plaid's institution ID.
institution_name REQUIRED	string	The financial institution name.

Name	Data type	Description
{publisher_user_id} REQUIRED	string	Unique identifier for the user sent by the publisher, to identify a user in the publisher’s system.
{institution_id} REQUIRED	string	The id of the institution whose token needs to be removed. This is the ID for the financial institution in Plaid.

Name	Data type	Description
{publisher_user_id} REQUIRED	string	Unique identifier for the user sent by the publisher, to identify a user in the publisher’s system.

Name	Data type	Description
institution_id	string	The ID of the institution whose link needs to be re-established with Plaid. This is the ID for the financial institution in Plaid.
institution_name	string	The financial institution name.
logo	string base64 image	The financial institution's logo.
logo_url	string	The URL for the financial institution's logo.
color	string	Color of the financial institution's logo.

Name	Data type	Description
account_id	string	The unique ID of the account type of the institution, for example, savings or checking.
name	string	Account name given by the institution.
mask	string	The last 4 digits of the account.
error	string	Possible values: NEED_AUTHENTICATION - Plaid account needs to be re-authorized. UNKNOWN - N/A contact support.

Name	Data type	Description
{publisher_user_id} REQUIRED	string	Unique identifier for the user sent by the publisher, to identify a user in the publisher’s system.
{institution_id} REQUIRED	string	The ID of the institution whose token needs to be removed. This is the ID for the financial institution in Plaid.

Name	Data type	Description
institution_id	string	The ID of the institution whose link needs to be re-established with Plaid. This is the ID for the financial institution in Plaid.
institution_name	string	The financial institution name.
logo	string base64 image	The financial institution's logo.
logo_url	string	The URL for the financial institution's logo.
color	string	Color of the financial institution's logo.

Name	Data type	Description
account_id	string	The unique ID of the account type of the institution, for example, savings or checking.
name	string	Account name given by the institution.
mask	string	The last 4 digits of the account.
error	string	Possible values: NEED_AUTHENTICATION - Plaid account needs to be re-authorized. UNKNOWN - N/A contact support.

Name	Data type	Description
publisher_user_id REQUIRED	string	Unique identifier for the user sent by the publisher, to identify a user in the publisher’s system.
institution_id REQUIRED	string	The ID of the institution whose token needs to be removed. This is the ID for the financial institution in Plaid.
institution_name REQUIRED	string	The financial institution name.
plaid_access_token REQUIRED	string	The secret access token for Plaid.

Terms and Conditions

Introduction

Plaid Account Link

Overview

Link user account with Plaid

Integrate Finfare Connect API with Plaid

﻿GET /plaid/link-token/{publisher_user_id}﻿

Path parameters

Query parameters

﻿

Responses

﻿GET /plaid/auth-token/{institution_id}/{publisher_user_id}﻿

Path parameters

Responses

﻿POST /plaid/public-token/{publisher_user_id}﻿

Path parameters

Body parameters

Responses

﻿DELETE /plaid/access-token/{publisher_user_id}/{institution_id}﻿

Responses

﻿GET /plaid/linked-cards/{publisher_user_id}﻿

Path parameters

Responses

﻿GET /plaid/linked-cards/{publisher_user_id}/{institution_id}﻿

Path parameters

Responses

﻿POST /plaid/access-token

Body parameters

Responses

GET /plaid/link-token/{publisher_user_id}

GET /plaid/auth-token/{institution_id}/{publisher_user_id}

POST /plaid/public-token/{publisher_user_id}

DELETE /plaid/access-token/{publisher_user_id}/{institution_id}

GET /plaid/linked-cards/{publisher_user_id}

GET /plaid/linked-cards/{publisher_user_id}/{institution_id}

POST /plaid/access-token