>  Switch To Link 5 and API v2 Documentation

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 below.


#The DDS configuration object

  • Allocation related properties define the 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.
  • At least one bank_account or card / card_source object must be specified in your DDS configuration.
    • At least one of percent_allocation or amount_allocation object is required for partial paycheck bank_account DDS configurations.
  • 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
  • #
    percent_allocationobject

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

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

  • #
    valuestring
    required

    The default percent value that will be displayed to the user during the direct deposit update process.

    value is required a percent_allocation object is included in the configuration.

  • #
    min_valuestring

    The minimum percent value that the user will be able to input.

    Set this to the same as value if you do not want the user to choose a lower percentage than your default value.

  • #
    max_valuestring

    The maximum percent value that the user will be able to input.

    Set this to the same as value if you do not want the user to choose a higher percentage than your default value.

  • #
    amount_allocationobject

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

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

  • #
    valuestring
    required

    The default amount value that will be displayed to the user during the direct deposit update process.

    value is required a amount_allocation object is included in the configuration.

  • #
    min_valuestring

    The minimum amount value that the user will be able to input.

    Set this to the same as value if you do not want the user to choose a lower amount than your default value.

  • #
    max_valuestring

    The maximum amount value that the user will be able to input.

    Set this to the same as value if you do not want the user to choose a higher amount than your default value.

  • #
    entire_allocationboolean

    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_editingboolean

    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.

  • #
    default_allocation_type *DEPRECATEDstring

    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.

  • #
    bank_accountobject

    The object that contains bank account information for a pay allocation.

  • #
    bank_namestring

    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_numberstring

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

  • #
    account_numberstring

    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_typestring

    Type of the bank account.

  • #
    cardobject

    The object that contains card details for a pay allocation.

    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.

  • #
    card_numberstring
    required

    8 to 19-digit payout card number as displayed on the card.

  • #
    cardholder_titlestring

    Title of the person to which the card has been issued. This should be entered exactly as displayed on the card.

  • #
    cardholder_first_namestring

    Forename of the person to which the card has been issued.

  • #
    cardholder_last_namestring

    Surname of the person to which the card has been issued.

  • #
    card_namestring

    Card name that is displayed alongside an obfuscated card number in Argyle Link. You can define card_name to label cards (e.g. My favorite card).

  • #
    expiration_yearinteger ≥ 2000
    required

    Expiration year as specified on the card.

  • #
    expiration_monthinteger between 1 and 12
    required

    Expiration month as specified on the card.

  • #
    card_cvc_cvvstring
    required

    3 or 4-digit security code found on the back of the card.

  • #
    address_line1string

    Address line 1—for example, street, PO Box, or company name.

  • #
    address_line2string

    Address line 2—for example, apartment, suite, unit, or building.

  • #
    statestring

    State, county, province, or region.

  • #
    citystring

    City, district, suburb, town, or village.

  • #
    postal_codestring

    Postal code of the address associated with the card.

  • #
    countrystring

    Card's country of issue in ISO 3166-1 alpha-2 format.

  • #
    card_sourceobject

    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.

  • #
    partnerstring

    Denotes the third-party financial service provider that handles card data.

    unit is the only accepted value, but more may be added in the future.

  • #
    card_namestring

    Card name that is displayed alongside an obfuscated card number in Argyle Link (e.g. My favorite card). You can define card_name to label cards.

  • #
    detailsobject

    The object that contains all required information used in authentication and data retrieval between Argyle's API and the third-party financial service provider.

  • #
    idstring

    The card identifier that is used to retrieve card details from Unit's database. Visit Unit's documentation on Cards for more information.

  • #
    org_idstring

    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.



Refer to DDS flows in our direct deposit switching guide for a full list of example DDS configuration objects and their associated use cases.

