> ## Documentation Index
> Fetch the complete documentation index at: https://docs.truv.com/llms.txt
> Use this file to discover all available pages before exploring further.

# New User

> Direct API integration for Deposit Switch and Paycheck Linked Lending

Bridge Widget flow provides direct control over payroll connections, specifically designed for Deposit Switch and Paycheck Linked Lending use cases.

<Warning>
  **Bridge Widget is only for Deposit Switch and Paycheck Linked Lending.**

  For Income & Employment, Assets, or Employment verification, use [Embedded Orders](/developers/integration/embedded-orders/overview) instead.
</Warning>

***

## When to Use Bridge Widget

```mermaid theme={null}
graph TD
    A[What are you building?] --> B{Use case?}
    B -->|Mortgage / Consumer Credit| C[Use Embedded Orders]
    B -->|Tenant Screening| C
    B -->|Government / Social Services| C
    B -->|Deposit Switch| D[Use Bridge Widget]
    B -->|Paycheck Linked Lending| D
```

| Use Case                | Recommended Method |
| ----------------------- | ------------------ |
| Deposit Switch          | **Bridge Widget**  |
| Paycheck Linked Lending | **Bridge Widget**  |
| Income & Employment     | Embedded Orders    |
| Assets                  | Embedded Orders    |
| Employment              | Embedded Orders    |

***

## Token flow

The Widget-only flow uses a three-token exchange to securely connect users:

```text theme={null}
bridge_token → public_token → access_token
```

| Token          | Created By               | Lifetime    | Purpose                              |
| -------------- | ------------------------ | ----------- | ------------------------------------ |
| `bridge_token` | Your server (via API)    | 6 hours     | Initialize Truv Bridge on the client |
| `public_token` | Truv Bridge (on success) | Short-lived | Temporary token for exchange         |
| `access_token` | Token exchange (via API) | Persistent  | Configure DDS/PLL and retrieve data  |

***

## Implementation

### Step 1: Create a user \[Server-side]

Create a user to associate with this connection.

```bash theme={null}
curl --request POST \
     --url https://prod.truv.com/v1/users/ \
     --header 'X-Access-Client-Id: YOUR_TRUV_CLIENT_ID' \
     --header 'X-Access-Secret: YOUR_TRUV_CLIENT_SECRET' \
     --header 'Content-Type: application/json' \
     --data '{
  "external_user_id": "your-internal-user-id",
  "first_name": "John",
  "last_name": "Doe"
}'
```

Save the `id` from the response to use in the next step.

### Step 2: Create a bridge token \[Server-side]

Create a bridge token with the user ID and your product configuration. Pass the `account` details for the destination bank account.

<Tabs>
  <Tab title="Deposit Switch">
    ```bash theme={null}
    curl --request POST \
         --url https://prod.truv.com/v1/users/USER_ID/tokens/ \
         --header 'X-Access-Client-Id: YOUR_TRUV_CLIENT_ID' \
         --header 'X-Access-Secret: YOUR_TRUV_CLIENT_SECRET' \
         --header 'Content-Type: application/json' \
         --data '{
      "product_type": "deposit_switch",
      "allowed_products": ["deposit_switch"],
      "account": {
        "account_number": "151251215",
        "account_type": "checking",
        "routing_number": "12027471412",
        "bank_name": "AcmeBank"
      }
    }'
    ```
  </Tab>

  <Tab title="Paycheck Linked Lending">
    ```bash theme={null}
    curl --request POST \
         --url https://prod.truv.com/v1/users/USER_ID/tokens/ \
         --header 'X-Access-Client-Id: YOUR_TRUV_CLIENT_ID' \
         --header 'X-Access-Secret: YOUR_TRUV_CLIENT_SECRET' \
         --header 'Content-Type: application/json' \
         --data '{
      "product_type": "pll",
      "account": {
        "action": "create",
        "account_type": "savings",
        "bank_name": "Acme Bank",
        "routing_number": "12345678219",
        "account_number": "16002622100",
        "deposit_type": "amount",
        "deposit_value": "50.00"
      }
    }'
    ```
  </Tab>
</Tabs>

### Step 3: Initialize Bridge Widget \[Client-side]

Pass the `bridge_token` to Truv Bridge. When the user connects successfully, Bridge returns a `public_token` via the `onSuccess` callback.

```html theme={null}
<script src="https://cdn.truv.com/bridge.js"></script>
<script>
  var bridgeToken = ''; // bridge_token from your server

  var bridge = TruvBridge.init({
    bridgeToken: bridgeToken,
    onSuccess: function(publicToken, metadata) {
      console.log('public_token:', publicToken);
      // Send publicToken to your server for exchange
    },
    onEvent: function(type, payload) {
      console.log('Event:', type, payload);
      // Handle events — see Bridge Events for all types
    },
    onClose: function() {
      console.log('Widget closed');
    }
  });

  bridge.open();
</script>
```

See [Bridge Events](/developers/sdks/bridge-events) for all callback events, error codes, and payload shapes.

### Step 4: Exchange token and retrieve data \[Server-side]

Exchange the `public_token` for a persistent `access_token`:

```bash theme={null}
curl --request POST \
     --url https://prod.truv.com/v1/link-access-tokens/ \
     --header 'X-Access-Client-Id: YOUR_TRUV_CLIENT_ID' \
     --header 'X-Access-Secret: YOUR_TRUV_CLIENT_SECRET' \
     --header 'Content-Type: application/json' \
     --data '{
  "public_token": "PUBLIC_TOKEN_FROM_BRIDGE"
}'
```

Store the returned `access_token` securely. Use it to fetch data and manage the connection.

***

## Webhooks

Listen for these server-side [webhook events](/api-reference/webhooks) to track connection status:

* `task-status-updated` with `status: done` — task completed successfully
* `task-status-updated` with error statuses — connection failed (see [Task lifecycle](/api-reference/tasks/lifecycle))

See [Webhooks](/api-reference/webhooks) for the full event reference.

***

## Best practices

* Always wait for `task-status-updated` webhook with `status: done` before treating a connection as complete
* Handle errors with user-friendly messaging
* Store `link_id` and `access_token` for future reference

[View best practices guide →](/developers/best-practices/bridge-token)

***

## Next steps

<CardGroup cols={2}>
  <Card title="Direct Deposit Switch" icon="arrow-right-arrow-left" href="/banking/integration/dds">
    Direct Deposit Switch integration for Retail Banking
  </Card>

  <Card title="Paycheck-Linked Loans" icon="credit-card" href="/credit/integration/pll">
    Complete Paycheck Linked Lending setup guide
  </Card>

  <Card title="Bridge Events" icon="bolt" href="/developers/sdks/bridge-events">
    Client-side event types and error codes
  </Card>

  <Card title="Best Practices" icon="star" href="/developers/best-practices/bridge-token">
    Widget-only implementation guidelines
  </Card>
</CardGroup>