# How to implement ISA transfers

## Prerequisites

- **Authentication scopes** — `isa:admin`, `transactions:read`
For more information, refer to
[Authentication scopes](/products/byol/concepts/api_concepts/authentication/authentication_oauth#list-of-authentication-scopes).
- **An active ISA tax wrapper** — The receiving account group must have a Stocks and Shares ISA tax wrapper in status
`ACTIVE`.
For more information, refer to [How to integrate ISA tax wrappers](/products/byol/guides/tax_wrappers/tax_wrappers_isa_integration).
- **Webhook handler ready** — Set up a webhook endpoint and subscribe to
[`ISA_TRANSFER.*`](/products/byol/guides/tax_wrappers/tax_wrappers_isa_transfers_webhooks) events. Creating a transfer is asynchronous and there
is no endpoint to read a transfer back, so webhooks are the only way to observe its progress. To receive the events
sent when a transfer settles, also subscribe to the `CASH_TRANSACTION` and `ISA_WRAPPER_ALLOWANCE` event categories.
For more information, refer to
[Implementing webhooks](/products/byol/getting_started/implementing_webhooks).


## Overview

A transfer within the same ISA manager moves cash from an end user's existing ISA into their Upvest-supported Stocks
and Shares ISA. You create the transfer through the Investment API, and Upvest credits the account group and applies
any current year subscription to the end user's annual ISA allowance.

Upvest has no visibility of the source ISA, so you supply two things the API cannot derive: the cash amount to credit,
and how much of that amount relates to the current tax year. For background on the stages and the allowance rules, see
the [ISA transfers overview](/products/byol/guides/tax_wrappers/tax_wrappers_isa_transfers_overview).

The Investment API currently supports incoming, cash settled transfers within the same ISA manager. Transfers between
different ISA managers, outgoing transfers, and in-specie settlement are planned for a future release.

## Transfer lifecycle

Each status change emits a matching `ISA_TRANSFER.*` webhook event.

| **Status** | **Description** |
|  --- | --- |
| `NEW` | The transfer has been created and has not started processing. |
| `PROCESSING` | The transfer is being processed. |
| `SETTLED` | The transfer is complete. The cash has been credited and any current year subscription has been applied to the allowance. This status is terminal. |
| `CANCELLED` | The transfer has been cancelled and no funds move. This status is terminal. |


## Create an ISA transfer

**POST** [`/isa/transfers`](/api/isa/create_isa_transfer)

This operation requires an `idempotency-key` header containing a randomly generated UUID. Reuse the same value when
retrying a request so the transfer is not created twice. For more information, refer to
[Idempotency](/products/byol/concepts/api_concepts/idempotency).

The response returns the created transfer with status `NEW`.

Example request
```json
{
  "direction": "INCOMING",
  "type": "NO_ISA_MANAGER_CHANGE",
  "method": "CASH",
  "user_id": "4b2e2e64-7544-4c3f-a98d-dfdc03d487aa",
  "account_group_id": "79e9f9a2-dd29-4b54-9cca-b4c31956beb3",
  "cash_amount": "10000.00",
  "currency": "GBP",
  "counterparty": {
    "account_number": "5WJSZB3C8"
  },
  "current_year_subscription": {
    "tax_year": "2025/2026",
    "cash_amount": "3000.00",
    "first_subscription_at": "2025-09-14T12:10:00.00Z"
  }
}
```

Example response
```json
{
  "id": "3a4b1383-11b3-4987-9f6f-593ae0991c1d",
  "created_at": "2025-11-09T14:10:00.00Z",
  "updated_at": "2025-11-09T14:10:00.00Z",
  "status": "NEW",
  "direction": "INCOMING",
  "type": "NO_ISA_MANAGER_CHANGE",
  "method": "CASH",
  "user_id": "4b2e2e64-7544-4c3f-a98d-dfdc03d487aa",
  "account_group_id": "79e9f9a2-dd29-4b54-9cca-b4c31956beb3",
  "cash_amount": "10000.00",
  "currency": "GBP",
  "counterparty": {
    "account_number": "5WJSZB3C8"
  },
  "current_year_subscription": {
    "tax_year": "2025/2026",
    "cash_amount": "3000.00",
    "first_subscription_at": "2025-09-14T12:10:00.00Z"
  }
}
```

### Request fields

| **Field** | **Required/Optional** | **Description** |
|  --- | --- | --- |
| `direction` | Required | The direction of the transfer. Currently, only `INCOMING` (funds move into the Upvest-supported Stocks and Shares ISA) is supported. |
| `type` | Required | The type of the transfer. Currently, only `NO_ISA_MANAGER_CHANGE` (the transfer occurs within the same ISA manager) is supported. |
| `method` | Required | The settlement method of the transfer. Currently, only `CASH` is supported. |
| `user_id` | Required | Unique identifier of the end user making the transfer. |
| `account_group_id` | Required | Unique identifier of the account group that receives the cash. This account group must hold an `ACTIVE` ISA tax wrapper. |
| `currency` | Required | Currency of the transfer, as an [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) code. Currently, only `GBP` is supported. |
| `cash_amount` | Conditional | Total cash amount of the transfer, as a decimal string with up to nine digits and two decimal places, for example `"10000.00"`. Required for `NO_ISA_MANAGER_CHANGE` transfers. |
| `counterparty` | Optional | Counterparty of the transfer. For incoming transfers, this is the source ISA. |
| `counterparty.account_number` | Conditional | The unique reference of the account group being transferred, such as the ISA reference number of the source ISA. Maximum 28 characters. Required when `counterparty` is provided. |
| `current_year_subscription` | Conditional | Details of the part of the transfer that relates to the current tax year. Required for `NO_ISA_MANAGER_CHANGE` transfers. |
| `current_year_subscription.tax_year` | Conditional | The current tax year in `YYYY/YYYY` format, for example `"2025/2026"`. Required when `current_year_subscription` is provided. |
| `current_year_subscription.cash_amount` | Conditional | The part of `cash_amount` that relates to current tax year subscriptions and so counts towards the current year ISA allowance. Required when `current_year_subscription` is provided. |
| `current_year_subscription.first_subscription_at` | Optional | The date and time of the first subscription made to the source ISA in the current tax year. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html). |


