(Beta) Data Transparency Messaging Migration Guide
How to enable Data Transparency Messaging for your application
Introduction
Plaid has introduced Data Transparency Messaging into the Link flow as a beta product. This experience provides users with a greater understanding of the types of data that they share with you and Plaid. When using Data Transparency Messaging, a user is informed of the specific data types that you are requesting and the reason that you are requesting them. If you want access to additional data from a user after their initial Link, they must consent to sharing that data through a separate consent flow.
This guide covers the client and server-side changes required to implement the Data Transparency Messaging feature.
What's new
- The API will only return data for products provided in your Link configuration. In addition to the existing
products
field, we have added a new configuration field calledadditional_consented_products
that can be used to gather consent for additional products. - The consent pane can be configured to display a pop-up that allows users to see what data is being requested. You will be able to specify your use case and why you need the data on the pop-up. There is also an option to add a standalone Data Transparency Messaging pane between institution select and credentials in addition to the consent pane for customers who want to make data transparency even more visible in the Link flow.
- Products not provided in the Link configuration can not be accessed without going through update mode.
Migration overview
- Review the implementation considerations.
- Review your API integration and potentially add the
additional_consented_products
field with products you want to gather consent for prior to enabling. Every product that you currently use should be included in either theproducts
oradditional_consented_products
fields. - Update Link customizations to enable Data Transparency Messaging
- (Optional) Configure update mode to collect consent in the future
Implementation considerations
Previously, as long as you were approved and enabled for a product during your Plaid Dashboard Production Request process, you could request and start using it by calling the corresponding product API route on any Item. Going forward, any Item that goes through Link with Data Transparency Messaging enabled restricts your access to new product data unless new consent is collected through update mode. This behavior does not apply to Items created prior to enabling Data Transparency Messaging.
If you anticipate upgrading to a product in the future, or if you currently use a product but don’t want Plaid to try to extract that data immediately, you can create a Link token with additional_consented_products
. These products will be shown in Link as part of Data Transparency Messaging, but will not be fetched or billed until you request them. Writing to the additional_consented_products
field prior to enabling Data Transparency Messaging will not have any impact on your current Items, but it is recommended that you do so to ensure that new Items will have all of the proper permissions once you enable the feature.
Products placed in the additional_consented_products
field do not have any impact on institution filtering or account subtype filtering. For example, if auth
is an additional_consented_product
, users will be allowed to select any account, not just checking/savings accounts.
Update Link customizations
To opt into Data Transparency Messaging, go to your Link customization or create a new one (you may duplicate an existing customization by using the duplicate feature), click on the Data Transparency Tab on the Consent Pane and enable the toggle. After enabling the toggle, you can customize the use case. Be aware that turning this feature on also changes the content on the Consent Pane. You can view the updated content in the General tab.
In addition to the updated Consent Pane, you can also enable a standalone Data Transparency Messaging pane for additional transparency. To do that, navigate to the Data Transparency pane and enable the feature. This pane works together with the Consent Pane, so the feature must first be enabled on the Consent Pane in order to enable the standalone pane, and both will be present in the flow. The use case on the standalone pane is shared with the use case on the Consent Pane popup, and can only be customized there.
Once you’ve selected how you want to present Data Transparency Messaging to consumers and written your use case, click Publish. Your changes will go into effect the next time you initialize Link with this customization. Only newly created Items created with the updated customization will have the new API behavior; existing Items will not be affected.
If you want to disable the feature, you can toggle it off in the Data Transparency tab and publish your changes.
If you currently use additional products after Link that you do not initialize via the products
field, it is recommended that you update your /link/token/create
code to include additional_consented_products
before enabling this feature in the Plaid Dashboard to avoid losing access to the additional API endpoints on your new Items.
API changes
For Items that have gone through Link with Data Transparency Messaging enabled, there will be a new consented_products
field returned by the /item/get
endpoint, as well as all product endpoints. This field contains all of the products that consent has been collected for on this Item.
For Items with the consented_products
field set, you will see the error code ADDITIONAL_CONSENT_REQUIRED
if you do not have consent to a product you are trying to request. This is the same error you would get if you are not enabled for the product.
Certain financial institutions implement opt-outs for sharing data types in their OAuth flow. If a user opts out of sharing certain financial data, you may be blocked from accessing certain product routes. This error code will be returned as ACCESS_NOT_GRANTED
.
To resolve ADDITIONAL_CONSENT_REQUIRED
errors, you should send the user through update mode with all of the products you want consent for. To resolve ACCESS_NOT_GRANTED
errors, you should send the user through update mode to do an Item repair. No products should be passed in with this request. We also recommend providing the user with context on what data you are requesting and why, prior to launching update mode, so they are more likely to give consent.
New SDK events and view names for the Data Transparency Messaging consent pane and standalone pane have also been added. The new view names are DATA_TRANSPARENCY
and DATA_TRANSPARENCY_CONSENT
. The new event is VIEW_DATA_TYPES
, which is triggered when a user views the popup data type modal on the Consent Pane.
Data types and consent
The products you request for Link Initialization are not mapped 1:1 with the different data types displayed. Our goal is to allow consumers to understand what types of data they are permissioning, and product names alone can be confusing to consumers. Because data types can be broad, in certain cases, you will get consent for more than just the products you initialize Link with. For example, the Assets product requires consent to both the "Transactions" and the "Account Holder Information" data types, so the Transactions and Identity products will both be consented to by default. To understand which products you have consent to access for a given Item, you can use the consented_products
field on the /item/get
or product endpoints as detailed above.
Data types
Account and balance info | May include account details such as account name, type, description, balances, and masked account number. |
Contact details | May include account owner name, email, phone, and address. |
Account and routing numbers | Includes your account and bank routing number. |
Transactions | May include transaction details such as amounts, dates, price, location, spending categories and descriptions, and insights like recurring transactions. |
Credit and loans | May include details about your credit and loan accounts, such as balance, payment dates and amounts due, credit limit, repayment status, interest rate, loan terms, and originator info. |
Investments | May include info about investment accounts, such as securities details, quantity, price, and transactions. |
Payroll info | May include income or employment data, such as gross earnings, check amount, as well as other earnings or employment info. |
Transaction risk info | May include account info such as activity and usage, holder info, and Plaid connection history. |
Requesting consent for additional products in update mode
If you would like to start collecting product data for an Item that you did not collect enough consent for during initial creation, you are able to send that item through update mode to collect new consent. To add this additional consent, initialize Link for update mode. For OAuth institutions, ensure you configure the Link token with a redirect URI, as described in Configure your Link token with your redirect URI. Your call to /link/token/create
should include the following:
- The
additional_consented_products
field should be set to include any new products you want to gather consent for.- For example, if Link was initialized with just Transactions and you want to upgrade to Identity, you would pass in
identity
to theadditional_consented_products
field. - To see the currently authorized and consented products on an Item, use the
/item/get
endpoint
- For example, if Link was initialized with just Transactions and you want to upgrade to Identity, you would pass in
- The
link_customization_name
should be set to a customization with Data Transparency Messaging enabled. The use case string should also be broadened to include your reasons for accessing the new data. If the use case is not customized, the default use case will be present on the Data Transparency Messaging pane.
If the upgrade was successful, you will receive the onSuccess()
callback and you will have access to the API endpoints for all of the products you passed into Link update mode. The new products will only be billed once the related API endpoints are called, even if they would otherwise be billed upon Item initialization (e.g., Transactions).
Using Data Transparency Messaging with legacy public key integrations
The Data Transparency experience is compatible with legacy public key integrations, but the additional_consented_products
configuration field will not be usable. All products will have to be passed in through the standard products
field.