Implementation Guide
Overview
To get Truv quickly implemented in your application for switching direct deposit accounts, we recommend following the step-by-step guide below. A diagram and outline is provided with step-by-step implementation as well.
Sequence Diagram
Below you can see an overview of tokens and data exchange between your application, Truv Bridge, your server/backend, and Truv.
1. Request a bridge_token token from your backend
2. On your backend server request bridge token from the Truv's API
3. Initialize Truv Bridge in your application by passing the bridge_token to TruvBridge.init
4. A user successfully connects their account and a public_token is generated. Bridge hands off the public_token client-side via the onSuccess callback.
5. Webhook events start to be delivered once connection status changes.
6. Exchange a temporary public_token for a permanent access_token.
7. Make an API request to Truv to get the data.


Authentication
Requests to Truv APIs must use HTTPS with TLS 1.2v encryption or higher.
All API requests require the X-Access-Client-Id
and X-Access-Secret
headers which should contain your Client ID and Access key, respectively. You can find these values in your Dashboard.
Because the values described above may grant access to some or all of your data, you must keep them secret and safe. Do not share them with others in public areas, use them in client-side code or the front end of your application, or otherwise use them in a way that may compromise their security.
Additionally, every API request will use the same base url (prod.truv.com) and key, but the prefix for the access key will need to be updated for the environment in use (sandbox, dev, prod).
1. Request a bridge token
Create a Bridge Token including product_type = deposit_switch
. To Authentication and start Bridge you will need your Client ID and API Secret from Dashboard.
Note, additionally, for Direct Deposit Switch, you will need the following data fields included when you create the Bridge token:
- account_number
- acount_type
- routing_number
- bank_name
curl --request POST \
--url https://prod.truv.com/v1/bridge-tokens/ \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'X-Access-Client-Id: {{client_id}}' \
--header 'X-Access-Secret: {{access_key}}' \
--data '
{
"tracking_info": "any data for tracking current user",
"client_name": "Truv Demo",
"color_primary": "#000000",
"product_type": "deposit_switch"
],
"company_mapping_id": "99dd17074ac94aa9ace2621d657c7610",
"provider_id": "adp",
"access_token": "99dd17074ac94aa9ace2621d657c7610",
"account": {
"account_number": "16002600",
"account_type": "checking",
"routing_number": "123456789",
"bank_name": "TD Bank"
},
"user": {
"id": "12345",
"first_name": "John",
"last_name": "Doe",
"email": "[email protected]",
"phone": "+14155554193",
"ssn": "222233333"
}
}
'
2. Initiate Truv Bridge
Using that Bridge Token, initiate Truv Bridge into your UI, usually by passing the bridge token to TruvBridge.init.
<script src="https://cdn.truv.com/bridge.js"></script>
<script>
// Step 2 - Call your back end to retrieve a bridge_token from truv
const bridgeToken = <%= Value returned by API call to acquire bridge_token %>
// Step 3 - Initialize Bridge
const bridge = TruvBridge.init({
bridgeToken: bridgeToken.bridge_token,
})
</script>
3. Testing Credentials
Test your implementation using sample credentials, refer to Testing or see some sample usernames and passwords below.
Username | Password | Description |
---|---|---|
goodlogin | goodpassword | Happy flow |
goodlogin | mfa | User with multi factor authentication |
error.user | login_error | Incorrect login or password |
4. Token exchange
Once a user successfully connects their account, a public_token is generated. Bridge will hand off that public_token client-side via the onSuccess callback once a user has successfully created a Link. Note: The public_token
will expire after 6 hours.
You will exchange the temporary public_token for a permanent access_token via the Exchange Tokens endpoint. The public_token
becomes invalidated once it has been exchanged for an access_token
.
{
"access_token": "48427a36d43c4d5aa6324bc06c692456",
"link_id": "24d7e80942ce4ad58a93f70ce4115f5c"
}
5. Webhooks
You have the option to receive Webhooks to your server to monitor Task status and get notified when the status of a Task changes. Use link_id or task_id to match the webhook events with Link connections.
{
"webhook_id": "609a82aab21e4d9ba2569f35e9e8f26a",
"event_type": "task-status-updated",
"updated_at": "2021-04-26T13:02:20.369267+00:00",
"task_id": "67f2924530564282bbaf6d27655e94a4",
"link_id": "64f8e374949c4b769706028022626bf1",
"product": "income",
"tracking_info": "27266f35-bb54-44c3-8905-070641a0c0aa",
"status": "login"
}
6. Retrieve the data
Using the permanent access_token
, you can generate a Direct Depositreport. If Income and Employment is needed, please refer to Implementation Guide.
{
"id": "24d7e80942ce4ad58a93f70ce4115f5c",
"status": "new",
"finished_at": "2021-04-06T11:30:00Z",
"completed_at": "2021-04-06 11:30:00+00:00",
"access_token": "48427a36d43c4d5aa6324bc06c692456",
"tracking_info": "user123456",
"deposit_details": {
"account_number": "16002600",
"account_type": "checking",
"routing_number": "123456789",
"bank_name": "TD Bank",
"deposit_type": "percent",
"deposit_value": "50.00"
},
"initial_accounts": [
{
"account_number": "16001234",
"routing_number": "55999876"
}
]
Updated about 1 month ago