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

# Create Transfer

> Create a same-account, same-currency book transfer between two virtual accounts

Move funds between two of an account's virtual accounts in the same currency — for example, sweeping collections into an operating account. Transfers are book transfers: the source virtual account is debited and the destination credited together — both balance changes take effect at once, so the transfer settles synchronously.

| Enum             | Values                           | Notes                                                                                          |
| ---------------- | -------------------------------- | ---------------------------------------------------------------------------------------------- |
| `TransferStatus` | `pending`, `completed`, `failed` | Currently always `completed`; `pending` / `failed` reserved for future asynchronous processing |

Creates a same-account, same-currency book transfer between two virtual accounts. The operation is idempotent on `Idempotency-Key` — replaying the same key returns the existing transfer's `id`.

<Warning>
  Validation: A `422` is returned when any business rule fails: source must differ from destination; amount `> 0`; both virtual accounts must belong to this account; currencies must match; both virtual accounts must be `active`; and the source balance must cover the amount (otherwise an insufficient-funds error is returned).
</Warning>

## Path Parameters

<ParamField path="account_id" type="string" required>
  Account id. Both virtual accounts in the transfer must belong to this account.
</ParamField>

## Headers

<ParamField header="Idempotency-Key" type="string" required>
  Idempotency key. Replaying the same key returns the previously created transfer instead of creating a new one.
</ParamField>

## Request Body

<ParamField body="source_virtual_account_id" type="string" required>
  Source virtual account id (`va_…`).
</ParamField>

<ParamField body="destination_virtual_account_id" type="string" required>
  Destination virtual account id (`va_…`). Must differ from the source.
</ParamField>

<ParamField body="amount" type="decimal" required>
  Transfer amount. Must be greater than 0; maximum 18 digits with 6 decimal places.
</ParamField>

<ParamField body="reference" type="string | null">
  Client/bank-visible reference. Maximum 40 characters.
</ParamField>

<ParamField body="internal_note" type="string | null">
  Internal note. Maximum 500 characters.
</ParamField>

## Response

Returns `200` with the new transfer's `id`. Use Get Transfer to retrieve the full object.

<ResponseField name="id" type="string">
  Transfer id (`atx_…`).
</ResponseField>

<RequestExample>
  ```json Request theme={null}
  {
    "source_virtual_account_id": "va_src1a2b3c4d5e6f7g8h9i0j2",
    "destination_virtual_account_id": "va_dst3c4d5e6f7g8h9i0j1k2l3",
    "amount": "500.00",
    "reference": "Sweep to operating account",
    "internal_note": "month-end rebalance"
  }
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "id": "atx_abc123def456ghi789jkl012"
  }
  ```
</ResponseExample>