SolutionsGuidesReferences

Implementation

Follow this step-by-step guide to integrate your paycheck-linked lending solution.

Suggest Edits

📘

This guide follows the recommended user flow discussed in the scoping phase and outlined here:

alt namealt name

Invite borrowers to allocate part of their monthly paycheck to pay down your loan while lowering your default risk at the same time.

We typically see lenders implementing this solution in a two-step flow:

  1. VOIE - verify an applicant's income and employment.
  2. Paycheck linking - after making a loan decision and having the user accept loan terms, add a regular pay allocation.

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 started and running.

VOIE

Step 1: Upload your logo

undefinedundefined

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

Step 2: Set up pay distribution config

  1. Set up your pay distribution config.
  2. Encrypt it.
  3. Plug it into your Argyle Link configuration.

For paycheck-linked lending, Argyle suggests the following config:

{
   "bank_account":{
      "bank_name":"Bank Name",
      "routing_number":"111111111",
      "account_number":"2222222222222",
      "account_type":"checking"
   },
   "amount_allocation":{
      "value":"32.57",
      "min_value":"32.57",
      "max_value": "32.57"
   },
   "allow_editing":false
}

The values in the amount_allocation object ensure that the users see a single $32.57 allocation and are not able to edit the value. $32.57 is just a placeholder amount here — insert the monthly installment amount based on the loan terms of your users.

📘

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

Setting allow_editing to false ensures that the users are not able to edit the allocations or add new ones. This parameter removes the Edit button:

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

Step 3: Encrypt pay distribution config

The encryption is necessary to ensure that 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":"Bank Name",
      "routing_number":"111111111",
      "account_number":"2222222222222",
      "account_type":"checking"
   },
   "amount_allocation":{
      "value":"32.57",
      "min_value":"32.57",
      "max_value": "32.57"
   },
   "allow_editing":false
}

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

{
    "encrypted_config": "CiQAB/5leR8apwI6icBQ6w7TsNOYoYNpAUBP4/fpP48Pij6Z+OYSvQIAfV+QlVQKWPoQPVeMf1wqovnIZprUQrmn/3TTAw3LH3MXphOd/610Hy36Tgv0oig9Q/xMxLMQWGThV9TaXBWw0ucowHjETRaQVynM78W/IQ5eVn+Xn7OqL5Imz36XbzNd+O1Xtor+ZE5hhXzH+CR0uo1bq5dsxCks9p8z5PLZIXgZCJr4v9ximsUAbT1WFiclPSai4MjL3zkMto1Ss0teSYUBKdgBWn/mgAGsV/As6tRVKT3Hyhhy7LWGyvySmTxe8ALAVv21nx+R76i+ddVoxrmgVn0slTrVBz5P4w/9pSD/6fH5HnKQc7g44qJtnORdqujbcdSaK1H5RgqTLld0DUX+ujrxHZE+FP1mo0Ziq80H5HlGgjsjA+JWEif/gItT+Ada8ckS2/IOMJPE8vbK2jQYlCj+mlj2uQF5yg=="
}

This encrypted pay distribution config is part of the Link config described in the next step.

Step 4: Configure Link

