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.

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"
    }
  ]