Hub Accounts: add endpoints for managing associated accounts

content/uk/docs/embedded-banking/hub-accounts.mdx

@@ -18,12 +18,12 @@ import WebhookSummary from 'src/components/webhook-summary';
 <p>All information on this page describes a solution that is <strong>not yet live in production and therefore could change</strong>. This includes any endpoint and webhook details. The information is being provided early to aid you in integrating with our API in our UK simulation environment.</p>
 </Callout>
 
-Hub Accounts are FSCS protected bank accounts held with ClearBank that enable innovative financial products. Use cases for Hub Accounts typically involve making payments to and from a defined set of accounts.
+Hub Accounts are FSCS protected bank accounts held with ClearBank that enable innovative financial products. Use cases for Hub Accounts typically involve making payments to and from a defined set of associated accounts.
 
 To ensure regulatory compliance, Hub Accounts may be subject to one or more of the following constraints:
 
 * Payments may only be made for specific purposes.
-* Payments may only be made to and from designated bank accounts.
+* Payments may only be made to and from certain designated bank accounts.
 * Payment frequency may be restricted.
 
 Exact details will be agreed with your institution directly.
@@ -58,6 +58,13 @@ A sort code will have been assigned to you as part of your onboarding process.
 **Product identity**  
 The `productId` you should use will be provided to you as part of onboarding. This ID determines how your Hub Account behaves.
 
+**Interest payments**  (optional)  
+If your Hub Accounts are configured to accrue interest, you can subscribe to the [Interest Paid webhook](#interest-paid-webhook) to be notified when interest is paid into the account.
+
+<Callout colour="blue">
+  If a Hub Account accrues any unpaid interest during closure, this will be transferred to its nominated account once account closure finishes.
+</Callout>
+
 **Interest configuration** (optional)  
 Hub Accounts may be interest bearing. This will have been agreed between your institution and ClearBank. If your Hub Accounts are interest bearing, you can set up their [interest configuration profile](./interest-configuration). Once created, the profile's `interestConfigurationId` may be reused across subsequent Hub Accounts to refer to the same configuration profile.
 
@@ -75,22 +82,90 @@ Hub Accounts may be interest bearing. This will have been agreed between your in
   ]}
 />
 
-
 <WebhookPlaceholder render='account-created-webhook-v1' />
 
-## Funding a Hub Account
+## Associated and nominated accounts
 
-A Hub Account can be funded and defunded via a nominated account that you assign, or via certain designated accounts.  
-Nominated accounts do not have to be provided by ClearBank: they can be from another external provider. However, the nominated account must be owned by the same account holder as the Hub Account.
-To set or replace the nominated account for a Hub Account, you can use the [PUT /v1/accounts/{accountId}/nominated-account](#set-a-nominated-account) endpoint.
+Other bank accounts can be linked to a Hub Account as an **associated account** or a **nominated account**. Funds can only transferred between a Hub Account and its associated or nominated accounts.
 
-You can make payments from a Hub Account to its nominated account via [Faster Payments](../gbp-payments/faster-payments). To receive updates about transactions for a Hub Account, you can subscribe to the [Transaction Settled webhook](../gbp-payments/faster-payments#transaction-settled-webhook).
+**Nominated account**  
+A nominated account is a single account designated for funding and defunding a Hub Account.
 
-If your Hub Accounts are configured to accrue interest, you can subscribe to the [Interest Paid webhook](#interest-paid-webhook) to be notified when interest is paid into the account.
+* Nominated accounts do not need to be ClearBank provided: they can be from another external provider.
+* The account holder for the nominated account and the Hub Account must be the same.
+* When a Hub Account is closed, any unpaid interest is redirected to its nominated account.
 
-<Callout colour="blue">
-  If a Hub Account accrues any unpaid interest during closure, this will be transferred to its nominated account once account closure finishes.
-</Callout>
+To set or replace the nominated account for a Hub Account, you can use the [POST /v1/accounts/{accountId}/related-accounts](#add-an-associated-or-nominated-account) (preferred), or the [PUT /v1/accounts/{accountId}/nominated-account](#set-a-nominated-account) endpoint.
+
+You can make payments from a Hub Account to its nominated account via [Faster Payments](../gbp-payments/faster-payments) or [CHAPS](../gbp-payments/chaps); to receive updates about FPS transactions for a Hub Account, you can subscribe to the [Transaction Settled webhook](../gbp-payments/faster-payments#transaction-settled-webhook).
+
+<br />
+
+**Associated accounts**  
+Associated accounts are one or several accounts defined to fulfil a specific role in relation to a Hub Account. The function of an associated account will vary depending on your specific use case:
+
+* An associated account does not need to be ClearBank provided: they can be from another external provider.
+* The number of associated accounts you may link to a Hub Account is limited, and will depend on your arrangement with ClearBank.
+* Hub Account funding to and from an associated account may or may not be allowed. This depends on your arrangement with ClearBank.
+
+Associated accounts can be added to a Hub Account using the [POST /v1/accounts/{accountId}/related-accounts](#add-an-associated-or-nominated-account) endpoint; removed using the [DELETE /v1/accounts/{accountId}/related-accounts/{iban}](#remove-an-associated-or-nominated-account) endpoint; and retrieved using the [GET /v1/accounts/{accountId}/related-accounts](#retrieve-associated-and-nominated-accounts) endpoint.
+
+If you need to update the account holder of an associated account, you can use the [PATCH /v1/accounts/{accountId}/related-accounts/{iban}](#amend-an-associated-or-nominated-account) endpoint.
+
+<br />
+
+**Example use case**  
+Hub Accounts could be used to temporarily hold funds between a customer and a vendor.
+
+For example, a Hub Account can be funded from a customer's nominated external account. Funds may then be held in the Hub Account for a defined period before being released to a third‑party vendor for the delivery of services.
+
+## Manage associated or nominated accounts
+
+<EndpointBlock
+  type="post"
+  title="Add an associated or nominated account"
+  endpoints={[
+    {
+      path: "/v1/accounts/{accountId}/related-accounts",
+      version: "1.0.Sterling",
+    }
+  ]}
+/>
+
+<EndpointBlock
+  type="get"
+  title="Retrieve associated and nominated accounts"
+  endpoints={[
+    {
+      path: "/v1/accounts/{accountId}/related-accounts",
+      version: "1.0.Sterling",
+    }
+  ]}
+/>
+
+<EndpointBlock
+  type="patch"
+  title="Amend an associated or nominated account"
+  endpoints={[
+    {
+      path: "/v1/accounts/{accountId}/related-accounts/{iban}",
+      version: "1.0.Sterling",
+    }
+  ]}
+/>
+
+<EndpointBlock
+  type="delete"
+  title="Remove an associated or nominated account"
+  endpoints={[
+    {
+      path: "/v1/accounts/{accountId}/related-accounts/{iban}",
+      version: "1.0.Sterling",
+    }
+  ]}
+/>
+
+## Manage nominated accounts
 
 <EndpointBlock
   type="put"