Users need to connect their employment accounts via Argyle Link to connect their payroll accounts. Below is an example configuration to start:

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: false, // this step is to connect account for VOIE. Set this to true when returning a user to confirm pay allocation
          payDistributionConfig: /* your encrypted pay distribution config */ "CiQAB/5leR8apwI6icBQ6w7TsNOYoYNpAUBP4/fpP48Pij6Z+OYSvQIAfV+QlVQKWPoQPVeMf1wqovnIZprUQrmn/3TTAw3LH3MXphOd/610Hy36Tgv0oig9Q/xMxLMQWGThV9TaXBWw0ucowHjETRaQVynM78W/IQ5eVn+Xn7OqL5Imz36XbzNd+O1Xtor+ZE5hhXzH+CR0uo1bq5dsxCks9p8z5PLZIXgZCJr4v9ximsUAbT1WFiclPSai4MjL3zkMto1Ss0teSYUBKdgBWn/mgAGsV/As6tRVKT3Hyhhy7LWGyvySmTxe8ALAVv21nx+R76i+ddVoxrmgVn0slTrVBz5P4w/9pSD/6fH5HnKQc7g44qJtnORdqujbcdSaK1H5RgqTLld0DUX+ujrxHZE+FP1mo0Ziq80H5HlGgjsjA+JWEif/gItT+Ada8ckS2/IOMJPE8vbK2jQYlCj+mlj2uQF5yg==",
          onAccountConnected: ({ accountId, userId, linkItemId }) => {
          console.log('Account connected: ', accountId, ' User ID:', userId, ' Link Item ID:', linkItemId) // save the accountId and linkItemId
        }, // save the accountId and linkItemId
        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/5leR8apwI6icBQ6w7TsNOYoYNpAUBP4/fpP48Pij6Z+OYSvQIAfV+QlVQKWPoQPVeMf1wqovnIZprUQrmn/3TTAw3LH3MXphOd/610Hy36Tgv0oig9Q/xMxLMQWGThV9TaXBWw0ucowHjETRaQVynM78W/IQ5eVn+Xn7OqL5Imz36XbzNd+O1Xtor+ZE5hhXzH+CR0uo1bq5dsxCks9p8z5PLZIXgZCJr4v9ximsUAbT1WFiclPSai4MjL3zkMto1Ss0teSYUBKdgBWn/mgAGsV/As6tRVKT3Hyhhy7LWGyvySmTxe8ALAVv21nx+R76i+ddVoxrmgVn0slTrVBz5P4w/9pSD/6fH5HnKQc7g44qJtnORdqujbcdSaK1H5RgqTLld0DUX+ujrxHZE+FP1mo0Ziq80H5HlGgjsjA+JWEif/gItT+Ada8ckS2/IOMJPE8vbK2jQYlCj+mlj2uQF5yg==" // 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(false) // this step is to connect account for VOIE. Set this to true when returning a user to confirm pay allocation
        .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))")
        // save accountId and linkItemId
    }
    // rest of callbacks (all callbacks must be implemented)
}

val PD_CONFIG = "CiQAB/5leR8apwI6icBQ6w7TsNOYoYNpAUBP4/fpP48Pij6Z+OYSvQIAfV+QlVQKWPoQPVeMf1wqovnIZprUQrmn/3TTAw3LH3MXphOd/610Hy36Tgv0oig9Q/xMxLMQWGThV9TaXBWw0ucowHjETRaQVynM78W/IQ5eVn+Xn7OqL5Imz36XbzNd+O1Xtor+ZE5hhXzH+CR0uo1bq5dsxCks9p8z5PLZIXgZCJr4v9ximsUAbT1WFiclPSai4MjL3zkMto1Ss0teSYUBKdgBWn/mgAGsV/As6tRVKT3Hyhhy7LWGyvySmTxe8ALAVv21nx+R76i+ddVoxrmgVn0slTrVBz5P4w/9pSD/6fH5HnKQc7g44qJtnORdqujbcdSaK1H5RgqTLld0DUX+ujrxHZE+FP1mo0Ziq80H5HlGgjsjA+JWEif/gItT+Ada8ckS2/IOMJPE8vbK2jQYlCj+mlj2uQF5yg==" // 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(false) // this step is to connect account for VOIE. Set this to true when returning a user to confirm pay allocation
    .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) {
            // save accountId and linkItemId
            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/5leR8apwI6icBQ6w7TsNOYoYNpAUBP4/fpP48Pij6Z+OYSvQIAfV+QlVQKWPoQPVeMf1wqovnIZprUQrmn/3TTAw3LH3MXphOd/610Hy36Tgv0oig9Q/xMxLMQWGThV9TaXBWw0ucowHjETRaQVynM78W/IQ5eVn+Xn7OqL5Imz36XbzNd+O1Xtor+ZE5hhXzH+CR0uo1bq5dsxCks9p8z5PLZIXgZCJr4v9ximsUAbT1WFiclPSai4MjL3zkMto1Ss0teSYUBKdgBWn/mgAGsV/As6tRVKT3Hyhhy7LWGyvySmTxe8ALAVv21nx+R76i+ddVoxrmgVn0slTrVBz5P4w/9pSD/6fH5HnKQc7g44qJtnORdqujbcdSaK1H5RgqTLld0DUX+ujrxHZE+FP1mo0Ziq80H5HlGgjsjA+JWEif/gItT+Ada8ckS2/IOMJPE8vbK2jQYlCj+mlj2uQF5yg==' // 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", // 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.
    "")
