DDS configurations

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, and card_source objects are validated when they are passed to the /pay-distribution-configs/encrypt endpoint. 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.

AttributeTypeDescription
bank_accountobject
optional

See underlying attributes
The object that contains bank account information for a pay allocation.
cardobject
optional

See underlying attributes
The object that contains card details for a pay allocation.
card_sourceobject
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_account and card in a single DDS configuration.

Attributes of bank_account

AttributeTypeDescription
bank_namestring optionalBank 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_numberstring required9-digit code that is based on the bank location where the user's account was opened.
account_numberstring required8 to 17-digit code that identifies the user as the account holder in the bank. The allocation will be sent to this account.
account_typestring requiredType of the bank account.

Possible values: checking, savings.

Attributes of card

AttributeTypeDescription
card_numberstring required8 to 19-digit payout card number as displayed on the card.
cardholder_titlestring optionalTitle of the person to which the card has been issued. This should be entered exactly as displayed on the card.
cardholder_first_namestring optionalForename of the person to which the card has been issued.
cardholder_last_namestring optionalSurname of the person to which the card has been issued.
card_namestring optionalCard 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_yearinteger ≥ 2000 requiredExpiration year as specified on the card.
expiration_monthinteger between 1 and 12 requiredExpiration month as specified on the card.
card_cvc_cvvstring required3 or 4-digit security code found on the back of the card.
address_line1string optionalAddress line 1—for example, street, PO Box, or company name.
address_line2string optionalAddress line 2—for example, apartment, suite, unit, or building.
statestring optionalState, county, province, or region.
citystring optionalCity, district, suburb, town, or village.
postal_codestring optionalPostal code of the address associated with the card.
countrystring optionalCard's country of issue in ISO 3166-1 alpha-2 format.

👍

Argyle recommends populating every field in the card object 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

AttributeTypeDescription
partnerstringDenotes 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_namestring optionalCard 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
detailsobject

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

AttributeTypeDescription
idstringThe card identifier that is used to retrieve card details from Unit’s database. Visit Unit’s documentation on Cards for more information.
org_idstringIdentifies 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.

AttributeTypeDescription
default_allocation_type
*deprecated
string optionalThe 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: percentamount.
percent_allocationobject 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_allocationobject 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_allocationboolean optionalIf 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_editingboolean optionalIf 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

AttributeTypeDescription
valuestring number requiredThe 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_valuestring number optionalThe 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_valuestring number optionalThe 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

AttributeTypeDescription
valuestring number requiredThe 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_valuestring number optionalThe 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_valuestring number optionalThe 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"
    }
}