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.
Please refer to this diagram for an explanation of how the relevant endpoints are related:
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.
For visual examples of all customizable UI elements, refer to the Link customization guide.
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.
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.
percent_allocation is provided, the user will not be able to enter a percent-based allocation.
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.
amount_allocation is provided, the user will not be able to enter an amount-based allocation
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
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.
You can limit the number of companies or platforms that are shown to users in Link during the company selection step:
payDistributionItemsOnlyis set to true, Link will only show Link items that support direct deposit update functionality.
percent_allocationvalues 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_updateobject in the /link-items endpoint.
The account object retrieved from accounts will have the
pay_distribution object containing
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:
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.
Provides information on why the pay distribution update was unsuccessful when
error_code has a corresponding
error_message (see below).
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
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.
Timestamp denoting the last time pay distribution was updated. Timestamps follow the ISO 8601 standard.
You can read direct deposit accounts, and the pay distribution set up on your end user's platform via the pay allocations endpoint.
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: