Skip to main content
Create an internal transfer with POST /v2/internal_transfers. A 200 returns the transfer in processing. Lead then debits the core balance behind the sender account number and credits the core balance behind the receiver. This happens within seconds. Lead tells you the outcome with a webhook.

​
Prerequisites

Before you send, check these:
  • Your token needs the internal_transfer/read_write scope.
  • Both account numbers must be active.
  • Both account numbers must point at core balances on different core accounts. Neither can be on a user deposit balance.
  • The core balance behind the sender account number must be enabled for internal transfers. Lead sets this at onboarding.
  • The sender account number can’t be one Lead holds.
  • Each account number’s internal transfer controls must permit the other. By default all account numbers are permitted.

​
Request requirements

The create request takes these fields and requires an Idempotency-Key header. See Idempotency metadata is optional. See The Internal Transfer Object for every response field.

​
Synchronous rejections

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

​
What you get back

The response includes sender_core_balance_id and receiver_core_balance_id from the start, so you know which two balances are involved. sender_core_transaction_id and receiver_core_transaction_id are null until the transfer posts.

​
Statuses and events

The table lists each status and its webhook. Treat processing as pending. Do not mark the transfer complete until internal_transfer.posted arrives. See Internal Transfer Statuses.

​
Testing in sandbox

A transfer stays in processing until you advance it with POST /v2/simulate/internal_transfers/{internal_transfer_id}/advance, naming posted or rejected in the body.