Implementation Guide


To get Truv quickly implemented in your application for a paycheck-linked loan, 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.



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 ( 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 = pll. To Authentication and start Bridge you will need your Client ID and API Secret from Dashboard.

Note, additionally, for Paycheck-Linked Loan, you will need the following data fields included when you create the Bridge token:

  • account_number
  • acount_type
  • routing_number
  • bank_name
  • deposit_type
    • `amount` - fixed amount from the paycheck
  • `deposit_value` (in dollars)
curl --request POST \
     --url \
     --header 'Accept: application/json' \
     --header 'Content-Type: application/json' \
     --header 'X-Access-Client-Id: {{client_id}}' \
     --header 'X-Access-Secret: {{access_key}}' \
     --data '
     "account": {
          "account_number": "16002600",
          "routing_number": "123456789",
          "bank_name": "TD Bank",
          "deposit_type": "amount",
          "deposit_value": "100"
     "user": {
          "id": "12345",
          "first_name": "John",
          "last_name": "Doe",
          "email": "[email protected]",
          "phone": "+14155554193",
          "ssn": "222233333"
     "product_type": "pll"

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=""></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,

3. Testing Credentials

Test your implementation using sample credentials, refer to Testing or see some sample usernames and passwords below.






Full time current employment



User with multi factor authentication



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 Paycheck Linked Loan report. 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": "amount",
    "deposit_value": "50.00"
  "initial_accounts": [
      "account_number": "16001234",
      "routing_number": "55999876"

Refresh or Continuous Access

Continues Access allows to do data refresh on the fixed schedule without a need from the user to re-authenticate. When new or updated data is available Truv will send webhook events to indicate what was updated. It could include changes in bank accounts, direct deposit account allocations, employment status, income, shifts, or statement data.

To enable continues monitoring for your account, please reach out to us


Depending on a payroll system, If a user has multi-factor authentication or OTP (one-time passcode) enabled on their account the session might expire. To resume the data monitoring a user re-authentication may be required.

To initiate data refresh programmatically for the existing Link, you could trigger it from the backend using Data Refresh. For reference, refer to Refresh mode.

To disconnect, you simply need to delete the Link and all associated data for that user is deleted.

Did this page help you?