Example — Full paycheck (No editing)
1{
2  "bank_account": {
3    "bank_name": "YellowHorizon",
4    "routing_number": "084101234",
5    "account_number": "9483746361234",
6    "account_type": "checking"
7  },
8  "entire_allocation": true,
9  "allow_editing": false
10}
Example — Add debit card
1{
2  "card": {
3    "card_number": "4253177385403456",
4    "cardholder_title": "Mr",
5    "cardholder_first_name": "John",
6    "cardholder_last_name": "Doe",
7    "card_name": "Master Visa",
8    "expiration_year": 2030,
9    "expiration_month": 10,
10    "card_cvc_cvv": "900",
11    "address_line1": "759 Victoria Plaza",
12    "address_line2": "Unit 12",
13    "city": "Los Angeles",
14    "state": "CA",
15    "postal_code": "90210",
16    "country": "US"
17  }
18}
Example — Add debit card (Not PCI DSS compliant)
1{
2  "card_source": {
3    "partner": "unit",
4    "card_name": "My Unit payout card",
5    "details": {
6      "id": "ymp000f9",
7      "org_id": "lj93cqt2"
8    }
9  }
10}
Example — Full paycheck + Add debit card
1{
2  "bank_account": {
3    "bank_name": "YellowHorizon",
4    "routing_number": "084101234",
5    "account_number": "9483746361234",
6    "account_type": "checking"
7  },
8  "entire_allocation": true,
9  "allow_editing": false,
10  "card": {
11    "card_number": "4253177385403456",
12    "cardholder_title": "Mr",
13    "cardholder_first_name": "John",
14    "cardholder_last_name": "Doe",
15    "card_name": "Master Visa",
16    "expiration_year": 2030,
17    "expiration_month": 10,
18    "card_cvc_cvv": "900",
19    "address_line1": "759 Victoria Plaza",
20    "address_line2": "Unit 12",
21    "city": "Los Angeles",
22    "state": "CA",
23    "postal_code": "90210",
24    "country": "US"
25  }
26}

#Encrypt to payDistributionConfig

post/v1/pay-distribution-configs/encrypt

Encrypt a DDS configuration to a payDistributionConfig.

  • To start the direct deposit update process in Link you must initialize it with the payDistributionConfig parameter set to the encrypted string returned as encrypted_config after encrypting your DDS configuration.
  • The encryption is necessary to ensure bank account and card details are never exposed on the front-end. Full routing, account, and card numbers always appear encrypted on the end user's device.
  • To encrypt your DDS configuration make a POST request to /pay-distribution-configs/encrypt with your DDS configuration in the payload.

Request body
  • #
    object
    required

    DDS configuration (pre-encryption).

Example Request
1curl --request POST \
2     --url https://api.argyle.com/v1/pay-distribution-configs/encrypt \
3     --header 'accept: application/json' \
4     --header 'content-type: application/json' \
5     --data '{
6        "bank_account": {
7            "bank_name": "YellowHorizon",
8            "routing_number": "084101234",
9            "account_number": "9483746361234",
10            "account_type": "checking"
11        },
12        "amount_allocation": {
13            "value": "177",
14            "min_value": "177",
15            "max_value": "177"
16        }
17     }'
Example Response
1{
2  "encrypted_config": "CiQAB/5leT7O7tuqZTNRlvgzuORNFdZu0tYaImtc7v5uTy5vBc0S4AQAL2UHl11enTB971I0t8Tx0U729+vnVIIX8splHDJijiiDEtcScd3W8b52FmFpg/IL3eHs7umRmd6JO8mvORDhBGQqF+x0XrZhzaZC4qB+ZiEs2rztEYGLMPgoYKegh7oKauNc9ZDf43l/KFDCYlYgW2Zd7LbB4M+PN39E8+GgMqHYTOKgpXFMYVBAniV8r58eu2PI9FV8sZ0JXRlOX2YTXAkEFC3XeX174olNQU4Eu1xlu+EPf61yCF1/UBvetVB7rSXMW/IcFrYkZCFVw+1YlDtGgk7uksStCB6ePuyWeu0/erjOitZidL5FwCx90OS0AEoMDqsXVQq+nyB+rCe2IAX9YFEL/xiWCB5gGXxzE+Y814WinVKq3YsSzsaMOhpKOpLfFuOb8YhQDzsq+OTlMx6W6RjOPSaqk29yQYWTDOaH37/iOABqnM8YWwbdz434KbuH02vo9gpS5Ny4MEyYTk5Uy0l8Z9rCce+/hUIRjqGNPQgim+kNwBp204V3tGX96fI/3JLwTeTUcmk4JrSK3G/LfDWQrxz+UYvxKO3BV56I6lvJcXMPrAlDGTzlxHOO9jUhSpBun0mU/gdbUXr9wunufZrb/Zc+4th+YCeVoBuwJ/TReBP8+fCfo0WQGXCX3wKGB5kl+PaoxRmTSrj24iSJLRCFTCygEeyW3/IFNK6/lCbYCLitJgLeOlz+oh+//1IDIrwj7f0h61ZQ15UdHqXBua0dJ/INxUjlUKyfmG8tMY5fCJaLLQkfhe/E0StQ8JdzYTbq2YGQIBfDuWCJpRbXYHQ40L7mQGXPDF+ocA=="
3}
Updating Argyle status...
© 2024 Argyle Systems Inc.argyle.com