Pay Distribution

Learn how to update your users' direct deposit information.

Note: this guide relates to the Argyle Link 3 version. The documentation for the previous version of Link is here. Please read through the Migrating to Link 3 article before upgrading to the new version.

Overview

Pay distributions allow users to update their direct deposit information and include your bank account into their pay distribution.

You can set up a process where users distribute their pay in percentages (e.g. 60-40 split) or dollar amounts (e.g. $2,000 to one account and the remainder to another). Minimum, maximum, and suggested values can be defined to accommodate your business goals.

Argyle Link flow when a Link item supports a single 100% pay allocation.
Argyle Link flow when a Link item supports multiple pay allocations.

Process overview

  1. Argyle Link (with pay distribution configuration) is initiated in your application on a button click allowing users to change their pay distribution information.
  2. In the pay distribution configuration, you can determine the percentage and/or dollar amount values of the user's pay to be allocated to your bank account.
  3. Pay distribution configuration is encrypted to ensure your bank account details are never exposed on the front-end. Your full routing and account numbers always appear encrypted on the end user's device
  4. You can read direct deposit accounts and the pay distribution set up on your end user's platform via the /v1/pay-allocations endpoint.
  5. After subscribing to pay distribution webhooks, your back-end systems will be notified when allocations are added, changed, or removed.

Please refer to this diagram for an explanation of how the relevant endpoints are related:

Pay distributions configuration

Argyle Link initiates a pay distribution change process if a pay distribution configuration is provided. Pay distribution configuration describes the desired outcome of that change.

Here are some examples:

Allocations in the pay distribution configuration are just recommendations. Users are able to modify the amounts or percentage of their pay to go to your account.

If you want to prevent the user from modifying the allocation value, set min_value equals to max_value, as shown in the amount_allocation example below. In this case, the user is not allowed to change the value of $200, only accept or reject it:

If the config contains only a percent allocation, Argyle restricts the options to percent only for the user. In the same way, if only the amount allocation is configured, the user will not be able to transfer you a percentage of their pay.

Pay distribution configuration parameters

For visual examples of all customizable UI elements, refer to the Link customization guide.

bank_account.bank_name
string
required

Bank name that will be displayed alongside an obfuscated account number in Link. This is used for labeling purposes in Argyle Link and does not need to perfectly match the actual bank name.

bank_account.routing_number
string
required

9-digit code that is based on the bank location where the user's account was opened.

bank_account.account_number
string
required

8 to 17-digit code that identifies the user as the account holder in the bank. The allocation will be sent to this account.

bank_account.account_type
string
required

Type of the bank account.

Possible values: checking, savings.

default_allocation_type
string
optional

The allocation type that will be presented to the user by default. Not all employment accounts support both formats. If you select a default that is not supported by the user's employment account, the user will still be able to enter an allocation using the supported format as long as a default value for that format is provided.

Possible values: percent, amount.

percent_allocation
object
optional

An object representing a percentage to be transferred into the bank account.

At least one of percent_allocation or amount_allocation is required for the configuration.

percent_allocation.value
string integer
required

The default percent value that will be displayed to the user during the pay distribution update process.

percent_allocation.value is required if percent_allocation is used in the configuration.

If no percent_allocation is provided, the user will not be able to enter a percent-based allocation.

percent_allocation.min_value
string integer
optional

The minimum percent value that the user will be able to deviate from your recommended or default value. Set this to the same as percent_allocation.value if you do not want the user to choose a lower amount than your default value.

percent_allocation.max_value
string integer
optional

The maximum percent value that the user will be able to deviate from your recommended or default value. Set this to the same as percent_allocation.value if you do not want the user to choose a higher amount than your default value.

amount_allocation
object
optional

An object representing a dollar amount to be transferred into the bank account.

At least one of percent_allocation or amount_allocation is required for the configuration.

amount_allocation.value
string integer
required

The default amount value that will be displayed to the user during the pay distribution update process.

amount_allocation.value is required if amount_allocation is used in the configuration.

If no amount_allocation is provided, the user will not be able to enter an amount-based allocation

amount_allocation.min_value
string integer
optional

The minimum amount value that the user will be able to deviate from your recommended or default value. Set this to the same as amount_allocation.value if you do not want the user to choose a lower amount than your default value.

amount_allocation.max_value
string integer
optional

The maximum amount value that the user will be able to deviate from your recommended or default value. Set this to the same as amount_allocation.value if you do not want the user to choose a higher amount than your default value.

allow_add_allocation
boolean
optional

Setting allow_add_allocation to false, will remove the "Add bank account" button in the Pay distribution screen of Argyle Link.

Default value is true.

enable_suggestions
boolean
optional

If set to true, the user will be shown a suggested pay allocations redistribution (given there are more than two pay allocations in the account) and will only need to click the "Confirm" button. If set to false, the user will have to manually enter how the pay allocations should be distributed.

Default value is true.

allow_editing
boolean
optional

If set to true, users will see the Edit button in the pay allocations screen and will be able to change the allocations. If set to false, users will not see the Edit button and will not be able to make any changes.

Default value is true.

Link integration

To start the pay distribution update process in Link you must initialize it with the payDistributionConfig parameter set to an encrypted version of your pay distribution configuration.

The encryption is necessary to ensure your bank account details are never exposed on the front-end. Your full routing and account numbers always appear encrypted on the end user's device.

To encrypt your pay distribution config make a POST request into pay-distribution-configs/encrypt with your pay distribution config in the payload.

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

