Implementation

Follow this step-by-step guide to integrate your deposit switch solution.

Historically, direct deposit switches have required too much coordination—not to mention paperwork—between you, your users, and their employer or payroll providers. It can be so cumbersome that many users never complete the process.

Enable your users to authorize a direct deposit switch instantly. Argyle automates account switching so that there’s no work on your end. For your users, it’s practically as simple. With just a few clicks and without leaving your platform, they can authorize a direct deposit switch or allocate a part of their wages to you.

We suggest integrating Argyle in two phases:

  1. Scoping - determine how you want to use Argyle and how to present the Argyle experience to your users.
  2. Technical implementation (this guide) - a guide to get you up and running.

Step 1: Upload your logo

Implementation logoImplementation logo

You can upload your logo under the Company details tab in your Settings menu via Argyle Console.


Step 2: Set up pay distribution config

To start, set up your pay distribution config. After that, it is necessary to encrypt it (step 3) and plug it into your Argyle Link configuration (step 4).

For direct deposit switching, Argyle suggests the following config:

{
   "bank_account":{
      "bank_name":"Bank Name",
      "routing_number":"111111111",
      "account_number":"2222222222222",
      "account_type":"checking"
   },
   "percent_allocation":{
      "value":"100",      // your user will see this value first
      "min_value":"100"   // your user cannot modify the value below this bound
   },
   "allow_editing":false
}

The values in the percent_allocation object ensure that the user will see a single 100% allocation and will not be able to edit the value.

Typically, we see 100% of a paycheck switched for a neo bank use case. If you would like to direct a smaller percent of a paycheck, you will need to adjust the percent_allocation parameter. Please note that some payroll platforms only support a single allocation and the percent will be automatically adjusted to 100% in this scenario.

📘

The above pay distribution config will only work with employers that support percent allocations. Some employers that only support amount allocations—they will not be shown to users if you use the above config. If you want to surface these employers to your users, you will have to use the amount_allocation parameter. Please refer to the Pay Distribution guide for more information.

Setting allow_editing to false ensures that the user is not able to edit the allocations or add new ones. If you want to let the user deposit less than 100%, use this configuration instead:

{
   "bank_account":{
      "bank_name":"Bank Name",
      "routing_number":"111111111",
      "account_number":"2222222222222",
      "account_type":"checking"
   },
   "percent_allocation":{
      "value":"100"
   },
   "amount_allocation":{
      "value":"200"
   }
}

If you want to customize your configuration further, please refer to the Pay Distributions guide for all configuration parameters and Customizing Argyle Link for all customizable UI elements.


Step 3: Encrypt pay distribution config

The encryption is necessary to ensure your bank account details are never exposed on the front-end. To encrypt your pay distribution config, make a POST request into:

  • https://api-sandbox.argyle.com/v1/pay-distribution-configs/encrypt if testing in the sandbox environment;
  • https://api.argyle.com/v1/pay-distribution-configs/encrypt if working with accounts in the production environment. With your pay distribution config in the payload:
POST https://api-sandbox.argyle.com/v1/pay-distribution-configs/encrypt

{
   "bank_account":{
      "bank_name":"New Bank",
      "routing_number":"084101234",
      "account_number":"9483746361234",
      "account_type":"checking"
   },
   "default_allocation_type":"percent",
   "percent_allocation":{
      "value":"100",
      "min_value":"100"
   },
   "allow_editing":false
}

You see the following response that contains the encrypted version of your config:

{
    "encrypted_config": "CiQAB/5leYUnrNL8BtyixGfDLuwlxh2ag6zivkz6SyOcTwtrN08SyQIAfV+QlUpYcWSIKvrkz4QZvx1XPkLIvoAxzg+Liq39II2XG725ifZlTvsEDCQka2RbOsrUeOU34iZ81mSM50+ccusu8ZfS6leNgE/vul3rCtPyxy3py22rzjExgkg2M4UMh+sIaDGbUtXYK+QYu/QyhzYYNBd1Mbr/Ey4DBF4AOtbGfjMoudk5NUf8gfz+pP3p4ZrE7wYHbp5y3udhKG2+kuoLJm/3xm7rnigTAfwJlmtAlJhgAH1dpjS6iTeKrnHdyYX3Xpb3Fmtm8WRBv++h0AofSxSe3beEye2n1OuN+FyZTnJd2+gsnpwuyJKELE1EYzsQrKELL+Qf9c05UMrwLJemTgx75web1RdZaGufni84pyo5/hH8JP5iQLUY8shfxx9+Gr714YBuA5S3Oaa7WwnEauOI74R81tlQaBOXTXElxAUzTFx3rQ=="
}

