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

# Transfers

> Create, track, and retry bank transfers

A **Transfer** represents a requested movement of funds through a connected bank account. It is a write-side API object, unlike a [Transaction](/transactions), which is an observed bank record after the fact.

Transfer access is subject to your API key scopes, the connected bank's capabilities, and the delegated user's bank-side permissions.

<Note>
  All external transfers require end-user approval in the bank portal. Waycore initiates the bank-side flow, then the transfer moves to `pending_bank_approval` until the end user completes approval. Internal transfer approval requirements depend on the bank, account setup, and delegated-user permissions.
</Note>

## Supported rails

| Rail       | Use case                                                                                           |
| ---------- | -------------------------------------------------------------------------------------------------- |
| `internal` | Move funds between connected accounts at the same institution or platform-supported internal rail. |
| `ach`      | US domestic ACH.                                                                                   |
| `wire`     | US domestic wire.                                                                                  |
| `swift`    | International wire via SWIFT.                                                                      |
| `fednow`   | US instant payment via FedNow.                                                                     |
| `rtp`      | US instant payment via RTP.                                                                        |
| `sepa`     | SEPA payments.                                                                                     |
| `local`    | Local domestic rails not represented by a more specific enum value.                                |

The requested rail is sent as `transferType`. For external transfers, the destination account identity is described separately by `destination.paymentIdentifier.scheme`, such as `us_ach`, `uk_sort_code_account_number`, `ca_eft`, `au_bsb_account_number`, or `iban`.

## Creating transfers

Create transfers with `POST /v1/transfers`. The endpoint returns `202 Accepted` with a `Transfer` object.

Use an `Idempotency-Key` header when creating or retrying a transfer so retries are safe. If the same request is replayed, Waycore may return the original response with `Idempotent-Replayed: true`. If the same idempotency key is reused with a materially different request, the API returns `409 Conflict`.

Internal transfer request:

```json theme={null}
{
  "type": "internal",
  "amount": {
    "type": "money",
    "value": "1250.00",
    "currency": "USD"
  },
  "sourceAccountId": "11111111-2222-3333-4444-555555555555",
  "destination": {
    "type": "account",
    "accountId": "66666666-7777-8888-9999-000000000000"
  },
  "transferType": "internal",
  "clientReference": "payroll-funding-2026-05-28"
}
```

External transfer request:

```json theme={null}
{
  "type": "external",
  "amount": {
    "type": "money",
    "value": "1250.00",
    "currency": "USD"
  },
  "sourceAccountId": "11111111-2222-3333-4444-555555555555",
  "destination": {
    "accountHolderName": "Acme Payroll LLC",
    "recipientType": "business",
    "paymentIdentifier": {
      "scheme": "us_ach",
      "countryCode": "US",
      "details": {
        "routingNumber": "011000015",
        "accountNumber": "000123456789"
      }
    }
  },
  "transferType": "ach",
  "clientReference": "payroll-funding-2026-05-28"
}
```

## Transfer lifecycle

| Status                  | Meaning                                                                            |
| ----------------------- | ---------------------------------------------------------------------------------- |
| `queued`                | The transfer has been accepted and is waiting to execute.                          |
| `executing`             | Waycore is executing the transfer through the bank.                                |
| `pending_bank_approval` | The bank flow has been initiated and the end user must approve in the bank portal. |
| `completed`             | Execution completed successfully.                                                  |
| `failed`                | Execution failed before completion. See `failureReason`.                           |
| `returned`              | The bank or downstream rail returned the payment after execution.                  |
| `cancelled`             | The transfer was cancelled.                                                        |
| `unknown`               | The bank state does not yet map cleanly to a more specific public status.          |

`requestedAmount` is the amount requested by the caller. `executedAmount` is populated once the actual amount sent is known.

## Listing and retrying

Use `GET /v1/transfers` to list transfers ordered by `createdAt desc, id desc`. You can filter by `status`, `accountId`, `createdAtFrom`, and `createdAtTo`, and paginate with `cursor`.

Use `GET /v1/transfers/{id}` to retrieve the latest known state for one transfer.

Use `POST /v1/transfers/{id}/retry` to retry a failed or retryable transfer. Retry requests support the same `Idempotency-Key` header as create requests. A retry returns `202 Accepted` with the updated transfer.

If a transfer is not retryable, the API returns `409 Conflict`.

## Failure reasons

When a transfer is `failed`, `returned`, or `cancelled`, `failureReason` may include:

* `insufficient_funds`
* `invalid_destination`
* `unsupported_transfer_type`
* `provider_rejected`
* `provider_unavailable`
* `timed_out`
* `unknown`

## Endpoints

<CardGroup cols={2}>
  <Card title="Create transfer" icon="send" href="/api-reference/transfers/create-transfer" />

  <Card title="List transfers" icon="list" href="/api-reference/transfers/list-transfers" />

  <Card title="Get transfer" icon="search" href="/api-reference/transfers/get-transfer" />

  <Card title="Retry transfer" icon="rotate-ccw" href="/api-reference/transfers/retry-transfer" />
</CardGroup>

## Required scopes

| Scope             | Used by                    |
| ----------------- | -------------------------- |
| `transfers:write` | Create and retry transfers |
| `transfers:read`  | List and get transfers     |