The Internal Transfer Object

An internal transfer moves money between two account numbers on different core accounts at Lead. You create one with POST /v2/internal_transfers and read it with GET /v2/internal_transfers/{internal_transfer_id}. POST requires an Idempotency-Key header. See Idempotency. This example is a posted transfer. Acme moved $2,500 from its operating account to its settlement account. Lead debited the operating account’s core balance and credited the settlement account’s. The transfer includes a core transaction for each: one for the debit and one for the credit.

{
  "id": "internal_transfer_4KqLe9Wc4OlYa7nZsU5xF2bR8t",
  "amount": 250000,
  "currency_code": "USD",
  "description": "Daily settlement sweep",
  "status": "posted",
  "sender_account_number_id": "account_number_2fTZ4St5HSJnxzv7jdevxQnev3U",
  "sender_core_balance_id": "core_balance_2xYw9Kn3Jp7QuS2lY5mAbC0dE4f",
  "sender_core_transaction_id": "core_transaction_2pQ7Hs9Vb3NkXz6mYrT4wE1a",
  "receiver_account_number_id": "account_number_3gUA5Tu6ITKoyAw8kefwyRofw4V",
  "receiver_core_balance_id": "core_balance_3yZx0Lo4Kq8RvT3mZ6nBcD1fF5g",
  "receiver_core_transaction_id": "core_transaction_2pT1Lv3Ye6QnAc9pBuW7zH4d",
  "rejection": null,
  "metadata": {},
  "created_at": "2026-10-07T15:02:11Z",
  "updated_at": "2026-10-07T15:02:14Z"
}

A transfer is either posted or rejected, never both. sender_core_transaction_id and receiver_core_transaction_id are set only on a posted transfer, and rejection is set only on a rejected one. On a processing transfer all three are null. See The rejection block for a rejected example.

Fields

The table lists each field on the object.

Field	Type	Description
`id`	string	Unique identifier, prefixed `internal_transfer_`.
`amount`	integer	Amount as an integer in minor units. 5000 is $50.00.
`currency_code`	string	ISO 4217. `USD`.
`description`	string	Your description of the transfer. Required on create.
`status`	enum	`processing`, `posted`, or `rejected`. See Internal Transfer Statuses.
`sender_account_number_id`	string	The account number money leaves.
`sender_core_balance_id`	string	The core balance behind the sender account number. Resolved by Lead.
`sender_core_transaction_id`	string or null	The core transaction for the debit on the sender’s balance. `null` until the transfer posts, and stays `null` on a rejected transfer.
`receiver_account_number_id`	string	The account number money arrives in.
`receiver_core_balance_id`	string	The core balance behind the receiver account number. Resolved by Lead.
`receiver_core_transaction_id`	string or null	The core transaction for the credit on the receiver’s balance. `null` until the transfer posts, and stays `null` on a rejected transfer.
`rejection`	object or null	Set when `status` is `rejected`. See The rejection block.
`metadata`	object	Key-value pairs for your own use. Lead doesn’t read them.
`created_at`, `updated_at`	timestamp	RFC 3339, UTC.

The rejection block

The table lists the fields in the rejection block.

Field	Type	Description
`reason`	enum	Why the transfer was rejected after Lead accepted it. The Reason table in this section lists the values.
`details`	string or null	Free text about the rejection, for example which account number was inactive.

Reason	Populated when
`account_number_not_active`	The sender or receiver account number wasn’t `active` when Lead processed the transfer.
`beneficiary_account_number_unrecognized`	Lead could not resolve the receiver account number.
`non_sufficient_funds`	The sender’s core balance did not have enough available funds.
`ofac_rejection`	The transfer failed sanctions screening.
`internal_error`	Lead could not complete the transfer and has stopped retrying.

This transfer was accepted, then rejected when Lead went to post it because the operating account’s available balance had dropped below the amount. No money moved and no core transactions were created.

