Widget-only Best Practices

Follow these best practices for Deposit Switch (DDS) and Paycheck Linked Lending (PLL) integrations using the Widget-only flow.

Wait for webhooks before proceeding

Always wait for the task-status-updated webhook with status: done before treating a connection as complete. Do not rely solely on the client-side onSuccess callback. The task may still be processing server-side.

# When you receive a task-status-updated webhook with status: done,
# retrieve the link details
curl --request GET \
     --url https://prod.truv.com/v1/links/{link_id}/ \
     --header 'X-Access-Client-Id: YOUR_TRUV_CLIENT_ID' \
     --header 'X-Access-Secret: YOUR_TRUV_CLIENT_SECRET'

Validate account details upfront

Provide complete and accurate bank account information when creating the bridge token. Missing or incorrect fields cause configuration failures. Deposit Switch: route the user’s entire paycheck or a fixed amount:

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",
  "account": {
    "account_number": "16002600",
    "routing_number": "123456789",
    "bank_name": "TD Bank",
    "account_type": "checking",
    "deposit_type": "entire"
  }
}'

Paycheck Linked Lending: deduct a fixed amount per paycheck:

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": {
    "account_number": "16002600",
    "routing_number": "123456789",
    "bank_name": "TD Bank",
    "account_type": "checking",
    "deposit_type": "amount",
    "deposit_value": "200.00"
  }
}'

Deposit type options

`deposit_type`	Description
`entire`	Route the entire paycheck
`amount`	Route a fixed dollar amount (set `deposit_value`)
`percent`	Route a percentage of the paycheck (set `deposit_value`)

Handle errors from webhooks

Monitor task-status-updated webhooks for error statuses. These indicate the connection or configuration failed.

Webhook status	Cause	Resolution
`login_error`	Incorrect credentials	Prompt the user to re-authenticate via Bridge Update Mode
`mfa_error`	MFA challenge failed	Prompt the user to try again
`config_error`	Provider doesn’t support the requested operation	Fall back to manual instructions or try a different provider
`account_locked`	Too many failed attempts at the provider	Ask the user to unlock their account with the provider

See Task lifecycle for all status transitions.

Handle client-side errors

Listen for ERROR events in the Bridge onEvent callback. The error object uses error_code, not a generic code field.

onEvent: function(type, payload) {
  if (type === 'ERROR') {
    switch (payload.error.error_code) {
      case 'LOGIN_ERROR':
        // User entered wrong credentials — Bridge handles retry UI
        break;
      case 'UNAVAILABLE':
        showMessage('This provider is temporarily unavailable. Try again later.');
        break;
      case 'LINK_EXISTS':
        showMessage('This account is already connected.');
        break;
    }
  }
}

See Bridge Events for all error codes and their meanings.

Use deeplinking when you know the employer

If you know the user’s employer or payroll provider, pass it when creating the bridge token to skip search screens and improve conversion.

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",
  "company_mapping_id": "48427a36d43c4d5aa6324bc06c692456",
  "account": {
    "account_number": "16002600",
    "routing_number": "123456789",
    "bank_name": "TD Bank",
    "account_type": "checking",
    "deposit_type": "entire"
  }
}'

See Deeplinking for the full guide.

Check DDS/PLL support before connecting

Use the company search endpoint to check if a provider supports DDS or PLL before routing the user through the flow. This avoids dead-end experiences where the user connects but the provider doesn’t support the desired product.

curl --request GET \
     --url 'https://prod.truv.com/v1/company-mappings-search/?query=Facebook' \
     --header 'X-Access-Client-Id: YOUR_TRUV_CLIENT_ID' \
     --header 'X-Access-Secret: YOUR_TRUV_CLIENT_SECRET'

Check the response for DDS/PLL availability before initiating the bridge token.

Leverage VOIE-PLL flow

For combined income verification and paycheck linked lending, complete the VOIE flow first, then check if the connected provider supports DDS/PLL. After VOIE completes, fetch the link details:

curl --request GET \
     --url https://prod.truv.com/v1/links/{link_id}/ \
     --header 'X-Access-Client-Id: YOUR_TRUV_CLIENT_ID' \
     --header 'X-Access-Secret: YOUR_TRUV_CLIENT_SECRET'

Check the is_dds_available flag in the response. If true, the user’s payroll provider supports DDS/PLL and you can offer it as a follow-up step without requiring the user to reconnect.

Understand the token flow

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

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

Store and protect tokens

access_token is persistent and grants access to the user’s data. Store it encrypted on your server.
bridge_token is short-lived (6 hours) and safe to pass to the client. Generate a new one if the user hasn’t started within that window.
public_token is single-use. Exchange it immediately for an access_token via POST /v1/link-access-tokens/ and discard it.

Never expose access_token or API credentials in client-side code.

Verify webhook signatures

Always verify the X-WEBHOOK-SIGN header on incoming webhooks to confirm they are from Truv. Use the raw request body. Never use parsed JSON. See Webhook Security for verification examples.

Next steps

Widget-only Integration

Implementation guide for Widget-only flow

Returning User

Reconnect or update an existing link

Bridge Events

Client-side event types and error codes

Task Lifecycle

Server-side connection statuses

​Wait for webhooks before proceeding

​Validate account details upfront

​Deposit type options

​Handle errors from webhooks

​Handle client-side errors

​Use deeplinking when you know the employer

​Check DDS/PLL support before connecting

​Leverage VOIE-PLL flow

​Understand the token flow

​Store and protect tokens

​Verify webhook signatures

​Next steps