> ## Documentation Index
> Fetch the complete documentation index at: https://developer.rollfi.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Employee Bank Account Linking

## Linking methods

Rollfi supports two main linking options for employee bank accounts.\
Bank account linking is one of the most important steps in employee onboarding, as it helps prevent payroll delays and returns.\
To limit liability, we suggest delegating bank account linking responsibility to the employee rather than admins.

### 🔹 Option 1 - Manual Account Linking

* Employees can manually link their bank accounts using a routing number and account number.
* Please refer to the [addUserBankAccount](https://developer.rollfi.xyz/api-reference/userportal/addUserBankAccount) API documentation.
* Required fields for manual account linking:
  1. accountName
  2. accountType (Rollfi currently supports checking and savings accounts)
  3. accountNumber
  4. routingNumber
  5. payPercentage

#### Sample response:

```json theme={null}
{
    "userPayAccountEntity": {
        "userPayAccountEntityId": "8BE7466C-37B5-4437-8FEE-7D0B582784BD",
        "status": "Ready",
        "message": "The User PayAccount Entity has been added successfully."
    }
}
```

### 🔹 Option 2 - Plaid

* Employees can also link their bank accounts using Plaid through the API.
* Linking through Plaid ensures employee accounts are fully verified before payroll is credited.
* There are two options for linking employee bank accounts through Plaid: email and URL.
* For non-primary accounts, `payPercentage` must be specified after the bank account linking is complete using the `updateUserPayPercentage` API.
* Plaid begin with an additional status `linkurlsent` or `invitesent` depending on wether a URL was generated or en email requested. This is recieved in a webhook and can be seen until the account linking is complete using `getUser`.

#### ⚠️ Warning:

Only one Plaid link can be requested at once. Employees must complete account linking using the original link before adding a secondary bank account.

#### 🔹 Plaid Email

To request a Plaid email link, use the [addUserBankAccount](https://developer.rollfi.xyz/api-reference/userportal/addUserBankAccount) API.

Sample request:

```json theme={null}
{
  "method": "addUserBankAccount",
  "linkType": "Plaid",
  "plaidOptions": "sendInviteByEmail",
  "userPayAccountEntity": {
    "companyId": "8A9B7683-8E02-494D-8422-963FD05EE785",
    "userId": "e066e305-3816-4b06-8576-50d2502be436"
  }
}

response:

{
    "message": "Bank Linking is in progress, payPercentage will be updated, once the linking is completed.",
    "inviteSentTo": "test_user_plaid@mailsac.com",
    "expirationDate": "2026-05-05T00:33:56.068686Z",
    "employeepayaccountentityid": null
}
```

📝 Notes:

* Employees must have an email configured to receive their link.
* After sending the email, the bank account status is `invitesent`. After completion the account follows the normal flow.
* The API response includes an `expirationDate`. Linking must be completed before expiration, or a new link request is required.

#### 🔹 Plaid URL Link

To request a Plaid URL, also use the [addUserBankAccount](https://developer.rollfi.xyz/api-reference/userportal/addUserBankAccount) API.

Sample request:

```json theme={null}
{
  "method": "addUserBankAccount",
  "linkType": "Plaid",
  "plaidOptions": "generateURL",
  "userPayAccountEntity": {
    "companyId": "8A9B7683-8E02-494D-8422-963FD05EE785",
    "userId": "e066e305-3816-4b06-8576-50d2502be436"
  }
}

response:

{
    "message": "Bank Linking is in progress, payPercentage will be updated, once the linking is completed.",
    "plaidLinkURL": "https://secure.plaid.com/hl/ls31018qr87nq0956qo84pq358rs5r8370",
    "expirationDate": "2026-05-05T00:31:34.212711Z"
}
```

📝 Notes:

* The generated link can be used in an `<iframe>` to fully embed Plaid within your UI.
* After the URL is received, the bank account status is `linkurlsent`. After completion the account follows the normal flow.
* The API response includes an `expirationDate` for the link. Linking must be completed before expiration, or a new link request is required.

## Bank Account Updates

* To update a user’s bank account, first add a secondary bank account, then update `payPercentage`. This ensures the user always has an active bank account on file.
* Once the secondary account has finished linking, either manually or through Plaid, use `updateUserPayPercentage` to replace the original account for payment purposes.
* To automate this flow, you can trigger the percentage update after receiving the [Employee Bank Account Webhook](https://developer.rollfi.xyz/api-reference/webhooks/bankAccounts) confirming the new account is ready.

### Re-adding a deactivated bank account

* If a request is made to add a bank account that is already linked to the user with `payPercentage: 0`, update the existing account’s `payPercentage` instead of adding it again.
* This allows the account to be reused for payments while preserving the existing bank account record and audit history.