Step 4: Configure Link

Users need to connect their employment accounts via Argyle Link to confirm a direct deposit switch. Find an example configuration below to start:

Deposit switch Link configuration

<!DOCTYPE html>
<html>
    <head>
        <meta charset="utf-8" />
    </head>
    <body>
        <script src="https://plugin.argyle.com/argyle.web.v3.js"></script>
        <script type="text/javascript">
      const argyle = Argyle.create({
        linkKey: 'YOUR_LINK_KEY', // insert your Link key here. It can be found in the Argyle Console.
        apiHost: 'https://api-sandbox.argyle.com/v1', // sandbox environment is used in this example. Change to production environment before launching.
        payDistributionItemsOnly: true, //only Link items that support pay distribution changes will be shown to users.
        payDistributionUpdateFlow: true,
          payDistributionConfig: /* your encrypted pay distribution config */ "CiQAB/5leYUnrNL8BtyixGfDLuwlxh2ag6zivkz6SyOcTwtrN08SyQIAfV+QlUpYcWSIKvrkz4QZvx1XPkLIvoAxzg+Liq39II2XG725ifZlTvsEDCQka2RbOsrUeOU34iZ81mSM50+ccusu8ZfS6leNgE/vul3rCtPyxy3py22rzjExgkg2M4UMh+sIaDGbUtXYK+QYu/QyhzYYNBd1Mbr/Ey4DBF4AOtbGfjMoudk5NUf8gfz+pP3p4ZrE7wYHbp5y3udhKG2+kuoLJm/3xm7rnigTAfwJlmtAlJhgAH1dpjS6iTeKrnHdyYX3Xpb3Fmtm8WRBv++h0AofSxSe3beEye2n1OuN+FyZTnJd2+gsnpwuyJKELE1EYzsQrKELL+Qf9c05UMrwLJemTgx75web1RdZaGufni84pyo5/hH8JP5iQLUY8shfxx9+Gr714YBuA5S3Oaa7WwnEauOI74R81tlQaBOXTXElxAUzTFx3rQ==",
          onAccountConnected: ({ accountId, userId, linkItemId }) => {
          console.log('Account connected: ', accountId, ' User ID:', userId, ' Link Item ID:', linkItemId) // save the accountId
        },
        onUserCreated: ({ userId, userToken }) => {
          console.log('User created: ', userId, 'User token:', userToken)
        } // save the userId and userToken
      })
      argyle.open()
    </script>
    </body>
</html>
class ViewController: UIViewController {

 override func viewDidLoad() {
    let PD_CONFIG = "CiQAB/5leYUnrNL8BtyixGfDLuwlxh2ag6zivkz6SyOcTwtrN08SyQIAfV+QlUpYcWSIKvrkz4QZvx1XPkLIvoAxzg+Liq39II2XG725ifZlTvsEDCQka2RbOsrUeOU34iZ81mSM50+ccusu8ZfS6leNgE/vul3rCtPyxy3py22rzjExgkg2M4UMh+sIaDGbUtXYK+QYu/QyhzYYNBd1Mbr/Ey4DBF4AOtbGfjMoudk5NUf8gfz+pP3p4ZrE7wYHbp5y3udhKG2+kuoLJm/3xm7rnigTAfwJlmtAlJhgAH1dpjS6iTeKrnHdyYX3Xpb3Fmtm8WRBv++h0AofSxSe3beEye2n1OuN+FyZTnJd2+gsnpwuyJKELE1EYzsQrKELL+Qf9c05UMrwLJemTgx75web1RdZaGufni84pyo5/hH8JP5iQLUY8shfxx9+Gr714YBuA5S3Oaa7WwnEauOI74R81tlQaBOXTXElxAUzTFx3rQ==" // your encrypted pay distribution config
    _ = Argyle.shared
        .loginWith(
            linkKey: "YOUR_LINK_KEY", // insert your Link key here. It can be found in the Argyle Console.
            apiHost: "https://api-sandbox.argyle.com/v1") // sandbox environment is used in this example. Change to production environment before launching.
        .linkItems([]) // add Link item IDs (e.g. "Starbox") if you want to constrain the Link item list in the search screen.
        .payDistributionUpdateFlow(true)
        .payDistributionConfig(PD_CONFIG) 
        .payDistributionItemsOnly(true) // only Link items that support pay distribution update will be shown to users.
        .resultListener(self)
  }

