Pay Distribution updated

Implement the accounts.pay_distribution_updated webhook to know when a direct deposit switching flow is successful.

The accounts.pay_distribution_updated webhook is triggered after:

  1. You request to a direct deposit update.
  2. Your user confirms this update.
  3. Argyle updates the direct deposit successfully.

This webhook notifies you when the direct deposit update is successful. Depending on your DDS configuration, this is what the webhook returns:

  • If the DDS configuration is for a single allocation type that is either a bank account or a card, a single accounts.pay_distribution_updated webhook is triggered. The type field in the webhook’s payload returns bank_account or card accordingly.
  • If the DDS configuration has both a bank account and a card, two separate accounts.pay_distribution_updated webhooks are triggered with corresponding payloads for each allocation type.

📘

pay_allocations webhooks are fired after a successful direct deposit update as well, but they can also trigger during periodic scans if something on the payroll provider's side changes or the user independently updates their pay allocations.

We recommend using accounts.pay_distribution_updated to track direct deposit changes you initiate for the user.

📘

A payroll account can allocate a paycheck to multiple accounts. Pay distribution webhooks will fire if any changes are made to any of these paycheck allocations. To monitor if a pay allocation to an individual account changes, set up webhooks for pay allocations, using these pages:

Event

accounts.pay_distribution_updated

Configuration

AttributeTypeDescription
include_resourceboolean optionalIf set to true in the webhook subscription configuration, the webhook payload returns the full account object as resource. Defaults to false.

Payload

AttributeTypeDescription
accountstring uuidID of the account where the direct deposit update was successful.
userstring uuidID of the user associated with the account.
resourceobjectThe full account object is returned if the webhook subscription contains "include_resource": true in the configuration.
allocation_idstring uuidID of the pay allocation passed in the pay distribution config. The value is null in some edge cases where it is not possible to match the updated pay allocation to any of the user's bank accounts or cards with total accuracy. In such cases, the details field provides the reason why the updated allocation was not matched.
pay_distribution_changedbooleanIndicates whether a successful direct deposit update has resulted in any changes in the user’s pay allocation details.

For example, when a successful direct deposit update was created using the same pay allocation details that were already present on the user’s payroll account, pay_distribution_changed returns false because no details were changed.
typestring enumDenotes the type of allocation that was updated.

Possible values: bank_account, card
flowstring enumDenotes the type of direct deposit flow that triggered the update.

Possible values:

- update - there was an update to the direct deposit.
- removal - a deposit account was removed.
- activation *deprecated - a pay allocation becomes active after a microdeposit verification.
detailsstring enumIn some edge cases where it is not possible to match the updated pay allocation to any of the user's bank accounts or cards with total accuracy, the value of the allocation_id field returns as null. If the value of allocation_id is null, the details field provides the reason why the updated allocation was not matched.

Possible values:

- obfuscated - the exact allocation_id cannot be determined because the payroll provider obfuscates bank account or card details.
- multiple_matching_allocations - the exact allocation_id cannot be determined because there are multiple allocations with partially matching bank account or card details used in the DDS configuration.

When allocation_id cannot be matched

In this example, due the partially matching bank account details in bank_account_A and bank_account_B, it is not possible to match the updated pay allocation to any of the user's bank accounts or cards with total accuracy. In this case, allocation_id returns null and details returns multiple_matching_allocations.

{
    "bank_account_A": {
        "routing_number": "*****1234",
        "account_number": "*********5678",
        "account_type": "savings"
    },
    "bank_account_B": {
        "routing_number": "*****1234",
        "account_number": "*********5678",
        "account_type": "savings"
    }
}

Examples

curl -X POST https://api.argyle.com/v1/webhooks \
  -u api_key_id:api_key_secret \
  -H "Content-Type: application/json" \
  -d '{"events": ["accounts.pay_distribution_updated"],
       "secret": "<secret for signature verification>",
         "name": "accounts.pay_distribution_updated",
       "config": { "include_resource": true },
          "url": "https://webhook.site/url"}'
{
    "event": "accounts.pay_distribution_updated",
    "name": "Pay distribution updated successfully",
    "data": {
        "account": "ada143be-3c90-4534-b7ea-9899674dc6e0",
        "user": "3823026e-a964-45f6-b201-6b8c096b30d3",
        "resource": {
            "id": "ada143be-3c90-4534-b7ea-9899674dc6e0",
            "user": "3823026e-a964-45f6-b201-6b8c096b30d3",
            "employers": [
                "homedepot"
            ],
            "..."
        },
        "allocation_id": "4334r6e-a964-45eef6-b201-64464",
        "pay_distribution_changed": true,
        "type": "bank_account",
        "details": null,
        "flow": "update"
    }
}