Link Web SDK

Plaid.create accepts one argument, a configuration Object, and returns an Object with three functions, open, exit, and destroy. Calling open will open Link and display the Consent Pane view, calling exit will close Link, and calling destroy will clean up the iframe.
It is recommended to call Plaid.create when initializing the view that is responsible for loading Plaid, as this will allow Plaid to pre-initialize Link, resulting in lower UI latency upon calling open, which can increase Link conversion.
When using the React SDK, this method is called usePlaidLink and returns an object with four values, open, exit, ready, and error. The values open and exit behave as described above. ready is a passthrough for onLoad and will be true when Link is ready to be opened. error is populated only if Plaid fails to load the Link JavaScript. There is no separate method to destroy Link in the React SDK, as unmount will automatically destroy the Link instance.
Note: Control whether or not your Link integration uses the Account Select view from the Dashboard.

// The usePlaidLink hook manages Plaid Link creation
// It does not return a destroy function;
// instead, on unmount it automatically destroys the Link instance
const config: PlaidLinkOptions = {
  onSuccess: (public_token, metadata) => {}
  onExit: (err, metadata) => {}
  onEvent: (eventName, metadata) => {}
  token: 'GENERATED_LINK_TOKEN',
};

const { open, exit, ready } = usePlaidLink(config);

The onSuccess callback is called when a user successfully links an Item. It takes two arguments: the public_token and a metadata object.

import {
  PlaidLinkOnSuccess,
  PlaidLinkOnSuccessMetadata,
} from 'react-plaid-link';

const onSuccess = useCallback<PlaidLinkOnSuccess>(
  (public_token: string, metadata: PlaidLinkOnSuccessMetadata) => {
    // log and save metadata
    // exchange public token (if using Item-based products)
    fetch('//yourserver.com/exchange-public-token', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
      },
      body: {
        public_token,
      },
    });
  },
  [],
);

{
  institution: {
    name: 'Wells Fargo',
    institution_id: 'ins_4'
  },
  accounts: [
    {
      id: 'ygPnJweommTWNr9doD6ZfGR6GGVQy7fyREmWy',
      name: 'Plaid Checking',
      mask: '0000',
      type: 'depository',
      subtype: 'checking',
      verification_status: null
    },
    {
      id: '9ebEyJAl33FRrZNLBG8ECxD9xxpwWnuRNZ1V4',
      name: 'Plaid Saving',
      mask: '1111',
      type: 'depository',
      subtype: 'savings'
    }
    ...
  ],
  link_session_id: '79e772be-547d-4c9c-8b76-4ac4ed4c441a'
}

The onExit callback is called when a user exits Link without successfully linking an Item, or when an error occurs during Link initialization. onExit takes two arguments, a nullable error object and a metadata object. The metadata parameter is always present, though some values may be null. Note that onExit will not be called when Link is destroyed in some other way than closing Link, such as the user hitting the browser back button or closing the browser tab on which the Link session is present.

import {
  PlaidLinkOnExit,
  PlaidLinkOnExitMetadata,
  PlaidLinkError,
} from 'react-plaid-link';

const onExit = useCallback<PlaidLinkOnExit>(
  (error: PlaidLinkError, metadata: PlaidLinkOnExitMetadata) => {
    // log and save error and metadata
    // handle invalid link token
    if (error != null && error.error_code === 'INVALID_LINK_TOKEN') {
      // generate new link token
    }
    // to handle other error codes, see https://plaid.com/docs/errors/
  },
  [],
);

{
  error_type: 'ITEM_ERROR',
  error_code: 'INVALID_CREDENTIALS',
  error_message: 'the credentials were not correct',
  display_message: 'The credentials were not correct.',
}

{
  institution: {
    name: 'Wells Fargo',
    institution_id: 'ins_4'
  },
  status: 'requires_credentials',
  link_session_id: '36e201e0-2280-46f0-a6ee-6d417b450438',
  request_id: '8C7jNbDScC24THu'
}

The onEvent callback is called at certain points in the Link flow. It takes two arguments, an eventName string and a metadata object.
The metadata parameter is always present, though some values may be null. Note that new eventNames, metadata keys, or view names may be added without notice.
The OPEN, LAYER_READY, LAYER_NOT_AVAILABLE, and LAYER_AUTOFILL_NOT_AVAILABLE events will fire in real time; subsequent events will fire at the end of the Link flow, along with the onSuccess or onExit callback. Callback ordering is not guaranteed; onEvent callbacks may fire before, after, or surrounding the onSuccess or onExit callback, and event callbacks are not guaranteed to fire in the order in which they occurred. If you need to determine the exact time when an event happened, use the timestamp in the metadata.
The following callback events are stable, which means that they are suitable for programmatic use in your application's logic: OPEN, EXIT, HANDOFF, SELECT_INSTITUTION, ERROR, BANK_INCOME_INSIGHTS_COMPLETED, IDENTITY_VERIFICATION_PASS_SESSION, IDENTITY_VERIFICATION_FAIL_SESSION, IDENTITY_MATCH_FAILED, IDENTITY_MATCH_PASSED, LAYER_READY, LAYER_NOT_AVAILABLE, LAYER_AUTOFILL_NOT_AVAILABLE. The remaining callback events are informational and subject to change and should be used for analytics and troubleshooting purposes only.

import {
  PlaidLinkOnEvent,
  PlaidLinkOnEventMetadata,
  PlaidLinkStableEvent,
} from 'react-plaid-link';

const onEvent = useCallback<PlaidLinkOnEvent>(
  (
    eventName: PlaidLinkStableEvent | string,
    metadata: PlaidLinkOnEventMetadata,
  ) => {
    // log eventName and metadata
  },
  [],
);

{
  error_type: 'ITEM_ERROR',
  error_code: 'INVALID_CREDENTIALS',
  error_message: 'the credentials were not correct',
  exit_status: null,
  institution_id: 'ins_4',
  institution_name: 'Wells Fargo',
  institution_search_query: 'wellsf',
  mfa_type: null,
  view_name: 'ERROR'
  request_id: 'm8MDnv9okwxFNBV',
  link_session_id: '30571e9b-d6c6-42ee-a7cf-c34768a8f62d',
  timestamp: '2017-09-14T14:42:19.350Z',
  selection: null,
}

Calling open will display the Consent Pane view to your user, starting the Link flow. Once open is called, you will begin receiving events via the onEvent callback.

const { open, exit, ready } = usePlaidLink(config);

// Open Link
if (ready) {
  open();
}

The exit function allows you to programmatically close Link. Calling exit will trigger either the onExit or onSuccess callbacks.
The exit function takes a single, optional argument, a configuration Object.

const { open, exit, ready } = usePlaidLink(config);

// Graceful exit - Link may display a confirmation screen
// depending on how far the user is in the flow
exit();

const { open, exit, ready } = usePlaidLink(config);

// Force exit - Link exits immediately
exit({ force: true });

The destroy function allows you to destroy the Link handler instance, properly removing any DOM artifacts that were created by it. Use destroy() when creating new replacement Link handler instances in the onExit callback.

// On unmount usePlaidLink hook automatically destroys any
// existing link instance

The submit function is currently only used in the Layer product. It allows the client application to submit additional user-collected data to the Link flow (e.g. a user phone number).

const { open, exit, submit } = usePlaidLink(config);

// After collecting a user phone number...
submit({
    "phone_number": "+14155550123"
});