ArgyleSdk.payDistributionConfig(PD_CONFIG)
ArgyleSdk.payDistributionUpdateFlow(false) // this step is to connect account for VOIE. Set this to true when returning a user to confirm pay allocation
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)) // save accountId and linkItemId
// 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 four values for later:

  • accountId- the onAccountConnectedcallback passes the accountId when an employment account is successfully connected.
  • linkItemId - the same callback passes linkItemId, which will be required later to deep link a user into the pay allocation confirmation screen.
  • 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 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

The user token is a necessary tool to create a seamless returning user experience and prevent duplicate account connections. User tokens are temporary access keys that allow you to take users to the correct spot within the Argyle flow. Whenever you need a user to return to Argyle Link, you have to utilize user tokens in the Link configuration.

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
      })
      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.
    .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
    .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.start()

Step 5: Connect test accounts

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 the previous step.

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, Walmart requires username and password, while Uber requires email and password.

If you are subscribed to webhooks, they are trigged on successfully connecting an account and updating the pay distribution.

Step 6: Check account sync status

It takes some time for Argyle to retrieve the employment information after the users connect their accounts. The average sync times are based on the length of employment:

data scan timesdata scan times

If you want to have all the employment information before proceeding, query the account object via the Argyle API with your user’s accountId saved previously:

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

// insert your user’s accountId in the request.
// this example uses the sandbox environment. Don't forget to switch to the production environment if you are testing in production.

Here is an example response:

{
  "id": "ac81e2bc-2157-4535-8ca4-fb1f068df1fc",
  "user": "53fe928d-9c6a-460b-b5ac-19d67304d106",
  "employers": [
    "homedepot"
  ],
  "link_item": "homedepot",
  "source": "workday",
  "created_at": "2019-11-27T15:55:56.771322Z",
  "updated_at": "2019-11-29T08:37:42.164522Z",
  "connection": {
    "status": "connected",
    "error_code": null,
    "error_message": null,
    "updated_at": "2019-11-29T08:37:42.112859"
  },
  "pay_distribution": {
    "status": "success",
    "error": null,
    "error_message": null,
    "updated_at": "2019-11-29T08:37:42.164522Z"
  },
  "availability": {
    "profiles": {
      "status": "synced",
      "updated_at": "2019-11-29T08:37:42.164522Z"
    },
    "employments": {
      "status": "synced",
      "updated_at": "2019-11-29T08:37:42.164522Z"
    },
    "reputations": {
      "status": "synced",
      "updated_at": "2019-11-29T08:37:42.164522Z"
    },
    "documents": {
      "status": "synced",
      "updated_at": "2019-11-29T08:37:42.164522Z"
    },
    "vehicles": {
      "status": "synced",
      "updated_at": "2019-11-29T08:37:42.164522Z"
    },
    "pay_allocations": {
      "status": "synced",
      "updated_at": "2019-11-29T08:37:42.164522Z"
    },
    "payouts": {
      "status": "synced",
      "updated_at": "2019-11-29T08:37:42.164522Z",
      "available_count": 3,
      "available_from": "2019-10-30T00:00:00Z",
      "available_to": "2018-11-27T00:00:00Z"
    },
    "activities": {
      "status": "synced",
      "updated_at": "2019-11-29T08:37:42.164522Z",
      "available_count": 146,
      "available_to": "2019-11-29T08:37:42.164522Z",
      "available_from": "2018-12-15T20:40:50.399677Z"

    }
  }
}
  • availability shows the progress of the employment information synchronization.
  • availability.profiles.status, availability.employments.status, and availability.payouts.status should be synced to make sure all the data was retrieved.

It takes some time for Argyle to retrieve the employment information after the users connect their accounts. The average sync times are based on the length of employment:

Step 7: Retrieve employment information

For employment verification, fetch the following fields from the employments endpoint:

  • hire_datetime
  • status
  • job_title

Submit a GET request to the Argyle API:

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

// insert your user's accountId in the request.
// this example uses the sandbox environment. Don't forget to switch to the production environment if you are testing in production.
//

Here is an example response:

