Transfers

A Transfer represents a requested movement of funds through a connected bank account. It is a write-side API object, unlike a Transaction, 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.

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.

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:

{
  "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:

{
  "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

Create transfer

List transfers

Get transfer

Retry transfer

Required scopes

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

Introduction

Getting started

Core APIs

Coverage and Reliability

Pricing

Support

Changelog

Supported rails

Creating transfers

Transfer lifecycle

Listing and retrying

Failure reasons

Endpoints

Create transfer

List transfers

Get transfer

Retry transfer

Required scopes

​Supported rails

​Creating transfers

​Transfer lifecycle

​Listing and retrying

​Failure reasons

​Endpoints

Create transfer

List transfers

Get transfer

Retry transfer

​Required scopes

Supported rails

Creating transfers

Transfer lifecycle

Listing and retrying

Failure reasons

Endpoints

Required scopes