Plaid Integration

Overview

Integrating with Plaid allows partners to securely link consumer bank accounts to enable payments and account verification.
This flow relies on a hosted link provided by Upward uses message passing and deep links to manage authentication and completion.


Integration Steps

Important note
When you use a Hosted Link in a native mobile app, you will open the URL inside of an “out of process” webview, such as an ASWebAuthenticationSession in iOS, or an Android Custom Tab. These sessions appear as part of your application, making the process feel more seamless than opening up the URL in a separate browser application.

  1. Request a consumer scoped token

    • Partners can get the token using auth api. Token scope required to perform this action is ui:client-onboarding api:purchase:write api:accounts:read api:accounts:write
  2. Request a hosted link

  3. Listen for Plaid token message

    • Upward will send an iframe message to the parent frame with the event:
    // plaid.token
    {
    "hostedLinkUrl": "https://secure.plaid.com/hl/ls948q0pr159oo9qq0ns8p951n5o83686q"
    }
  4. Use the hosted link to initiate Plaid

    • After receiving the hosted link, you’ll need to open a secure Plaid flow.
  5. Open the Plaid browser

    • Launch a secure.plaid.com browser session where the consumer can complete Plaid authentication.
  6. Handle completion with custom URL schema

    • Once Plaid completes, Upward will send out a deep link using the schema:
      upwardli://plaid-link
  7. Close the Plaid browser on redirect

    • Your app must listen for the plaid completion_redirect_uri in order to close the Plaid browser session.

Example: Plaid Completion / Close Browser

Here is the code example:

1// Handle deep links
2 useEffect(() => {
3 const handleUrl = ({ url }: { url: string }) => {
4 if (url.includes("plaid-link")) {
5 WebBrowser.maybeCompleteAuthSession();
6 }
7 };
8 const subscription = Linking.addEventListener("url", handleUrl);
9 return () => {
10 subscription.remove();
11 };
12 }, []);