Book transfers

A book transfer moves money between two accounts at the bank. No rail is involved. It posts to the ledger at once as one journal, and it is complete when the response arrives.

Creating one

POST /transfers/book takes an Idempotency-Key header and these fields. The two accounts may belong to the same customer or to different customers.

from_account_idstringRequired

The account that pays.

to_account_idstringOne of two

The account that receives, by id. It is used when both this and to_account_number are sent.

to_account_numberstringOne of two

The account that receives, by any of its open account numbers. A number the bank does not know answers 404 not_found.

amountintegerRequired

Minor units, greater than zero.

currency_codestringRequired

ISO 4217. It must be the currency of both accounts.

descriptionstringRequired

Shown on both accounts' statements, after the words "Book transfer".

What happens

The service checks the caller, the paying account's approval policy and payment limits, and the state of both accounts. It then posts one journal of kind transfer, dated the current business date: a debit to the paying account's ledger account and a credit to the receiving one. No hold is placed and there is no pending state. The answer is 201 with status completed and the journal_id.

The transfer publishes payments.book_transfer.completed, with the transfer as its data, and the ledger publishes ledger.journal.posted. In GET /transfers it has type book and direction internal, and the account_id filter finds it from either account.

Repeating the request with the same key returns the first transfer with 200. The ledger journal is keyed on the same value, so a retry after a timeout cannot post twice.

What can refuse it

Code	Status	When
`step_up_required`	403	The caller is a customer session whose last PIN or passkey confirmation is more than five minutes old. Service and staff tokens are not asked.
`forbidden`	403	The customer may not initiate payments from the paying account.
`payments.approval_required`	422	The paying account's approval policy covers the amount, or the token came from a customer API key. Create a scheduled transfer and have it approved.
`payments.limit_exceeded`	422	The paying account's payment limits are on and the amount is over the per-payment limit, the account's daily limit or the initiator's daily limit.
`accounts.account_not_open`	422	Either account is not `open`.
`accounts.debit_blocked`, `accounts.certificate_locked`, `accounts.transfer_limit_reached`, `accounts.withdrawal_restricted`	422	A restriction on the paying account forbids the debit.
`payments.same_account`	422	Both sides are the same account.
`validation_failed`	400	The amount is not positive, neither receiving field is sent, the currency differs from either account, or the receiving account is an unfunded certificate and the amount is below its minimum deposit.
`ledger.insufficient_available`	422	The available balance, posted less holds, does not cover the amount. A book transfer does not draw on overdraft protection.

Between entities of a group

POST /transfers/inter-entity moves money between accounts of two customers in one active customer group. It takes from_account_id, to_account_id, amount, currency_code, description, requested_by and a purpose: loan, repayment, capital, dividend, management_fee, settlement or other. initiated_by names the member acting and defaults to the paying entity.

Two accounts of one customer are refused with payments.same_customer. Use a book transfer.
Customers that do not share an active group are refused with payments.not_in_group.
Under the group's parent_only policy, a member other than the parent is refused with payments.group_policy.

The paying account's approval policy applies. The money moves as an ordinary book transfer, and the answer is an inter-entity transfer (iet_) carrying the group_id, both customer ids, the book_transfer_id and the journal_id. It publishes payments.inter_entity_transfer.completed.

On a schedule

A scheduled transfer with a to_account_id, or to a counterparty whose account is at this bank, runs as a book transfer on each run date. That is also the route for a payment that needs approval.