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. |
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"
}
{
"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_fundsinvalid_destinationunsupported_transfer_typeprovider_rejectedprovider_unavailabletimed_outunknown
Endpoints
Required scopes
| Scope | Used by |
|---|
transfers:write | Create and retry transfers |
transfers:read | List and get transfers |