Initializing Link with the payDistributionConfig parameter with the encrypted pay distribution configuration value will set up Link to run the pay distribution update process.

Limiting the number of Link items in the company selection screen

You can limit the number of companies or platforms that are shown to users in Link during the company selection step:

  • If the payDistributionItemsOnly is set to true, Link will only show Link items that support direct deposit update functionality.
  • Additionally, if you define only the amount_allocation or percent_allocation values in the pay distribution config, then only the Link items that support amount or percent allocations will be shown to the user. To find out which Link items support which types of allocations, please refer to the features.pay_distribution_update object in the /link-items endpoint.

Account statuses

The account object retrieved from accounts will have the pay_distribution object containing status, error_code, error_message, and updated_at fields.

The account object refers to the pay distribution process as a whole, which can consist of multiple pay allocations.

The pay distribution object represents the status of the pay distribution update process. Here is an example of an account after a successful pay distribution update:

Attributes

pay_distribution.status
string

Denotes the point in the process of the pay distribution update process. Possible values:

idle - pay distribution update process has not been initiated.

awaiting_confirmation - waiting for the user to confirm updated pay distribution.

awaiting_connection - waiting to establish connection to the user's employment account.

scanning - scanning existing pay allocations prior to update process.

updating - updating the user's pay distribution.

success - pay distribution update successful.

error – pay distribution update unsuccessful. See the pay_distribution.error_code below for details.

pay_distribution.error_code
string

Provides information on why the pay distribution update was unsuccessful when pay_distribution.status is error.

Possible values: confirmation_timeout, incompatible_config, invalid_mfa, mfa_timeout, missing_allocation_type, not_supported, not_supported_by_employer, system_error, unsupported_bank_accounts, unsupported_mfa_method, unusable_bank_account, updated_too_recently.

Each error_code has a corresponding error_message (see below).

pay_distribution.error_message
string

Provides additional information on why the pay distribution update error occurred. Each error_message corresponds to a particular error_code (see above). The list below is formatted as:

error_code - error_message

Possible values:

confirmation_timeout - this user did not finish setting up their new pay distribution.

incompatible_config - the pay allocation details that have been submitted are not supported by this user's employment account.

invalid_mfa - this user did not provide the correct multi-factor authentication response.

mfa_timeout - this user did not complete multi-factor authentication.

missing_allocation_type - one or more of this account's pay allocations is missing a type (percent/amount/remainder), causing Argyle to be unable to update the user's pay distribution information.

not_supported - this user's employment account does not support updating pay distribution information.

not_supported_by_employer - this user's employment account does not support changes to pay distribution information. This may be because the employer has disabled users from editing this information.

system_error - Argyle encountered a problem connecting to this account. Our team has been notified and is investigating.

unsupported_bank_accounts - this user's employment account includes pay allocations to bank account types that Argyle does not yet support, like HSAs.

unsupported_mfa_method - this user's employment account uses a multi-factor authentication method that Argyle does not currently support.

unusable_bank_account - the provided bank account cannot be used for pay distribution update. Please provide a different bank account.

updated_too_recently - pay distribution update is temporarily unavailable. This user's account is in a cool-off state after an earlier update.

pay_distribution.updated_at
string

Timestamp denoting the last time pay distribution was updated. Timestamps follow the ISO 8601 standard.

Reading pay allocations

You can read direct deposit accounts, and the pay distribution set up on your end user's platform via the pay allocations endpoint.

Attributes

id
string uuid

Unique ID of the pay allocation.

account
string

ID of the account associated with a Link item that generates the payout to the user.

employer
string

The company or entity that employs the user.

created_at
timestamp

A timestamp when the pay allocation object was created. This will not always match the time it was updated in the payroll platform.

updated_at
timestamp

A timestamp when the pay allocation object was last updated. This will not always match the time it was updated in the payroll platform.

bank_account.account_number
string

5 to 17-digit code that identifies the user as the account holder in the bank. In most cases, the account number will be 8-17 digits long. Depending on the payroll platform, the value can be fully or partially obfuscated.

bank_account.routing_number
string

9-digit code that is based on the bank location where the user's account was opened. Depending on the payroll platform, the value can be fully or partially obfuscated.

bank_account.account_type
string

The type of the user's bank account.

Possible values: checking, savings, other.

status
string

Account status in the employment record source. A pending status will signify that the pay allocation was changed in Argyle Link, but is not yet propagated within the company or payroll (Link item) platform.

Possible values: active, pending.

allocation_type
string

The selected type of allocation.

Possible values: percent, amount.

allocation_value
string decimal

The amount associated with the allocation type.

allocation_value can be a decimal value (e.g. 147.27) or remainder (total salary minus any decimal allocations).

metadata
string

Metadata holds additional available, often unstructured, information about this data resource.

Removing pay allocations

Pay allocations can be removed via the API without invoking Link. You can learn more about removing pay allocations here.

Webhooks

There are 3 webhook events related to pay distributions:

pay_allocations.added - A new pay allocation was added.

pay_allocations.removed - A pay allocation was removed.

pay_allocations.updated - A change in a pay allocation occurred.

Here's an example of a webhook payload you would get when a new pay allocation is added:

All three webhooks have the same payload parameters:

account
string uuid

ID of the parent account.

user
string uuid

ID of the user the account belongs to.

pay_allocation
string uuid

ID of the pay allocation that was added, removed, or updated.