{
  "id": "internal_transfer_4LrMf0Xd5PmZb8oAtV6yG3cS9u",
  "amount": 250000,
  "currency_code": "USD",
  "description": "Daily settlement sweep",
  "status": "rejected",
  "sender_account_number_id": "account_number_2fTZ4St5HSJnxzv7jdevxQnev3U",
  "sender_core_balance_id": "core_balance_2xYw9Kn3Jp7QuS2lY5mAbC0dE4f",
  "sender_core_transaction_id": null,
  "receiver_account_number_id": "account_number_3gUA5Tu6ITKoyAw8kefwyRofw4V",
  "receiver_core_balance_id": "core_balance_3yZx0Lo4Kq8RvT3mZ6nBcD1fF5g",
  "receiver_core_transaction_id": null,
  "rejection": {
    "reason": "non_sufficient_funds",
    "details": "The originating account did not have sufficient balance. Balance: 184250"
  },
  "metadata": {},
  "created_at": "2026-10-08T15:00:03Z",
  "updated_at": "2026-10-08T15:00:06Z"
}

Creating an internal transfer

The create request takes these fields:

Field	Required	Description
`sender_account_number_id`	Yes	The account number money leaves. It must be active when Lead posts the transfer. If it isn’t, the transfer is rejected with account_number_not_active.
`receiver_account_number_id`	Yes	The account number money arrives in. It must be active when Lead posts the transfer. If it isn’t, the transfer is rejected with account_number_not_active.
`amount`	Yes	Amount as an integer in minor units. 5000 is $50.00.
`currency_code`	Yes	`USD`.
`description`	Yes	Your description of the transfer.
`metadata`	No	Key-value pairs for your own use.

Lead checks the following before it accepts the transfer. A failure returns an error and creates no transfer.

Condition	Result
Either account number is on a user deposit balance	The request returns an error. To move money into or out of a user deposit balance, use the user deposit transactions API.
Both account numbers resolve to the same core account	The request returns an error. You can’t use an internal transfer to move funds between account numbers belonging to the same account.
The core balance behind the sender account number doesn’t permit internal transfers	`422`. Lead sets this permission at onboarding.
The sender account number is held by Lead	The request returns an error.

Some checks depend on balances at posting time, such as available funds and account number status. They run after Lead accepts the transfer, and their results appear in the rejection block.

Listing internal transfers

The GET /v2/internal_transfers endpoint returns a list (objects, has_more) sorted newest first. You can filter it by:

Filter	Matches
`sender_account_number_id`	Transfers sent from the account number.
`receiver_account_number_id`	Transfers received by the account number.
`core_transaction_id`	The transfer whose `sender_core_transaction_id` or `receiver_core_transaction_id` equals the value.
`status`	One status value.
`created_at`	Transfers created in the range.

Coming from v1

A v2 internal transfer replaces the v1 internal transfer. Transfers created on /v1/internal_transfer are readable on /v2/internal_transfers. The create request body is unchanged.

v1	v2	Notes
`POST /v1/internal_transfer`	`POST /v2/internal_transfers`	Resource name is plural. Same request body.
`sender_account_id`, `receiver_account_id`	Removed	Filter and reconcile by account number and core balance instead.
No balance fields	`sender_core_balance_id`, `receiver_core_balance_id`	Added in v2. Resolved from the account numbers.
No ledger link	`sender_core_transaction_id`, `receiver_core_transaction_id`	Added in v2. One for the sender and one for the receiver. `null` until posted.
No `core_transaction_id` filter	`core_transaction_id` list filter	Added in v2. Matches the sender’s or the receiver’s.
Transfers to or from an account number on a user deposit balance accepted	Rejected	Use a user deposit transaction.
No sender permission check	Sender core balance must permit internal transfers, else `422`	Lead sets this at onboarding.
Errors in the v1 shape	Errors in the v2 shape	The same-account rule is unchanged.

Products

Banking Infrastructure

Customers & Accounts

Balances and Transactions

Lending & Receivables

Payment Rails

Fields

The rejection block

Creating an internal transfer

Listing internal transfers

Coming from v1

​Fields

​The rejection block

​Creating an internal transfer

​Listing internal transfers

​Coming from v1

​Related

Fields

The rejection block

Creating an internal transfer

Listing internal transfers

Coming from v1

Related