  @IBAction func argyleNewUser(_ sender: Any) {
    let argyle = Argyle.shared.controller
    argyle.modalPresentationStyle = .fullScreen
    self.present(argyle, animated: true, completion: nil)
  }
}

extension ViewController: ArgyleResultListener {

    func onUserCreated(token: String, userId: String) {
        print("APP: onUserCreated((token: \(token), userId: \(userId))")
        // save user token and userId
    }

    func onAccountConnected(accountId: String, userId: String, linkItemId: String) {
        print("APP: onAccountConnected(accountId: \(accountId), userId: \(userId), linkItemId: \(linkItemId))")
    }
        // rest of callbacks (all callbacks must be implemented)
}
val PD_CONFIG = "CiQAB/5leYUnrNL8BtyixGfDLuwlxh2ag6zivkz6SyOcTwtrN08SyQIAfV+QlUpYcWSIKvrkz4QZvx1XPkLIvoAxzg+Liq39II2XG725ifZlTvsEDCQka2RbOsrUeOU34iZ81mSM50+ccusu8ZfS6leNgE/vul3rCtPyxy3py22rzjExgkg2M4UMh+sIaDGbUtXYK+QYu/QyhzYYNBd1Mbr/Ey4DBF4AOtbGfjMoudk5NUf8gfz+pP3p4ZrE7wYHbp5y3udhKG2+kuoLJm/3xm7rnigTAfwJlmtAlJhgAH1dpjS6iTeKrnHdyYX3Xpb3Fmtm8WRBv++h0AofSxSe3beEye2n1OuN+FyZTnJd2+gsnpwuyJKELE1EYzsQrKELL+Qf9c05UMrwLJemTgx75web1RdZaGufni84pyo5/hH8JP5iQLUY8shfxx9+Gr714YBuA5S3Oaa7WwnEauOI74R81tlQaBOXTXElxAUzTFx3rQ==" // your encrypted pay distribution config

val config = ArgyleConfig.Builder()
    .loginWith(
        "YOUR_LINK_KEY", // insert your Link key here. It can be found in the Argyle Console.
        "https://api-sandbox.argyle.com/v1", // sandbox environment is used in this example. Change to production environment before launching.
        "")
    .linkItems(arrayOf("")) // add Link item IDs (e.g. "Starbox") if you want to constrain the Link item list in the search screen.
    .payDistributionConfig(PD_CONFIG)
    .payDistributionItemsOnly(true)  // only Link items that support pay distribution update will be shown to users.
    .payDistributionUpdateFlow(true)
    .setCallbackListener(object : Argyle.ArgyleResultListener {

        override fun onUserCreated(userToken: String, userId: String) {
            // save userToken and userId 
            Log.d("Result", "onUserCreated:  userId: $userId, userToken: $userToken")
        }

        override fun onAccountConnected(accountId: String, userId: String, linkItemId: String) {
            Log.d("Result", "onAccountConnected: accountId: $accountId, userId: $userId, linkItemId: $linkItemId")
        }
        // more callbacks available
    })
    .build()

Argyle.instance.init(config)
Argyle.instance.startSDK(this)
import ArgyleSdk from '@argyleio/argyle-plugin-react-native'

const PD_CONFIG = 'CiQAB/5leYUnrNL8BtyixGfDLuwlxh2ag6zivkz6SyOcTwtrN08SyQIAfV+QlUpYcWSIKvrkz4QZvx1XPkLIvoAxzg+Liq39II2XG725ifZlTvsEDCQka2RbOsrUeOU34iZ81mSM50+ccusu8ZfS6leNgE/vul3rCtPyxy3py22rzjExgkg2M4UMh+sIaDGbUtXYK+QYu/QyhzYYNBd1Mbr/Ey4DBF4AOtbGfjMoudk5NUf8gfz+pP3p4ZrE7wYHbp5y3udhKG2+kuoLJm/3xm7rnigTAfwJlmtAlJhgAH1dpjS6iTeKrnHdyYX3Xpb3Fmtm8WRBv++h0AofSxSe3beEye2n1OuN+FyZTnJd2+gsnpwuyJKELE1EYzsQrKELL+Qf9c05UMrwLJemTgx75web1RdZaGufni84pyo5/hH8JP5iQLUY8shfxx9+Gr714YBuA5S3Oaa7WwnEauOI74R81tlQaBOXTXElxAUzTFx3rQ==' // your encrypted pay distribution config

