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, 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, 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