This guide walks through launching customer deposit accounts — checking-style products, wallets, or stored value — where your customers’ money is held at Lead. It’s the foundation flow for most programs: the same chain underlies debit card programs and most money-movement products.
How it works
Each customer is an Entity; each product they hold is an Account with the deposit capability; you provision routable Account Numbers so money can reach them; money moves over any payment rail; and you report Balances and Transactions daily as the ledger of record. Two account concepts are in play and must not be confused: the customer’s user Account (the product container you create) and your program’s core FBO (the Lead-managed pooled account where the money physically sits). Account Numbers hang off the core account — even when assigned to an individual customer, the number attaches to the FBO and carries the customer on its entity_id; an inbound payment lands on the FBO and is attributed to the customer from there (Object Model).
Example scenario
Nest Egg is a savings app. When Priya signs up, Nest Egg screens her, creates her Entity, opens her deposit Account, and provisions an account number against its program FBO with Priya’s entity_id — the address she gives her employer for direct deposit. Her paycheck lands on the FBO and attributes to her via the account number; Nest Egg’s ledger credits her, and its daily files report her balance and activity to Lead.
Objects involved
Before you start
- Sandbox credentials with entity, account, account-number, and rail scopes. Your program’s FBO exists from onboarding — note its
account_id; Step 3 needs it.
- Balance and Transaction reporting is file-based today. Daily files over SFTP, due by 6:00 a.m. CT the business day after the activity (empty file on quiet days) — Balances & Transactions, SFTP setup. User transaction and balance APIs are planned successors (Platform Evolution).
- The Accounts API has a planned unified-model successor (the user account API), and Account Numbers will attach to balances rather than accounts under the unified model — same flows, typed IDs, migration in cohorts with notice (Platform Evolution). Treat all IDs as opaque strings.
Integration steps
Step 1: Create the customer Entity
POST /v0/entities
{ "type": "individual", "screening": { "...": "your KYC/OFAC results" }, "...": "..." }
Keep Entity data current after launch — updates to identifying fields trigger re-screening attestations.
Step 2: Open the deposit Account
POST /v0/accounts
{ "entity_id": "...", "capabilities": ["deposit"] }
Created active; account_holder_type derives from the entity types (all-individual → consumer). This user Account is the product container — it is not the account that Account Numbers attach to.
Step 3: Provision an Account Number — against the core account, not the user Account
POST /v1/account_number
{ "account_id": "your program FBO's core account_id", "entity_id": "Priya's entity_id", "...": "..." }
The account_id here is the core account’s
account_<id>-style identifiers, and passing the Step 2 id here is the most common wiring mistake in this flow. Account Numbers attach to the core account — your FBO — with the customer carried on entity_id; the user Account never appears in this call (Object Model, “How the Two Surfaces Connect”). Then assign and activate per the Account Number lifecycle — the number can’t transact until active. (Under the unified model, account numbers will point to a balance instead; the create call changes shape, the concept — a routable address attributed to a customer — doesn’t.)
Decision point: one number per customer is the common pattern; issue additional numbers when the product needs distinct addresses per purpose (e.g. a dedicated direct-deposit number), and use per-number controls to scope what each address accepts.
Step 4: Receive money
POST /v1/simulate/ach/incoming_ach
{ "account_number": "...", "amount": 50000, "...": "..." }
The payment lands on the FBO; attribute it to Priya via the account number it arrived on. Handle ach.posted to credit her in your ledger. Verify webhook signatures and handle replays from the first handler you write (webhooks).
Step 5: Send money
Send over the rails your program uses, wiring up each rail’s webhooks and returns per its pages under Payment Rails. Decision point: rail choice is a product decision — Money Movement compares reach, speed, finality, and operating hours.
Step 6: Report
Produce your first Balance and Transaction files, submit over SFTP, and clear validation against the File Reference schemas. Cadence and semantics: Balances & Transactions.
Handling exceptions
Testing this flow in sandbox
The full chain runs in sandbox: attested-passed screening, account and account-number lifecycle, the incoming-ACH simulator with advance, and each contracted rail’s simulators per Environments & testing. Exercise at least one return path per rail and validate files against realistic volume before production submission.
Object Model (the two surfaces — read this if Step 3’s warning surprised you) · Balances & Transactions · Account Numbers · Payment Rails · Make Your First Payment API Call · Launch a Debit Card Program · Reports Lead Delivers
If something in this guide doesn’t match what you see, contact your Lead team. 
