Skip to main content
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.

​
When to Use Bridge Widget

Use CaseRecommended Method
Deposit SwitchBridge Widget
Paycheck Linked LendingBridge Widget
Income & EmploymentEmbedded Orders
AssetsEmbedded Orders
EmploymentEmbedded Orders

​
Token flow

The Widget-only flow uses a three-token exchange to securely connect users: 
bridge_token → public_token → access_token
TokenCreated ByLifetimePurpose
bridge_tokenYour server (via API)6 hoursInitialize Truv Bridge on the client
public_tokenTruv Bridge (on success)Short-livedTemporary token for exchange
access_tokenToken exchange (via API)PersistentConfigure 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. 
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"
  }
}'

​
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. 
<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 Webhook Events 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