Refresh External Bank Accounts

Overview

Plaid bank connections expire periodically and require the customer to re-authenticate with their financial institution. When a connection expires, the external bank account's state transitions to refresh_required and the account cannot be used for transactions until the customer completes Plaid's Update Mode flow.

❗️

Transactions disabled

No transactions can be performed with an external bank account in the refresh_required state.

Detect the refresh_required state

Poll GET /api/external_bank_accounts/{external_bank_account_guid} and check the state field.

{
  "guid": "external_bank_account_guid",
  "name": "Customer Checking Account",
  "asset": "USD",
  "account_kind": "plaid",
  "bank_guid": "bank_guid",
  "customer_guid": "customer_guid",
  "state": "refresh_required",
  "failure_code": null,
  "created_at": "2026-01-01T12:00:00.000Z",
  "updated_at": "2026-01-15T12:00:00.000Z"
}

Refresh the bank connection

Guide the customer through Plaid's Update Mode in five steps:

1. Detect the refresh_required state by polling GET /api/external_bank_accounts/{external_bank_account_guid}.
2. Create a workflow with POST /api/workflows using kind: link_token_update and the external_bank_account_guid that needs to be refreshed. Read the plaid_link_token from the response.
3. Initialize Plaid Link with the plaid_link_token in update mode.
4. The customer re-authenticates with their financial institution through the Plaid Link flow.
5. Update the external bank account state by calling PATCH /api/external_bank_accounts/{external_bank_account_guid} with state set to completed.

⚠️

Manual state update required

The Platform does not automatically update the external bank account state after the customer re-authenticates. Your application must explicitly call PATCH /api/external_bank_accounts/{external_bank_account_guid} with { "state": "completed" } to transition the account out of the refresh_required state.

Create the update workflow

POST /api/workflows
Content-Type: application/json
Authorization: Bearer YOUR_TOKEN

{
  "type": "plaid",
  "kind": "link_token_update",
  "language": "en",
  "link_customization_name": "default",
  "external_bank_account_guid": "external_bank_account_guid",
  "redirect_uri": "https://yourapp.com/api/plaid-redirect-uri"
}

Finalize the refresh

After the customer completes the Plaid Link update flow, call the patch external bank account endpoint to finalize the refresh:

PATCH /api/external_bank_accounts/{external_bank_account_guid}
Content-Type: application/json
Authorization: Bearer YOUR_TOKEN

{
  "state": "completed"
}

Sandbox testing

To test the full update mode flow, force an external bank account into the refresh_required state using the patch external bank account endpoint:

PATCH /api/external_bank_accounts/{external_bank_account_guid}
Content-Type: application/json
Authorization: Bearer YOUR_TOKEN

{
  "state": "refresh_required"
}

This simulates an expired bank connection so you can verify that your application handles the update mode flow correctly.

Next steps

• Add Customer External Bank Accounts
• Verify External Bank Accounts
• Transfer Process