Transfer

Each rail has its own transfer object. One summary shape covers them, so a single list shows an account's movements.

The common shape

GET /transfers and GET /transfers/{id} return the summary. The list is newest first and filters by type, account_id and status.

type is ach, iat, book, wire or realtime. rail is set on realtime transfers only: fednow or rtp.
direction is outbound, inbound or, for a book transfer, internal.
amount is an integer in minor units of currency_code: 125000 is 1,250.00 USD.
account_id is the customer account that moved. A book transfer also names the receiving account in counterparty_account_id, and the account_id filter matches either side.
journal_id is the ledger journal, once the transfer has posted.

Check deposits and international wires are not in this list. They have their own, at /transfers/checks and /transfers/international-wire.

The rail's own object

The rail's endpoint returns the full object, with what the summary leaves out: the counterparty, trace numbers, message ids, return codes.

Type	Object	Id prefix	Read
`ach`, `iat`	ACH transfer	`acht_`	`GET /transfers/ach/{id}`, `GET /transfers/iat/{id}`
`book`	Book transfer	`book_`	`GET /transfers/book/{id}`
`wire`	Wire transfer	`wire_`	`GET /transfers/wire/{id}`
`realtime`	Realtime transfer	`rttr_`	`GET /transfers/realtime/{id}`

An ACH transfer's own direction is credit (money pushed out) or debit (money pulled in). The summary shows a credit as outbound and a debit as inbound. Entries received from other banks are ACH receipts (achr_), listed as inbound ach items with their outcome as the status.

The counterparty is written on the transfer itself: routing_number, account_number, name and account_type on ACH, the bank's aba and bank_name with the beneficiary on a wire. A saved counterparty (cpty_) is used by scheduled transfers.

Ties to the ledger

An ACH credit, an outbound wire and an outbound realtime transfer each place a pending_debit hold when they are accepted, so the money cannot be spent twice. On an ACH transfer the hold is named in hold_id. When the payment posts, its journal releases the hold in the same step and is named in journal_id. A settled ACH entry that is later returned also carries reversal_journal_id. A book transfer places no hold: it posts at once.

States

A book transfer is completed when it is created. An ACH transfer is pending, then batched, sent and settled. It can also be held_for_review, rejected, cancelled or returned.

A wire or a realtime transfer publishes an event named after each new state, such as payments.wire.settled. An ACH transfer publishes payments.ach_transfer.created, and its file reports the rest as payments.ach_file.sent and payments.ach_file.settled.

The shared fields are listed in the Transfer object.