// Configure the SDK before hand, once. only call ArgyleSdk.start() when the UI is needed
ArgyleSdk.loginWith("YOUR_LINK_KEY", "https://api-sandbox.argyle.com/v1", "")
ArgyleSdk.payDistributionConfig(PD_CONFIG)
ArgyleSdk.payDistributionUpdateFlow(true)
ArgyleSdk.payDistributionItemsOnly(true)  // only Link items that support pay distribution update will be shown to users.

ArgyleSdk.onUserCreated(res => console.log("onUserCreated", res)) // save userToken and userId 
ArgyleSdk.onAccountConnected(res => console.log("onAccountConnected", res))
// more callbacks available

ArgyleSdk.linkItems([])  // add Link item IDs (e.g. "Starbox") if you want to constrain the Link item list in the search screen.

// Launch the SDK
ArgyleSdk.start()

Notice the apiHost configuration parameter in the example code pointing to https://api-sandbox.argyle.com/v1. This ensures that the plugin starts in a Sandbox environment where you can use the Sandbox credentials below to test Argyle Link.

Save these three values to be used later:

  • accountId- the onAccountConnectedcallback passes the accountId when an employment account is successfully connected.
  • userId- the onUserCreated callback passes the userId when a user is created. The userId connects all accountIds in the case where a user has more than one employer (e.g. two part-time jobs).
  • userToken - the onUserCreated callback passes the userToken when a user is created. A userToken is necessary to ensure that one user does not create multiple user instances. You need it later to ensure user's permissions are scoped to the specified user's data. This allows users to add new accounts or revoke access to their existing accounts.

User tokens

User tokens are temporary access keys that allow you to start Argyle Link for an already existing user.

They are JWT tokens that contain an expiry date you can use to determine if it is necessary to create a new user token. Newly issued tokens expire in 30 days. You can always decode the token to discover the exact expiration date (check exp field).

Suggested flow for user token usage:

  1. When a new user is created, save the userId and userToken.

  2. When the same user is returning to Link, check if userToken has not expired and is still valid.

  3. If userToken is still valid, provide it to Link in the config.

  4. If userToken has expired:

    • Create a new userToken by calling the /user-tokens endpoint in the Argyle API to generate a new userToken.

    • Provide it to Link in the config. Make sure that you request user tokens on your server-side and your client_id and client_secret are never exposed on the front-end.

Link initialization for a returning user

<!DOCTYPE html>
<html>
  <head>
    <meta charset="utf-8" />
  </head>
  <body>
    <script src="https://plugin.argyle.com/argyle.web.v3.js"></script>
    <script type="text/javascript">
      const argyle = Argyle.create({
        linkKey: 'YOUR_LINK_KEY', // insert your Link key here. It can be found in the Argyle Console.
        apiHost: 'https://api-sandbox.argyle.com/v1', // sandbox environment is used in this example. Change to production environment before launching.
        userToken: 'USER_TOKEN', // insert the old or new user token here
        linkItems: [] // add Link item IDs (e.g. ‘Starbox’) if you want to constrain the Link item list in the search screen.
      })
      argyle.open()
    </script>
  </body>
</html>
_ = Argyle.shared
    .loginWith(
        linkKey: "YOUR_LINK_KEY", // insert your Link key here. It can be found in the Argyle Console.
        apiHost: "https://api-sandbox.argyle.com/v1") // sandbox environment is used in this example. Change to production environment before launching.
    .linkItems([]) // add Link item IDs (e.g. "Starbox") if you want to constrain the Link item list in the search screen.
    .resultListener(self)

