New User

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

Bridge Widget is only for Deposit Switch and Paycheck Linked Lending.For Income & Employment, Assets, or Employment verification, use Embedded Orders instead.

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:

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.

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.

Deposit Switch
Paycheck Linked Lending

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"
  }
}'

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"
  }
}'

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

<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 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:

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 to track connection status:

task-status-updated with status: done — task completed successfully
task-status-updated with error statuses — connection failed (see Task lifecycle)

See 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 →

Next steps

Direct Deposit Switch

Direct Deposit Switch integration for Retail Banking

Paycheck-Linked Loans

Complete Paycheck Linked Lending setup guide

Bridge Events

Client-side event types and error codes

Best Practices

Widget-only implementation guidelines

When to Use Bridge Widget

Token flow

Implementation

Step 1: Create a user [Server-side]

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

Step 3: Initialize Bridge Widget [Client-side]

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

Webhooks

Best practices

Next steps

Direct Deposit Switch

Paycheck-Linked Loans

Bridge Events

Best Practices

​When to Use Bridge Widget

​Token flow

​Implementation

​Step 1: Create a user [Server-side]

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

​Step 3: Initialize Bridge Widget [Client-side]

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

​Webhooks

​Best practices

​Next steps

Direct Deposit Switch

Paycheck-Linked Loans

Bridge Events

Best Practices

When to Use Bridge Widget

Token flow

Implementation

Step 1: Create a user [Server-side]

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

Step 3: Initialize Bridge Widget [Client-side]

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

Webhooks

Best practices

Next steps