`current_year_subscription.cash_amount` must not exceed `cash_amount`. Only the current year portion counts towards
the annual allowance — the remainder is treated as previous years' balance and does not affect the allowance.

### Response fields

Only the fields not present in the request are listed below.

| **Field** | **Required/Optional** | **Description** |
|  --- | --- | --- |
| `id` | Required | Unique identifier of the ISA transfer, as a UUID. |
| `created_at` | Required | Date and time when the resource was created. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html). |
| `updated_at` | Required | Date and time when the resource was last updated. [RFC 3339-5](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6), [ISO8601 UTC](https://www.iso.org/iso-8601-date-and-time-format.html). |
| `status` | Required | Status of the transfer: `NEW`, `PROCESSING`, `SETTLED`, or `CANCELLED`. See [Transfer lifecycle](#transfer-lifecycle). |


## After the transfer settles

When a transfer reaches `SETTLED`:

- The cash is credited to the account group, and the credit appears as a cash transaction of type `ISA_TRANSFER`. You
can retrieve it with [`GET /transactions/cash`](/api/transactions/list_cash_transactions), and it also triggers a
`CASH_TRANSACTION.EXECUTED` webhook event whose `object.type` is `ISA_TRANSFER`. The cash transaction's
`references` array contains an entry with `type` set to `ISA_TRANSFER` and `id` set to the ID of the transfer, so
you can match the credit to the transfer.
- The used amount on the receiving wrapper's annual allowance increases by `current_year_subscription.cash_amount`,
and an `ISA_WRAPPER_ALLOWANCE.UPDATED` event is sent. Update the allowance on the source ISA to reflect the amount
that moved.