Direct Deposit Switch

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: Direct Deposit Switch

Get started

Run the demo

Clone and run the Direct 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.

Understand the API flow

The demo follows this sequence:

Create a user — Your server calls POST /v1/users/ to create a Truv user.
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.
Initialize Bridge — Your frontend opens Truv Bridge with the bridge_token. The customer connects their payroll provider and confirms the deposit switch.
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.
Retrieve the report — Fetch the deposit switch confirmation with GET /v1/users//deposit_switch/report/.

Review the code

Each step maps to a specific file in the demo. Use these as reference when building your integration.

Step	Demo file	API reference
User creation	`server/routes/bridge.js`	POST /v1/users/
Bridge token creation	`server/routes/bridge.js`	POST /v1/users//tokens/
Bridge initialization	`src/demos/DepositSwitch.jsx`	Bridge SDK
Webhook handling	`server/webhooks.js`	Webhooks
Report retrieval	`server/routes/user-reports.js`	DDS 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.

Field	Required	Description
`account_number`	Yes	Your bank account number (4-20 digits)
`routing_number`	Yes	Your bank routing number (8-12 digits)
`bank_name`	Yes	Your bank’s display name
`account_type`	Yes	`checking` or `savings`
`deposit_type`	No	Allocation type: `entire`, `amount`, or `percent`
`deposit_value`	No	Amount 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.

Allocation	`deposit_type`	`deposit_value`	Behavior
Full paycheck	`entire`	Not required	Routes the entire paycheck
Fixed amount	`amount`	Dollar amount (e.g. `"500.00"`)	Routes a specific dollar amount
Percentage	`percent`	Percentage (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

Webhooks

Handle task-status-updated and other webhook events

DDS Report API

Retrieve deposit switch confirmation reports

​Get started

​Configure account details

​Set allocation type

​Full paycheck

​Fixed amount

​Percentage

​Next steps

Bridge Widget Guide

Sandbox Testing

Webhooks

DDS Report API

Get started

Configure account details

Set allocation type

Full paycheck

Fixed amount

Percentage

Next steps