{
   "id":"857b4aad-1a55-4200-84f7-311cd3dc3432",
   "account":"021a1749-6973-4e47-a82a-307008ca88cc",
   "employer":"walmart",
   "created_at":"2020-10-27T17:29:08.724441Z",
   "updated_at":"2020-10-27T17:29:08.724520Z",
   "status":"active",
   "type":"part-time",
   "job_title":"cashier",
   "hire_datetime":"2018-10-27T17:29:08.724441Z",
   "termination_datetime":null,
   "termination_reason":null,
   "base_pay":{
      "amount":36400,
      "period":"annual",
      "currency":"USD"
   },
   "pay_cycle":"monthly",
   "platform_ids":{
      "employee_id":"47FJ06ON8",
      "position_id":"INA609028",
      "platform_user_id":"H3WTY0FHMQ24ERDN"
   },
   "metadata":{}
}

For income verification, fetch the following fields from the payouts endpoint:

  • gross_pay
  • net_pay
  • taxes
  • deductions

A payout object represents a single paystub. You will want to retrieve all the payout objects for a relevant timeframe. Submit a GET request to the Argyle API:

GET https://api-sandbox.argyle.com/v1/payouts?account=<accountId>&from_start_date=2020-01-01&to_start_date=2021-01-01

// insert your user's accountId in the request.
// insert relevant dates for the from_start_date and to_start_date parameters.
// this example uses the sandbox environment. Don't forget to switch to the production environment if you are testing in production.

In this example request, the number of payouts (paystubs) is limited to the 20-21’ period.

You could also retrieve the YTD income by using only the from_start_date parameter and setting it to 2021-01-01 or inserting the value programmatically to receive payouts for the last 12 months. Here is an example response of a single payout:

{
   "id":"a6b95412-e43a-4584-be9f-1dc101aa349a",
   "account":"f8bf3e18-09ba-428c-b197-6798f1b2b834",
   "document_id":"97f21592-b6b6-352a-91d7-e221bf0dd6e9",
   "employer":"walmart",
   "status":"completed",
   "type":"direct_deposit",
   "payout_date":"2020-04-22T00:00:00Z",
   "payout_period":{
      "start_date":"2019-12-28T00:00:00Z",
      "end_date":"2020-01-10T00:00:00Z"
   },
   "currency":"USD",
   "gross_pay":"1730.77",
   "reimbursements":"279.87",
   "deductions":"68.68",
   "deduction_list":[
      {
         "amount":"68.68",
         "name":"Health Benefits - Pretax",
         "tax_classification":"pre_tax"
      }
   ],
   "taxes":"224.68",
   "tax_list":[
      {
         "amount":"171.28",
         "name":"Fed Withholdng",
         "type":"federal"
      },
      {
         "amount":"53.40",
         "name":"Fed OASDI/EE",
         "type":"fica"
      }
   ],
   "fees":null,
   "net_pay":"1717.28",
   "bonuses":"0.00",
   "commission":"0.00",
   "overtime":"0.00",
   "hours":"80.00",
   "employer_address":{
      "line1":"4 Jackson St",
      "line2":"Apt C",
      "city":"Norton",
      "state":"MA",
      "postal_code":"27660",
      "country":"US"
   },
   "filing_status":[
      {
         "type":"federal",
         "location":null,
         "status":"single"
      },
      {
         "type":"state",
         "location":"MD",
         "status":"single"
      }
   ],
   "metadata":{
      "hours_breakdown":[
         {
            "hours":"80",
            "amount":"1730.77",
            "description":"Work Hours"
         }
      ]
   }
}

For additional data fields, please refer to the Argyle API reference.

Paycheck linking

📘

Now, you have all the necessary information to make a loan decision. Once the applicant has agreed to the terms, you can link their paycheck.

📘

If you are just using Argyle for paycheck linking, then you need to set up a pay distribution config and encrypt it as described in the previous steps.

Step 8: Initialize Link with the pay distribution config

To start the paycheck-linking process, return the user to Link with the following config:

Pay distribution update flow

