Skip to main content
Switch a new customer’s paycheck deposit to your bank by embedding Truv Bridge in your application. The customer connects their payroll provider, selects an allocation, and Truv handles the deposit switch automatically.
Integration pattern: Bridge Widget (User + Bridge Token flow) | Products: DDS | Demo: Deposit Switch

​
Get started

1

Run the demo

Clone and run the Deposit Switch demo to see the full direct deposit switch flow working locally.
git clone https://github.com/truvhq/demo-apps.git
cd demo-apps
npm install && npm start
Open http://localhost:5173, select Retail Banking > Deposit Switch, and walk through a switch using sandbox credentials (goodlogin / goodpassword).See full setup instructions for ngrok and environment configuration.
2

Understand the API flow

The demo follows this sequence:
  1. Create a user — Your server calls POST /v1/users/ to create a Truv user.
  2. Create a bridge token — Your server calls POST /v1/users//tokens/ with product_type: "deposit_switch" and an account object containing your bank’s account details and allocation preferences.
  3. Initialize Bridge — Your frontend opens Truv Bridge with the bridge_token. The customer connects their payroll provider and confirms the deposit switch.
  4. Receive webhooks — Truv sends a task-status-updated webhook with status done when the switch completes. Verify the signature using the X-Webhook-Sign header with HMAC-SHA256.
  5. Retrieve the report — Fetch the deposit switch confirmation with GET /v1/users//deposit_switch/report/.
3

Review the code

Each step maps to a specific file in the demo. Use these as reference when building your integration.
StepDemo fileAPI reference
User creationserver/routes/bridge.jsPOST /v1/users/
Bridge token creationserver/routes/bridge.jsPOST /v1/users//tokens/
Bridge initializationsrc/demos/DepositSwitch.jsxBridge SDK
Webhook handlingserver/webhooks.jsWebhook events
Report retrievalserver/routes/user-reports.jsDDS report

​
Configure account details

Pass your bank’s account details in the account object when creating the bridge token. These fields tell Truv where to route the customer’s paycheck.
FieldRequiredDescription
account_numberYesYour bank account number (4-20 digits)
routing_numberYesYour bank routing number (8-12 digits)
bank_nameYesYour bank’s display name
account_typeYeschecking or savings
deposit_typeNoAllocation type: entire, amount, or percent
deposit_valueNoAmount or percentage (required when deposit_type is amount or percent)

​
Set allocation type

Control how much of the customer’s paycheck routes to your bank. Choose one of three allocation types.
Allocationdeposit_typedeposit_valueBehavior
Full paycheckentireNot requiredRoutes the entire paycheck
Fixed amountamountDollar amount (e.g. "500.00")Routes a specific dollar amount
PercentagepercentPercentage (e.g. "50")Routes a percentage of the paycheck

​
Full paycheck

{
  "account_number": "16002600",
  "routing_number": "123456789",
  "bank_name": "Your Bank",
  "account_type": "checking",
  "deposit_type": "entire"
}

​
Fixed amount

{
  "account_number": "16002600",
  "routing_number": "123456789",
  "bank_name": "Your Bank",
  "account_type": "checking",
  "deposit_type": "amount",
  "deposit_value": "500.00"
}

​
Percentage

{
  "account_number": "16002600",
  "routing_number": "123456789",
  "bank_name": "Your Bank",
  "account_type": "checking",
  "deposit_type": "percent",
  "deposit_value": "50"
}

​
Next steps

Bridge Widget Guide

Full implementation guide for the User + Bridge Token flow

Sandbox Testing

Test deposit switching in sandbox

Webhook Events

Handle task-status-updated and other webhook events

DDS Report API

Retrieve deposit switch confirmation reports