Pay Distribution configs

Learn about Pay Distribution configs.

Argyle Link initiates a pay distribution update process when a pay distribution configuration (pd_config) is provided. Pay distribution configurations describe the desired outcome of that change and can include a bank_account object, a card object, or both.

If you do not have PCI DSS compliance and want to utilize a third-party financial service provider to handle sensitive card data, you can define the card_source object in your pay distribution configuration.

Refer to Direct deposit switching experience for more information on this use case.

📘

bank_account, card, and card_source objects are validated when they are passed to the /pay-distribution-configs/encrypt endpoint. Learn more about validation in Encrypt a pay distribution config.

Objects within a pd_config

Attribute

Type

Description

bank_account

object optional

See underlying attributes

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

This object is optional, but you must define either the card or bank_account option, or both options in your pd_config.

card

object optional

See underlying attributes

The object that contains card details for a pay allocation.

This object is optional, but you must define either the card or bank_account option, or both options in your pd_config.

card_source

object

See underlying attributes

The object that contains instructions for a third-party provider to initiate an instant payout to cards.

card_source must be defined in your pd_config when card details are handled by a third-party financial service provider.

🚧

card_source cannot be combined with bank_account or card when creating a pay distribution configuration. Learn more about how this is validated in Encrypt a pay distribution config.

Attributes of bank_account

Attribute

Type

Description

bank_name

string optional

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.

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

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 the card has been issued to. This should be entered exactly as displayed on the card.

cardholder_first_name

string optional

Forename of the person the card has been issued to.

cardholder_last_name

string optional

Surname of the person the card has been issued to.

card_name

string optional

Card name that is displayed alongside an obfuscated card number in Link. You can define card_name to label cards in Argyle Link.

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 card object when creating a pay distribution configuration for cards, including the optional fields. Doing so enables compatibility with all platforms that support card pay distribution.

Attributes of 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 Link. You can define card_name to label cards in Argyle Link.

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

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 payout cards. Visit Direct deposit switching experience for more information about configuring allocations and different use cases.

Attribute

Type

Description

default_allocation_type

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: percentamount.

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 the configuration.

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 the configuration.

entire_allocation

boolean optional

If set to true, users will see a Pay Distribution screen with a single allocation to which their entire net pay is assigned. All previous allocations will be marked as “removed” and will not be visible on the Pay Distribution screen. The user must confirm the change in order to proceed with the action.

Default value is false.

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.

❗️

Setting entire_allocation to true has implications on other pay distribution config parameters:

  • If entire_allocation is set to true, amount_allocation and percent_allocation values cannot be set. default_allocation_type can still be provided to decide if the suggested pay distribution screen will contain a single amount allocation (i.e., remainder) or a single percent allocation (100%).
  • allow_editing is ignored because requiring a single allocation should not allow any modifications. No matter what value is set, there will be no Edit button in Link’s suggested pay distribution screen.

Attributes of percent_allocation

Attribute

Type

Description

value

string number 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.

min_value

string number 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.

max_value

string number 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.

Attributes of amount_allocation

Attribute

Type

Description

value

string number 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.

min_value

string number 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.

max_value

string number 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.

Endpoints

Endpoints

Encrypt a pay distribution config - POST /pay-distribution-configs/encrypt

Examples

{
    "bank_account": {
        "bank_name": "New Bank",
        "routing_number": "084101234",
        "account_number": "9483746361234",
        "account_type": "checking"
    },
    "default_allocation_type": "amount",
    "percent_allocation": {
            "value": "20",
            "min_value": "10",
            "max_value": "30"
    },
    "amount_allocation": {
            "value": "200",
            "min_value": "200",
            "max_value": "200"
    },
    "entire_allocation": false,
    "allow_editing": true
}
{
   "bank_account":{
      "bank_name":"New Bank",
      "routing_number":"084101234",
      "account_number":"9483746361234",
      "account_type":"checking"
   },
   "entire_allocation":true,
   "default_allocation_type":"amount"
}
{
    "card": {
        "card_number": "4253177385403456",
        "cardholder_title": "Mr",
        "cardholder_first_name": "John",
        "cardholder_last_name": "Doe",
        "card_name": "Viza",
        "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"
    }
}
{
    "bank_account": {
        "bank_name": "New Bank",
        "routing_number": "084101234",
        "account_number": "9483746361234",
        "account_type": "checking"
    },
    "card": {
        "card_number": "4253177385403456",
        "cardholder_title": "Mr",
        "cardholder_first_name": "John",
        "cardholder_last_name": "Doe",
        "card_name": "Viza",
        "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"
    },
    "amount_allocation": {
        "value": "200"
    }
}
{
    "card_source": { 
        "partner": "unit",
        "card_name": "My favorite card",
        "details": {
            "id": "ymp000f9",
            "org_id": "lj93cqt2"
        }
    }
}