> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://developers.upwardli.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developers.upwardli.com/_mcp/server.

# Post Onboarding Plaid Integrating

# 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](/api-access/api-reference/auth/create-token-exchange).
     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**
   * Open the provided link in your app or browser.
   * URL: [https://component-embedded-sandbox.upwardli.com/en/onboarding/transfer/?access_token=\{consumer_scope_token}](https://component-embedded-sandbox.upwardli.com/en/onboarding/transfer/?access_token=\{consumer_scope_token})

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:

```tsx
// Handle deep links
  useEffect(() => {
    const handleUrl = ({ url }: { url: string }) => {
      if (url.includes("plaid-link")) {
        WebBrowser.maybeCompleteAuthSession();
      }
    };
    const subscription = Linking.addEventListener("url", handleUrl);
    return () => {
      subscription.remove();
    };
  }, []);
```

---

## Sandbox Testing: Failed Verification

After an account is linked, Upward runs a Plaid identity match to confirm the account belongs to the consumer. A mismatch deactivates the account, emails the consumer, and sends the [`Consumer.BankAccount.VerificationFailed`](/concepts/webhooks/event-catalog#bank-account-management-webhooks) webhook.

In sandbox this check passes automatically. To test the failure path, link an account for a consumer whose `first_name` is `Alexander` and `last_name` is `Upward` — the identity match will fail for that consumer. Any other name passes, and the comparison is not case-sensitive.