let argyle = Argyle.shared.updateToken("USER_TOKEN").controller // insert the old or new user token here
argyle.modalPresentationStyle = .fullScreen
self.present(argyle, animated: true, completion: nil)
val config = ArgyleConfig.Builder()
  .loginWith(
        "YOUR_LINK_KEY", // insert your Link key here. It can be found in the Argyle Console.
        "https://api-sandbox.argyle.com/v1", // sandbox environment is used in this example. Change to production environment before launching.
        "USER_TOKEN") // insert the old or new user token here
    .linkItems(arrayOf()) // add Link item IDs (e.g. "Starbox") if you want to constrain the Link item list in the search screen.
    .setCallbackListener(object : Argyle.ArgyleResultListener {

        override fun onUserCreated(userToken: String, userId: String) {
            // save userId and userToken
            Log.d("Result", "onUserCreated:  userId: $userId, userToken: $userToken")
        }
    })
    .build()

Argyle.instance.init(config)
Argyle.instance.startSDK(this)
import ArgyleSdk from '@argyleio/argyle-plugin-react-native'

ArgyleSdk.loginWith(
        "YOUR_LINK_KEY", // insert your Link key here. It can be found in the Argyle Console.
        "https://api-sandbox.argyle.com/v1", // sandbox environment is used in this example. Change to production environment before launching.
        "USER_TOKEN") // insert the old or new user token here
ArgyleSdk.linkItems([]) // add Link item IDs (e.g. "Starbox") if you want to constrain the Link item list in the search screen.

ArgyleSdk.start()

Step 5: Set up webhooks

To receive regular updates on a user's accounts and pay distribution status, subscribe to webhooks.

Webhooks send notifications to your system every time something occurs, for example, an account is connected, removed, or updated. Read the blog post on Optimizing Workflows with Continuous Data and Webhooks to learn how Argyle clients use webhooks.

To monitor new and existing accounts, Argyle recommends subscribing to the following webhooks:

  • accounts.added - sends a notification upon a user submitting their login credentials in Link.
  • accounts.connected - sends a notification if the submitted credentials are correct and the connection is successful.
  • accounts.failed - sends a notification if a problem occurs and the connection is unsuccessful. Additional information about the problem is provided in the error_code and error_message fields of the webhook payload.
  • accounts.removed - sends a notification when an account is removed (either by you or the user via Argyle Link).
  • accounts.pay_distribution_updated - sends a notification for each successfully updated allocation that you specify in your pay distribution configuration.
  • accounts.pay_distribution_failed - sends a notification if a problem occurs and the pay distribution is not updated successfully. Additional information about the problem is provided in the error_code and error_message fields of the webhook payload.

📘

Consult the Webhooks reference for a complete list of available webhooks.


Step 6: Connect test accounts and update direct deposit

Connect test account and update direct depositConnect test account and update direct deposit

To test the workflow, you will need to initialize Link with the configuration discussed in Step 4.

Within the Sandbox environment, Argyle provides two slightly different data sets:

  • Rideshare/Delivery — if you select a gig company like Uber or Doordash, the data has more activity information (duration, distance, etc).
  • General — if you select any other company or payroll platform, the data reflects traditional employment records.

When running in a Sandbox environment, you can connect work accounts with the provided sandbox credentials only:

BobSarahJoe
Email[email protected][email protected][email protected]
Usernametest_1test_2test_3
Passwordpassgoodpassgoodpassgood
Verification code808180828083
Phone number(800) 900-0001(800) 900-0002(800) 900-0003
Driver's licenseD1230001D1230002D1230003

Make sure to select the appropriate credentials item. For example, a company called Walmart requires username and password, while Uber requires email and password.

If you are subscribed to webhooks as recommended in Step 5, they fire upon successfully connecting an account and updating the pay distribution.


Step 7: Going live and scaling

When you are happy with your implementation and have run multiple tests in the sandbox environment, you switch over to the production environment.

Change the apiHost

First of all, you should change the apiHost in your Link configuration from:

https://api-sandbox.argyle.com/v1

to

https://api.argyle.com/v1

The same logic applies to any API requests that you have previously used, so

GET https://api-sandbox.argyle.com/v1/employments/<accountId>

becomes

GET https://api.argyle.com/v1/employments/<accountId>

Change the linkKey

The linkKey can be found in the API keys section of the Console in the Link key row. Use the production Link key when moving to the production environment.

Start slow

Many of our clients find it useful to connect a personal account first and run a few experiments in the production environment. If Argyle does not support your employer at the moment, you can create an account with a freelance platform like Upwork and connect that account.

Launch and scale

After testing with your personal accounts, you can test with your real users. Argyle recommends starting with a small subset of your users to make sure that everything is working as expected. From there on, roll out gradually to your full user base.


Did this page help you?