Learn about direct deposit switching (DDS) configurations.
Argyle Link initiates a direct deposit update when a DDS configuration is provided that has been encrypted to a payDistributionConfig. DDS configurations contain bank account and debit card details that determine which DDS screens are shown to users, and what pay allocations are suggested.
Refer to the structuring DDS configurations section of our direct deposit switching guide for more information.
bank_account,card, andcard_sourceobjects are validated when they are passed to the/pay-distribution-configs/encryptendpoint. Learn more encryption validation here.
Objects within a DDS configuration
At least one bank_account or card/card_source object must be specified in your DDS configuration.
| Attribute | Type | Description |
|---|---|---|
| bank_account | object optional See underlying attributes | The object that contains bank account information for a pay allocation. |
| card | object optional See underlying attributes | The object that contains card details for a pay allocation. |
| card_source | object optional See underlying attributes | The object that contains card details for a pay allocation when you are not PCI DSS compliant and are using a third-party to handle sensitive card details. |
Refer to add a bank and debit account in our direct deposit switching guide before including both
bank_accountandcardin a single DDS configuration.
Attributes of bank_account
bank_account| Attribute | Type | Description |
|---|---|---|
| bank_name | string optional | Bank name that will be displayed alongside an obfuscated account number in Argyle Link. This is used for labeling purposes and does not need to perfectly match the actual bank name. |
| routing_number | string required | 9-digit code that is based on the bank location where the user's account was opened. |
| 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. |
| account_type | string required | Type of the bank account. Possible values: checking, savings. |
Attributes of card
card| Attribute | Type | Description |
|---|---|---|
| card_number | string required | 8 to 19-digit payout card number as displayed on the card. |
| cardholder_title | string optional | Title of the person to which the card has been issued. This should be entered exactly as displayed on the card. |
| cardholder_first_name | string optional | Forename of the person to which the card has been issued. |
| cardholder_last_name | string optional | Surname of the person to which the card has been issued. |
| card_name | string optional | Card name that is displayed alongside an obfuscated card number in Argyle Link. You can define card_name to label cards.For example: My favorite card |
| expiration_year | integer ≥ 2000 required | Expiration year as specified on the card. |
| expiration_month | integer between 1 and 12 required | Expiration month as specified on the card. |
| card_cvc_cvv | string required | 3 or 4-digit security code found on the back of the card. |
| address_line1 | string optional | Address line 1—for example, street, PO Box, or company name. |
| address_line2 | string optional | Address line 2—for example, apartment, suite, unit, or building. |
| state | string optional | State, county, province, or region. |
| city | string optional | City, district, suburb, town, or village. |
| postal_code | string optional | Postal code of the address associated with the card. |
| country | string optional | Card's country of issue in ISO 3166-1 alpha-2 format. |
Argyle recommends populating every field in the
cardobject when creating a DDS configuration for debit cards, including the optional fields. Doing so enables compatibility with all platforms that support adding debit cards.
Attributes of card_source
card_source| Attribute | Type | Description |
|---|---|---|
| partner | string | Denotes the third-party financial service provider that handles card data. Currently the only accepted value is unit. Accepted values can potentially change when more partners are integrated in the future. |
| card_name | string optional | Card name that is displayed alongside an obfuscated card number in Argyle Link. You can define card_name to label cards.For example: My favorite card |
| details | object See underlying attributes | The object that contains all required information used in authentication and data retrieval between Argyle’s API and the third-party financial service provider. |
Child attributes of details
details| Attribute | Type | Description |
|---|---|---|
| id | string | The card identifier that is used to retrieve card details from Unit’s database. Visit Unit’s documentation on Cards for more information. |
| org_id | string | Identifies your organization in Unit’s database. This ID is represented as orgId by Unit. Visit Unit’s documentation on Partner API Tokens for more information. |
Allocation settings
Use these settings to define the amount or percentage of money that is allocated to a bank account. Allocation fields do not apply to cards. Visit our direct deposit switching guide for which pay allocations to use for your use case.
| Attribute | Type | Description |
|---|---|---|
| default_allocation_type *deprecated | string optional | The allocation type that is presented to the user by default: percent_allocation or amount_allocation.Not all employment accounts support both types. If you select a default that is not supported by the user's employment account, the user is still presented with an allocation of supported type as long the percent_allocation and/or amount_allocation object is populated.Possible values: percent, amount. |
| percent_allocation | object optional See underlying attributes | An object representing a percentage to be transferred into the bank account. At least one of percent_allocation or amount_allocation is required for partial paycheck DDS configurations. |
| amount_allocation | object optional See underlying attributes | 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 partial paycheck DDS configurations. |
| entire_allocation | boolean optional | If included in the DDS configuration and set to true, the user's entire net pay will be assigned to the newly introduced allocation. Previous allocations will be removed.Default value is false. |
| allow_editing | boolean optional | If set to true, users will see the Edit button in the direct deposit update screen and will be able to change their 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. |
Attributes of percent_allocation
percent_allocation| Attribute | Type | Description |
|---|---|---|
| value | string number required | The default percent value that will be displayed to the user during the direct deposit 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. |
| min_value | string number optional | The minimum percent value that the user will be able to input. Set this to the same as percent_allocation.value if you do not want the user to choose a lower percentage than your default value. |
| max_value | string number optional | The maximum percent value that the user will be able to input. Set this to the same as percent_allocation.value if you do not want the user to choose a higher percentage than your default value. |
Attributes of amount_allocation
amount_allocation| Attribute | Type | Description |
|---|---|---|
| value | string number required | The default amount value that will be displayed to the user during the direct deposit 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. |
| min_value | string number optional | The minimum amount value that the user will be able to input. 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. |
| max_value | string number optional | The maximum amount value that the user will be able to input. 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. |
Endpoints
These are the endpoints available for pay-distribution-configs/encrypt.
| Endpoints |
|---|
Encrypt to payDistributionConfig - POST /pay-distribution-configs/encrypt |
Examples
Refer to DDS flows in our direct deposit switching guide for a full list of example DDS configuration objects and their associated use cases.
Switch direct deposit for a bank account:
(receive full paycheck, no user editing)
{
"bank_account": {
"bank_name": "YellowHorizon",
"routing_number": "084101234",
"account_number": "9483746361234",
"account_type": "checking"
},
"entire_allocation": true,
"allow_editing": false
}
Add a debit card:
(you are PCI DSS compliant and are not using a third party to handle sensitive card information)
{
"card": {
"card_number": "4253177385403456",
"cardholder_title": "Mr",
"cardholder_first_name": "John",
"cardholder_last_name": "Doe",
"card_name": "Master Visa",
"expiration_year": 2030,
"expiration_month": 10,
"card_cvc_cvv": "900",
"address_line1": "759 Victoria Plaza",
"address_line2": "Unit 12",
"city": "Los Angeles",
"state": "CA",
"postal_code": "90210",
"country": "US"
}
}
Add a debit card:
(you are not PCI DSS compliant and are using Unit as a third party to handle sensitive card information)
{
"card_source": {
"partner": "unit",
"card_name": "My Unit payout card",
"details": {
"id": "ymp000f9",
"org_id": "lj93cqt2"
}
}
}
Switch direct deposit for a bank account and add a debit card:
(PCI DSS compliant only)
{
"bank_account": {
"bank_name": "YellowHorizon",
"routing_number": "084101234",
"account_number": "9483746361234",
"account_type": "checking"
},
"entire_allocation": true,
"allow_editing": false,
"card": {
"card_number": "4253177385403456",
"cardholder_title": "Mr",
"cardholder_first_name": "John",
"cardholder_last_name": "Doe",
"card_name": "Master Visa",
"expiration_year": 2030,
"expiration_month": 10,
"card_cvc_cvv": "900",
"address_line1": "759 Victoria Plaza",
"address_line2": "Unit 12",
"city": "Los Angeles",
"state": "CA",
"postal_code": "90210",
"country": "US"
}
}