<!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 user token
        linkItems: ['LINK_ITEM_ID'] // insert the linkItemId saved previously during the account connection phase
        payDistributionItemsOnly: true, // only Link items that support pay distribution changes will be shown to users.
        payDistributionUpdateFlow: true, // set this to true when returning a user to confirm pay allocation
          payDistributionConfig: /* your encrypted pay distribution config */ "BiQAX5+IRA7qSjrGKS/aLVTlUkfwXbLAQzyI5sq1NiD8KMPr5jgS/wEAYPZorNBq2DdrvSkNOnuWLXl1Ht6QKoSD2rhirmSw+22zKOIVCQPbeWt0LOSraWErTtjWArX42cNBsVEPWnhwqOIW4L0p9SYzzR5RGbSGOfyCkdtM7traQUwt1voEjtrETdX7+V3sMi2Jdss3kZDZ3hrWK/9qi1noLJ9YQ9e9gGLK7+fk/5n/UElAUt7h/UkcJsBsbV+YzHcpmuP3w4SepuNzoKIeycBzUodBLB4KmQD2HFlt+yokkO2KnmBWtguhXdFnfttrpUANeSSRhdy8K1QBexeKcCJu1aRUQ/tBEHq1I88XfZeXqlKmQNx6YE8SMIY/A2wiwczICPloOTU=",
      )
      argyle.open()
    </script>
    </body>
</html>

let PD_CONFIG = "BiQAX5+IRA7qSjrGKS/aLVTlUkfwXbLAQzyI5sq1NiD8KMPr5jgS/wEAYPZorNBq2DdrvSkNOnuWLXl1Ht6QKoSD2rhirmSw+22zKOIVCQPbeWt0LOSraWErTtjWArX42cNBsVEPWnhwqOIW4L0p9SYzzR5RGbSGOfyCkdtM7traQUwt1voEjtrETdX7+V3sMi2Jdss3kZDZ3hrWK/9qi1noLJ9YQ9e9gGLK7+fk/5n/UElAUt7h/UkcJsBsbV+YzHcpmuP3w4SepuNzoKIeycBzUodBLB4KmQD2HFlt+yokkO2KnmBWtguhXdFnfttrpUANeSSRhdy8K1QBexeKcCJu1aRUQ/tBEHq1I88XfZeXqlKmQNx6YE8SMIY/A2wiwczICPloOTU=" // 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(["LINK_ITEM_ID"]) // insert the linkItemId saved previously during the account connection phase
    .payDistributionUpdateFlow(true) // set this to true when returning a user to confirm pay allocation
    .payDistributionConfig(PD_CONFIG) 
    .payDistributionItemsOnly(true) // only Link items that support pay distribution update will be shown to users.
    .resultListener(self)

let argyle = Argyle.shared.updateToken("USER_TOKEN").controller // insert the user token here
argyle.modalPresentationStyle = .fullScreen
self.present(argyle, animated: true, completion: nil)

val PD_CONFIG = "BiQAX5+IRA7qSjrGKS/aLVTlUkfwXbLAQzyI5sq1NiD8KMPr5jgS/wEAYPZorNBq2DdrvSkNOnuWLXl1Ht6QKoSD2rhirmSw+22zKOIVCQPbeWt0LOSraWErTtjWArX42cNBsVEPWnhwqOIW4L0p9SYzzR5RGbSGOfyCkdtM7traQUwt1voEjtrETdX7+V3sMi2Jdss3kZDZ3hrWK/9qi1noLJ9YQ9e9gGLK7+fk/5n/UElAUt7h/UkcJsBsbV+YzHcpmuP3w4SepuNzoKIeycBzUodBLB4KmQD2HFlt+yokkO2KnmBWtguhXdFnfttrpUANeSSRhdy8K1QBexeKcCJu1aRUQ/tBEHq1I88XfZeXqlKmQNx6YE8SMIY/A2wiwczICPloOTU=" // 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.
        "USER_TOKEN") // insert the user token here
    .linkItems(arrayOf("LINK_ITEM_ID")) // insert the linkItemId saved previously during the account connection phase
    .payDistributionConfig(PD_CONFIG)
    .payDistributionItemsOnly(true)  // only Link items that support pay distribution update will be shown to users.
    .payDistributionUpdateFlow(true) // set this to true when returning a user to confirm pay allocation
    .setCallbackListener(object : Argyle.ArgyleResultListener {
        // callbacks
    })
    .build()

Argyle.instance.init(config)
Argyle.instance.startSDK(this)

import ArgyleSdk from '@argyleio/argyle-plugin-react-native'

const PD_CONFIG = 'BiQAX5+IRA7qSjrGKS/aLVTlUkfwXbLAQzyI5sq1NiD8KMPr5jgS/wEAYPZorNBq2DdrvSkNOnuWLXl1Ht6QKoSD2rhirmSw+22zKOIVCQPbeWt0LOSraWErTtjWArX42cNBsVEPWnhwqOIW4L0p9SYzzR5RGbSGOfyCkdtM7traQUwt1voEjtrETdX7+V3sMi2Jdss3kZDZ3hrWK/9qi1noLJ9YQ9e9gGLK7+fk/5n/UElAUt7h/UkcJsBsbV+YzHcpmuP3w4SepuNzoKIeycBzUodBLB4KmQD2HFlt+yokkO2KnmBWtguhXdFnfttrpUANeSSRhdy8K1QBexeKcCJu1aRUQ/tBEHq1I88XfZeXqlKmQNx6YE8SMIY/A2wiwczICPloOTU=' // 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", // 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 user token here
ArgyleSdk.payDistributionConfig(PD_CONFIG)
ArgyleSdk.payDistributionUpdateFlow(true) // set this to true when returning a user to confirm pay allocation
ArgyleSdk.payDistributionItemsOnly(true)  // only Link items that support pay distribution update will be shown to users.

ArgyleSdk.linkItems(["LINK_ITEM_ID"]) // insert the linkItemId saved previously during the account connection phase

// Launch the SDK
ArgyleSdk.start()

This Link config is different from the previous one in a few ways:

  • userToken - pass the previously saved user token so that Link recognized the user.
  • linkItems - you need to pass the previously saved linkItemId to deep link the user into the pay allocation confirmation screen.
  • payDistributionUpdateFlow is set to true.

The Pay distribution confirmation screen shown to the users:

Step 9: Remove the pay allocation

At the end of the loan term, you can remove the previously set up pay allocation via an API call:

  1. Retrieve the pay allocation ID
  2. Remove the pay allocation

Retrieve the pay allocation ID

GET https://argyle.com/v1/pay_allocations?account=<account-id>

You can retrieve the pay allocation ID by making a GET request to the /v1/pay_allocations?account=<account-id> endpoint, where <account-id> is the ID of the user's account. Retrieve the ID of your pay allocation from the response.

Remove the pay allocation

POST https://argyle.com/v1/pay-allocations/<id>/remove

Make a POST request (with no payload) to the /v1/pay-allocations/<id>/remove endpoint, where <id> is the ID of the allocation you want to be removed.

Troubleshooting: expired authentication

On rare occasions, you will receive a 400 Bad Request error when submitting a remove request.

This means that the users payroll platform authentication has expired. Prompt the user to return to Link to re-authenticate by initializing Link with the user token. After the user has logged in again, you can remove the pay allocation as described above.

Step 10: 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 when an account is connected, removed, or updated. Read about how Argyle clients use webhooks here.

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.

To monitor changes to employment records, Argyle recommends subscribing to the following webhooks:

  • employments.updated - sends a notification when some information in the employment changes. You are notified if a user is terminated, their base pay changes, etc.
  • payouts.partially_synced - when subscribing to this webhook, you can specify days_synced to be notified when a particular amount of data is available (e.g. after a month's or year's worth of payouts are available).
  • payouts.added - sends a notification when a new payout is added to a user's account. It helps you to continuously verify if a user is still receiving income.

📘

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

Step 11: Trigger a periodic scan

In the Production environment, new data for connected accounts are constantly generated and delivered to you (e.g. new payouts, activities) during periodic data scans. For testing purposes, you can trigger a periodic scan yourself to get new data for an already connected account. Please use the following endpoint:

https://api-sandbox.argyle.com/v1/accounts/<accountId>/periodic-scan

It accepts POST requests with an empty body.

accountId has to be a Sandbox accounts.id, otherwise, an error is returned:

{
    "account": [
        "Periodic scan can be manually scheduled only for sandbox accounts."
    ]
}

Periodic scan data

A periodic scan for Sandbox accounts returns 1-5 new payouts and activities. It is possible to trigger a periodic scan as many times as you need for testing.

Step 12: 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

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>

changes to:

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

Change the linkKey

Argyle Link key in the ConsoleArgyle Link key in the Console

The linkKey is 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 clients consider useful to connect a personal account first and execute 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. We recommend starting with a small subset of your users to confirm that everything is working as expected. From there on, advance gradually to your full user base.

Updated 13 days ago

Did this page help you?