# Environments and Testing Source: https://docs.lead.bank/core-concepts/platform/environments-and-testing Understand Lead's sandbox and production environments. Lead operates two environments — sandbox and production — with different behaviors around transaction auto-advance, settlement simulation, and daily processing windows. Understanding both helps you build against realistic conditions and avoid surprises at go-live. ## **Environments** ### **Sandbox** The sandbox environment is available at [api.sandbox.lead.bank](http://api.sandbox.lead.bank). It is isolated from production and shares no data with it. Use sandbox to build and test your integration before requesting production credentials. Key differences from production: * **No auto-advance.** Transactions do not progress through statuses automatically. Use the /simulations endpoints to advance them manually. See [Sandbox](/get-started/sandbox) for the full list of simulation endpoints by rail. * **KYC and OFAC not enforced.** Entity data is accepted without identity verification or sanctions screening. * **International wires reach accepted only.** Full settlement simulation is not available for international wires in sandbox. * **/simulations endpoints return 404 in production.** Do not call simulation endpoints from production code. ### **Production** The production environment is available at [api.lead.bank](http://api.lead.bank). Credentials are provisioned by your Technical Account Manager after you complete sandbox testing and production go-live. [See Program Launch](/get-started/program-launch) for the milestone sequence. # Executing vs. Reporting Source: https://docs.lead.bank/core-concepts/platform/executing-vs-reporting Which Lead APIs execute actions like moving money, and which report facts where you are the ledger of record — and how to predict an API's behavior from the difference. Lead's APIs follow two different contracts, and knowing which one you're holding predicts almost everything about how an API behaves — whether it sends webhooks, whether a status is authoritative or declarative, and what happens when you make a mistake. This page explains the two contracts once, so the rest of the documentation doesn't have to re-explain them product by product. ## **The two contracts** **Execution APIs make something happen.** When you call `POST` on a payment rail — ACH, Wires, Instant Payments, Internal Transfers, Blockchain Payments — or request a Funding, you are instructing Lead to move money. Lead is the actor: it validates the instruction, submits it to a payment network or its core ledger, and owns the outcome. The object's `status` is **authoritative** — it tells you what has actually happened to real money, and only Lead's systems change it. **Reporting APIs tell Lead something that happened in *your* systems.** For the products your customers hold, **you are the ledger of record**, not Lead. Your platform decided the underwriting outcome, opened the account, issued the card, posted the fee. Lead is your regulator-facing partner bank, and it needs an accurate, timely picture of that activity for compliance oversight — so you report it, through the Entity, Applications, Accounts, and Cards APIs, and through the daily Balance and Transaction files. Here the object's `status` is **declarative** — it reflects what you told Lead is true in your ledger. ## **Why the distinction predicts API behavior** **Webhooks exist where Lead knows something you don't.** Payment rails emit webhooks `ach.posted`, `wire.rejected`, `instant_payment.counterparty_status_updated`, `funding.posted`) because the state lives on Lead's side and in the payment networks — Lead is telling you what happened. Reporting objects generally don't emit webhooks for lifecycle changes, because *you* made the change; there is nothing Lead knows that you don't. **"Terminal" means different things.** On an execution object, a terminal status describes reality: a `returned` ACH was returned; that cannot un-happen. On a reporting object, a terminal status describes *your report* — and reports can be wrong. This is why, for example, a Card reported as `closed` can be corrected back to `active` through the API: the correction isn't reopening a card, it's fixing an inaccurate report so Lead's picture matches your ledger. If a rule on a reporting API looks strange, re-read it as "keep Lead's copy accurate" and it usually makes sense. **Mistakes have different blast radii.** A duplicate execution call risks moving money twice — which is why every write endpoint requires an `Idempotency-Key`, and why you should treat idempotency on payment rails as non-negotiable. A duplicate or erroneous report corrupts Lead's picture of your ledger — no money moves, but your compliance reporting is now wrong, and correcting it is on you. **Timeliness obligations differ.** Execution is on-demand: you call when you want money to move. Reporting is an obligation with a clock: Lead needs your customer activity on a defined cadence whether or not anything interesting happened. ## **Where each API sits** | **API / workflow** | **Contract** | **Status is…** | **Lifecycle webhooks** | | :- | :- | :- | :- | | ACH, Wires, Instant Payments, Internal Transfers, Blockchain Payments | Execution | Authoritative | Yes — see [Webhooks & Events](/api-integrations/using-the-api/webhooks) | | Funding (lending) | Execution | Authoritative | Yes — see [Webhooks & Events](/api-integrations/using-the-api/webhooks) | | Entity | Reporting — you attest your customer's identity data and screening results | Declarative | None | | Applications | Reporting — you submit the terminal underwriting decision your platform reached | Declarative | None | | Accounts | Reporting — reports your end-customer account data to Lead for compliance oversight | Declarative | None | | Cards | Reporting — you notify Lead of cards created with your issuer processor | Declarative | None | | Subledger Balance + daily Balance/Transaction files | Reporting | Declarative | None | | Account Numbers, Originators | **Platform configuration** — a third, smaller category: you provision real Lead-side infrastructure (routable numbers, origination parameters). Lead executes the provisioning; you own the lifecycle. | Authoritative | Mostly synchronous — see the Account Number rows of [Webhooks & Events](/api-integrations/using-the-api/webhooks) | ## **One more consequence: which numbers are "real"** Because you are the ledger of record for customer products, the balance Lead holds for a customer product is a *reported* figure, reconciled against actual money movement on the core accounts Lead operates (your FBO and operating accounts). When you're debugging "where is the money," the execution objects and the core-account reports are the ground truth of movement; the reporting objects are the ground truth of *attribution*. The [Object Model](/core-concepts/platform/object-model) page describes how the two surfaces connect. # Glossary Source: https://docs.lead.bank/core-concepts/platform/glossary Definitions for Lead-specific terms — Entity, Account, FBO, RFI, TAM, and more — plus common banking and payments terms used throughout this documentation. [A](/core-concepts/platform/glossary#a) • [B](/core-concepts/platform/glossary#b) • [C](/core-concepts/platform/glossary#c) • [E](/core-concepts/platform/glossary#e) • [F](/core-concepts/platform/glossary#f) • [I](/core-concepts/platform/glossary#i) • [K](/core-concepts/platform/glossary#k) • [L](/core-concepts/platform/glossary#l) • [N](/core-concepts/platform/glossary#n) • [O](/core-concepts/platform/glossary#o) • [P](/core-concepts/platform/glossary#p) • [R](/core-concepts/platform/glossary#r) • [S](/core-concepts/platform/glossary#s) • [T](/core-concepts/platform/glossary#t) • [W](/core-concepts/platform/glossary#w) ## A **Account**: A Lead object that represents a deposit or credit product for a customer. Every Account belongs to an Entity and is the parent of one or more Account Numbers and Balances. Identified by the account\_ prefix. See [Object Model](/core-concepts/platform/object-model). **Account Holder**: An Entity role that grants full control and legal responsibility for an Account. Required before an Account Number can be created or activated for a customer. See [Entity Roles](/products/entity/roles). **Account Number**: A Lead object that represents a routing and account number pair assigned to a customer. Used to send and receive payments on external rails. Identified by the acct\_num\_ prefix. See [Object Model](/core-concepts/platform/object-model). **ACH (Automated Clearing House)**: A batch-payment network operated by Nacha. Lead supports all three same-day windows and all six next-day windows. See [Money Movement](/core-concepts/platform/money-movement). **Authorized Signer**: An Entity role for an individual authorized to sign on behalf of an Account Holder, typically a control person or beneficial owner of a business. No legal responsibility for the account. See [Entity Roles](/products/entity/roles). **Authorized User**: An Entity role for an individual with restricted access to an account, such as a cardholder on a business account. The lightest data requirements of the four roles. See [Entity Roles](/products/entity/roles). ## B **Balance**: A Lead object that tracks the financial position of an Account. Types include current, available, and subledger. See [Object Model](/core-concepts/platform/object-model). **Beneficial Owner**: An individual who owns or controls 25% or more of a business entity. Lead requires beneficial owner data for business Account Holders as part of KYC. Data requirements match those of the Authorized Signer role. ## C **Charge-Off**: The accounting treatment for a loan or balance written off as a loss due to non-payment or fraud. In Lead's reporting, a charged-off balance is reflected in `charge_off_balance` on the Balances file. The associated Account typically moves to status: `closed` with `status_reason: charged_off`. See [Balances Schema](/file-reference/balances-and-transactions/balances-schema). **CTR (Currency Transaction Report)**: A regulatory filing required for cash transactions exceeding \$10,000 in a single day. Filed by Lead on behalf of the program. ## E **Eligibility**: Lead's computed answer to which relationships an entity's current data qualifies it for: `account_holder`, `minor_account_holder`, `authorized_signer`, and `authorized_user`. Returned as `eligibility` on Entity v2, where it replaces `role_details`. See [Entity Eligibility](/v2/products/entity/eligibility). **Entity**: A Lead object that represents a person or business in your program. The root object in Lead's hierarchy — every Account, Account Number, and transaction traces back to an Entity. Identified by the `entity_ prefix`. See [Object Model](/core-concepts/platform/object-model). ## F **FBO (For Benefit Of)**: A bank account structure where Lead holds funds on behalf of your customers. Your program has a single FBO account; individual customer balances are tracked as sub-balances within it. Lead provides your `account_id` during onboarding. **FedNow**: The Federal Reserve's instant payment network. Lead currently supports FedNow for sending and receiving instant payments. See [Money Movement](/core-concepts/platform/money-movement). **FedWire**: The Federal Reserve's wire transfer network. Used for domestic wire transfers. Lead has a direct connection to FedWire. See [Money Movement](/core-concepts/platform/money-movement). ## I **IAT (International ACH Transaction)**: An ACH SEC code used for cross-border entries. Requires additional originator and receiver details via the `iat_details` field. See [ACH](/products/ach/overview). **IM (Implementation Manager)**: Your primary Lead contact from kickoff through go-live. Owns timelines, milestones, and cross-functional coordination. See [Programs and Partners](/core-concepts/platform/programs-and-partners). **Internal Transfer**: A Lead rail for moving funds instantly between accounts held at Lead. Does not touch any external network. Identified by the `xfer_ prefix`. See [Money Movement](/core-concepts/platform/money-movement). ## K **KYC (Know Your Customer)**: The process of verifying a customer's identity. You perform KYC and attest the result on the entity (`kyc_details`); Lead validates the attestation. A passed result is required for the Account Holder, Minor Account Holder, and Authorized Signer roles. ## L **Lead Entity**: The read-only entity that represents Lead Bank as the holder of the core accounts Lead holds, like your FBO. Lead sets it up during onboarding. Entity type `lead`, available on Entity v2. See [Entity v2](/v2/products/entity/overview). ## N **Nacha**: The organization that governs the ACH network and sets operating rules for ACH participants, including SEC codes, return windows, and same-day limits. **NAICS Code**: A 6-digit North American Industry Classification System code used to identify a business entity's industry. Required when creating a business or sole proprietorship Entity. Lead validates that the value is a full 6-digit code — 2-digit sector codes are not accepted. See [Entity](/products/entity/overview). ## O **ODFI (Originating Depository Financial Institution)**: The bank that initiates an ACH entry on behalf of the originator. Lead acts as the ODFI for outgoing ACH entries your program originates. **OFAC (Office of Foreign Assets Control)**: A U.S. Treasury division that administers sanctions programs. You screen entities against OFAC lists and attest the result on the entity (`ofac_details`). **Originator**: A Lead object that represents an ACH Company ID used to identify your program on the ACH network. A single program can have multiple Originators. See [Originators](/products/ach/originators). ## P **Partner**: Your company — the fintech that has signed an agreement with Lead and is integrating against Lead's platform. See [Programs and Partners](/core-concepts/platform/programs-and-partners). **Partner Entity**: A read-only entity that represents your company as the holder of the core accounts your company holds, like an operating account. Lead sets it up during onboarding, and a program can have more than one. Entity type `partner`, available on Entity v2. See [Entity v2](/v2/products/entity/overview). **Partner Site**: The Lead portal at [partners.lead.bank](http://partners.lead.bank) where operational and compliance resources live, including SLAs, the risk management framework, program policies, and data requirements. Access is provisioned by your IM during kickoff. **Program**: A specific product you offer to your end customers under your Lead relationship. Each program has its own credentials, rails configuration, and reconciliation files. See Programs and Partners. ## R **RDFI (Receiving Depository Financial Institution)**: The bank that receives an ACH entry on behalf of the receiver. When your customers receive an incoming ACH, Lead acts as the RDFI. **RFI (Request for Information)**: A compliance request Lead issues when additional information is needed about a customer or transaction. Delivered via Slack to your program's compliance contact. **RTP (Real-Time Payments)**: The Clearing House's instant payment network. Support for RTP is coming soon to Lead. See [Money Movement](/core-concepts/platform/money-movement). ## S **SAR (Suspicious Activity Report)**: A regulatory filing required when a financial institution detects potentially illegal activity. Filed by Lead on behalf of the program. **SEC Code**: A three-letter Nacha code that classifies an ACH entry by type and authorization method. Examples include PPD (consumer credits/debits), CCD (business credits/debits), WEB (internet-initiated), and IAT (international). **Subledger Balance**: A Lead Balance type used for lending products to track principal, interest, fees, and repayment schedules at the loan level. See [Object Model](/core-concepts/platform/object-model). **SWIFT**: The messaging network used for international wire transfers. Lead uses SWIFT for outgoing USD international wires. See Money Movement. ## T **TAM (Technical Account Manager)**: Your technical Lead contact for sandbox configuration, credential provisioning, SFTP setup, and integration support. Post-launch primary contact. See [Programs and Partners](/core-concepts/platform/programs-and-partners). **Transaction**: A Lead object that represents a posted or non-posted financial event on an Account. Identified by the `txn_ prefix`. See [Object Model](/core-concepts/platform/object-model). ## W **Webhook**: An HTTP callback Lead sends to your endpoint when an event occurs, such as a payment status change or an RFI. Used to build real-time, event-driven integrations. See [Webhooks](/api-integrations/using-the-api/webhooks). # Integration Surfaces by Product Source: https://docs.lead.bank/core-concepts/platform/integration-surfaces-by-product The current integration surface for every Lead product and workflow — which run on APIs, which still run on SFTP files, and where files remain today. Lead's platform is completing a transition to a fully API-based integration model. This page describes the **recommended integration path for new partners**: how each product and workflow is integrated today. Where an API exists, it is the path we support and recommend. A blank cell means that column does not apply to that row. See the [Platform Evolution](/core-concepts/platform/platform-evolution) page for details on the upcoming changes. | Product / workflow | Create & manage | Move money | Reporting & reconciliation | | - | - | - | - | | **BUILD ON LEAD** | | | | | Deposit accounts | `API` Accounts API | `API` ACH, Wire, Instant Payments, and Internal Transfer APIs | `File` Daily Balances and Transactions files | | Credit & lending accounts | `API` Applications API, Accounts API, Create Subledger Balance API, Funding API | `API` Funding API to originate; disburse over any payment-rail API | `File` Daily Balance and Transactions files | | Cards | `API` Cards API `Beta` | Card transactions settle through your issuer processor and network settlement, not a Lead payment surface. | `File` Daily Transactions file from Lead, plus settlement files from the card networks | | Receivables purchase (daily sale) | | `File` Sales Request / Response exchange over SFTP. API planned — see [Platform Evolution](/core-concepts/platform/platform-evolution). | | | **MOVE MONEY** | | | | | ACH | `API` Originators API | `API` ACH API | `File` ACH Cash Recon report | | Wires (domestic and USD international) | | `API` Wires API. A version migration is in progress. | | | Instant Payments | | `API` Instant Payments API. FedNow is live. | | | Internal Transfers | | `API` Internal Transfer API | | | Blockchain Payments | | `API` Blockchain Payments API `Beta` | | | Checks | | `File` X9 file exchange, the industry clearing format for check images | `File` X9 files | | **SUPPORTING OBJECTS** | | | | | Customers (Entities) | `API` Entity API | | | | Account Numbers | `API` Account Number API | | | | Originators (ACH origination parameters) | `API` Originators API | | | | **WHAT YOU REPORT TO LEAD** | | | | | Balances and transactions (your customers' ledger) | | | `File` Daily Balances, Transactions, and Non-Posted Transactions files over SFTP | | Receivables purchase (daily sale) | | `File` Sales Response file confirming each day's purchase; settlement from your operating account. `API` Sale API arriving — see Platform Evolution | | | Compliance documents | | | `File` SFTP delivery. Also referenced in Accounts and Applications payloads. | | **WHAT LEAD SENDS YOU** | | | | | Daily reports | | | `File` Daily Balance, Daily Activity, ACH Cash Reconciliation, Platform Reconciliation, network settlement reports, and the daily Sales Request — delivered over SFTP | ### Where Files Remain Today Everything you build is created over APIs, and every payment rail except checks is an API. Files remain in three places: **Daily reporting to and from Lead.** Daily balances, transactions, and the daily report set travel over SFTP. This is one pipeline, shared across every product, and it is the same whether you are building deposits, lending, or cards. **The receivables sale (API planned).** Lending and card-credit programs confirm each day's receivables purchase through the Sales Request/Response exchange today. A Sale API is in flight ([Platform Evolution](/core-concepts/platform/platform-evolution)); the daily cycle is unchanged across the transition. **Industry clearing formats.** X9 for checks and card network settlement files are how those networks work. They are not part of the API transition. If you are scoping file infrastructure for a new integration, the answer is one SFTP consumer for the daily file set, plus X9 only if you are doing checks. # Money Movement Source: https://docs.lead.bank/core-concepts/platform/money-movement Compare Lead's five payment rails — ACH, Wire, Instant Payments, Internal Transfer, and Blockchain Payments — and review the daily processing windows for each one, plus where checks fit. Lead supports five payment rails. Each rail has different settlement timing, reversibility, direction support, and availability. This page helps you choose the right rail for your use case. For implementation details, see the linked Build pages. ## **Rails at a Glance** | **Rail** | **Directions** | **Settlement** | **Reversible** | **Availability** | **Status** | | :- | :- | :- | :- | :- | :- | | ACH | Send, Receive | Same-day or next-day | Yes, within window | Business days | Live | | Wire | Send, Receive | Same-day | No | Business days | Live | | Instant Payments | Send, Receive | Seconds | No | 24/7/365 | FedNow live; RTP coming in Q4 2026 | | Internal Transfer | Send | Immediate | No | 24/7/365 | Live | | Blockchain Payments | Send, Receive | Instant | No | 24/7/365 | Beta | Checks are also supported as an execution flow, exchanged in the industry-standard X9 file format rather than over an API — see [Checks at Lead](/products/checks/overview). ## **ACH** ACH is a batch-processed rail operated by the Automated Clearing House network. Entries are submitted in files and settled on a same-day or next-day basis during business hours. **Use ACH when:** you need a low-cost, high-volume rail for recurring payments, payroll, loan disbursements, or consumer-initiated transfers where same-day or next-day settlement is acceptable. Lead supports all standard SEC codes, including PPD, CCD, WEB, and IAT for cross-border entries. ACH entries can be canceled before the cutoff and returned within the standard Nacha window. Lead supports all three settlement windows: same-day morning, same-day afternoon, and next-day. → [See ACH](/products/ach/overview) ## **Wire** Wire transfers move funds over FedWire (domestic) or SWIFT (international USD). Wires settle same-day when submitted within Lead's cutoff windows and are irrevocable once sent. **Use Wire when:** you need same-day finality, are sending large-dollar amounts, or are moving funds internationally in USD. → [See Wire](/products/wire/overview) ## **Instant Payments** Instant Payments settle in seconds, are available around the clock, and are final and irrevocable. Instant Payments currently supports FedNow and will support RTP in Q4 2026. In the Lead API, both networks use the same `instant_payment` object — you do not need to specify the underlying rail. **Use Instant Payments when:** your customers need immediate fund availability at any hour, including nights, weekends, and holidays. Common use cases include earned wage access, insurance claims disbursements, and gig economy payouts. Because instant payments are irrevocable, you cannot reverse or cancel a sent payment. If a payment is sent in error, use a return request to attempt recovery from the receiver. → [See Instant Payments](/products/instant-payments/overview) ## **Internal Transfer** Internal Transfers move funds between accounts held at Lead instantly and at no cost. They do not touch any external network and settle immediately, 24/7. **Use Internal Transfer when:** you need to move funds between your FBO account and a customer account, or between two accounts within your program, without going through an external rail. > [!TIP] > > Internal Transfers are outbound only — you initiate the move from the source account. They are irrevocable once submitted. → [See Internal Transfer](/products/internal-transfer/overview) ## **Blockchain Payments** Blockchain Payments is a beta feature that enables money movement between Lead deposit accounts and blockchain rails. It supports two primary flows: * **USD to stablecoin payout:** Send USD from a Lead account to a blockchain wallet address (stablecoin) * **USD to foreign currency:** Send USD out over blockchain rails and have it settle in a foreign currency at the destination (the "stablecoin sandwich") **Use Blockchain Payments when:** your program pays out to blockchain wallets, or needs to move funds internationally in foreign currency over blockchain rails. > [!TIP] > > Because this feature is in beta, reach out to your Technical Account Manager before building against it. → [See Blockchain Payments](/products/blockchain-payments/overview) ## **Choosing a Rail** A few common decision points: **Speed vs. Cost**: Internal Transfers and Instant Payments are the fastest options. ACH is the lowest cost. Wire is the standard choice when same-day finality is needed for large-dollar or international payments. **Reversibility**: Only ACH entries can be returned within the Nacha window. Wires, Instant Payments, Internal Transfers, and Blockchain Payments are irrevocable once sent. **Hours**: Instant Payments and Internal Transfers are available 24/7. ACH and Wire are subject to Lead's daily cutoff windows.  **International**: Wire (USD international via SWIFT) and Blockchain Payments are the options for cross-border movement. ACH supports cross-border entries via the IAT SEC code for specific use cases. ## **Processing Windows** ### **ACH** ACH runs on business days only. Lead supports all three same-day ACH windows and all six next-day ACH windows. Submissions after a Lead cutoff are queued for the next available window — there is no best-effort processing. ### **Same-Day ACH** | **Lead Cutoff (CT)** | **Fed Window Deadline (CT)** | **Settlement at Counterparty** | | :- | :- | :- | | 9:00 AM | 9:30 AM | 12:00 PM same business day | | 1:15 PM | 1:45 PM | 4:00 PM same business day | | 2:00 PM | 3:45 PM | 5:00 PM same business day | ### **Next-Day ACH** | **Lead Cutoff (CT)** | **Fed Window Deadline (CT)** | **Settlement at Counterparty** | | :- | :- | :- | | 9:00 AM | 9:30 AM | 7:30 AM next business day | | 1:15 PM | 1:45 PM | 7:30 AM next business day | | 3:15 PM | 3:45 PM | 7:30 AM next business day | | 6:30 PM | 7:00 PM | 7:30 AM next business day | | 9:15 PM | 9:45 PM | 7:30 AM next business day | | 10:00 PM | 1:15 AM | 7:30 AM next business day | > [!TIP] > > The same-day Nacha limit is \$1,000,000 per entry. Entries above that threshold must use `delivery_type: next_business_day`. ### **Wire** Domestic wires (FedWire) settle same-day when submitted within Lead's wire cutoff window. International wires (SWIFT) follow the same submission window but settlement timing at the receiving institution varies by correspondent. Contact your TAM for current wire cutoff times. Wires are irrevocable once sent. To attempt recovery of a wire sent in error, use the [Return Requests API](/products/wire/return-requests). ### **Instant Payments** Instant payments are available 24/7/365 and are not subject to business-day or cutoff constraints. Settlement completes in approximately 20 seconds. Instant payments are irrevocable once sent. ### **Internal Transfers** Internal Transfers settle immediately and are available 24/7/365. They are not subject to cutoffs or business-day constraints. ## **File Deadlines** If your integration includes file-based flows, Lead expects files by **6:00 a.m. CT** on the business day following the date of the activity being reported. Files received after this deadline may not be processed in that day's cycle. See [Exchanging Files with Lead](/file-reference/delivery/overview) for full file naming. # Object Model Source: https://docs.lead.bank/core-concepts/platform/object-model The objects every Lead program is built from — and how they fit together today. Lead represents programs with a small vocabulary of objects: **Entity**, **Application,** **Account**, **Account Number**, **Balance**, and **Transaction** — plus two that apply only to customer products. The same names show up across the API, file schemas, webhook events, and reports, so learning them up front makes the rest of the documentation read more naturally. This is one of the first pages to read carefully if you're new to Lead. The single most important idea is that these objects live on one of two surfaces — **core** and **user** — and the two work quite differently today. Rather than define each object once and qualify it per surface, this page walks through each surface on its own. Most of it is about how things work today; a short section at the end flags [what's changing](/core-concepts/platform/platform-evolution#what’s-changing). ## Two Surfaces Most objects sit on one of two surfaces, and the cleanest way to hold the distinction is: * **Core Surface**: The accounts you use to *operate your program*. Lead opens these during onboarding and manages their lifecycle; you read them but don't open or close them yourself. * **User Surface**: The financial *products your customers hold*. You create these, manage their lifecycle, and report activity against them. > [!TIP] > > Your **user accounts are the per-customer view**, and your **core accounts are where the money actually sits**. Most programs use both, and the rest of this page explains them one at a time. ## Entity (shared) A legal person or organization — every account on either surface is held by one. You create entities for your customers with the [Entity API](/products/entity/overview) (three subtypes: `individual`, `business`, and `sole_prop`), and Lead creates an entity in your name for your program. The Entity is where Lead anchors KYC, OFAC screening, RFI handling, and any partner-supplied risk score. * **Identifier:** `entity_`, returned on creation. You can also reference an Entity by your own `client_customer_id`. * **Roles:** An Entity holds an Account in one or more [roles](/products/entity/roles) — `account_holder`, `minor_account_holder`, `authorized_signer`, or `authorized_user` — which govern what it can do on the Account. * **Lifecycle:** Created and updated; some updates re-trigger KYC. Entities stay attached to any Account for the life of the relationship and can't be deleted. ## Core Surface The foundational accounts you use to operate your program. Lead opens them for you during onboarding and manages their lifecycle; you read them through the online banking UI and the daily reports (API access Coming Soon), but you don't open or close them yourself. They come in three kinds: * **FBOs**: Pooled "For Benefit Of" accounts that hold your customers' funds in aggregate. * **Operating Accounts**: Our day-to-day DDAs for operating, revenue, reserve, settlement, network settlement, and so on. * **Shadow Accounts**: Secondary sweep or placement accounts, such as IntraFi ICS. ### Account (core) On the core surface, an **Account and its balance are the same object** — there is no separate core Balance. A core Account is one of your FBOs, operating DDAs, or shadow accounts, and it carries the balance. You read the balance from the [Daily Balance Report](/file-reference/reports/daily-balance) or the online banking UI. * **Identifier:** `account_` * **Held by:** Your Lead or partner entity * **Lifecycle:** Opened and managed by Lead ### Account Number The routing number and account number pair that lets money reach an account on Lead's payment rails. A single core account can have many — for example, one for each end customer whose funds are pooled in an FBO. Account Numbers hang off core accounts. Even when you assign one to an individual customer, it attaches to the core account — the customer is carried on the account number's `entity_id` — so an inbound payment lands on the core account first and is attributed to the customer from there. * **Today:** An Account Number points to a core Account (via `account_id`). * **Lifecycle:** Unassigned → active ↔ inactive → canceled. canceled is terminal; Account Numbers are never reused. See [Account Number Statuses](/products/account-number/statuses). * **Controls:** Per-rail allow/block rules for incoming and outgoing payments are set at the Account Number level. See [Controls](/products/account-number/controls). > [!TIP] > > All of Lead's money-movement APIs — ACH, wires, instant payments, and internal transfers — are indexed off the Account Number. You originate a payment by referencing an `account_number_id`, and Lead resolves the account it settles against. ### Transaction (core) Debits and credits on a core account are generated by Lead — you don't report them. They appear in the [Daily Activity Report](/file-reference/reports/daily-activity) and the online banking UI. ### Core Accounts (today) ```text theme={null} Entity (Lead or partner) └── Account (account + balance combined) └── Account Number (routable payment address) ``` ## User Surface The financial products your customers hold — deposit and credit. You create them (via API or file), manage their lifecycle, and report their activity to Lead. Two of the objects here, **Application** and **Card**, exist only on the user surface — there is no core-side equivalent. The objects below appear roughly in the order you'd use them. ### Application For credit and lending products only (not deposit products). When your underwriting reaches a final decision, you submit it to the [Applications API](/products/applications/overview) — `approved`, `declined`, or `canceled` — which Lead uses to meet Reg B and fair-lending obligations. An approved Application is required to open a credit or lending Account, so the order is **Entity → Application → Account**. * **Identifier:** `application_` * **Status:** Terminal only — `approved`, `declined`, or `canceled`. There is no in-progress state, and all outcomes must be reported. ### Account A lightweight container for a customer's product. It holds the entity relationships and sets the product type — `deposit` or `credit` — while the money itself lives on a **Balance** beneath it. * **Identifier:** `account_` * **Lifecycle:** `inactive` ↔ `active` → `closed` (closed is terminal) * **Holders:** An Account can be held by more than one Entity — joint accounts, or business accounts with several signers. ### Balance How much money is on a user account at a point in time — its own object on the user surface. Two types: * **Deposit**: Checking or savings style accounts, with or without debit cards. * **Credit**: Term loans or lines of credit. You report end-of-day balances to Lead for reconciliation. ### Card A card issued on a customer account — a debit card on a deposit account, or the card itself for a credit or charge product. You report cards to Lead in the card file, each tied to an account and entity and keyed by your own `client_card_id`. * **Type:** Virtual or physical; `consumer`, `commercial`, `hsa`, or `fsa` * **Status:** `active`, `inactive`, `closed`, or `expired` (closed is terminal) * Card transactions reference the Card ### Transaction A debit or credit posted to a user Balance, which you report to Lead via a daily batch file, keyed by your own `client_transaction_id` (API access Coming Soon) * **Type:** Indicates how the money moved — see [Transaction Types](/products/balances-and-transactions/transaction-types) for the full enumeration. * **Posted vs. non-posted:** Non-posted (pending) Transactions may not affect available balance the same way posted ones do; posted Transactions are final on the ledger. ### User Accounts (today) ```text theme={null} Entity (individual / business / sole_prop) └── Account             (for credit, opened from an approved Application)     ├── Card            (if the product issues cards)     └── Balance         (deposit or credit)         └── Transaction ``` ## How the Two Surfaces Connect A single product ties both surfaces together. Take a checking product: each end customer is an Entity, and you open a user Account for them that carries a Balance. Their money physically pools in your FBO — a core Account Lead set up for you. You give the customer an Account Number for inbound ACH; today that number hangs off the core FBO even though it's assigned to the customer. Each payment or fee posts as a Transaction on the user Balance, you report that activity to Lead, and Lead reflects the matching money movement on the FBO. > [!NOTE] > > **Key Takeaway** > > Today, every Account Number hangs off the **core** Account — even the ones you assign to individual customers. That Account Number → Account linkage is the single most important thing to know about today's model, and it's the main thing changing. # Platform Evolution Source: https://docs.lead.bank/core-concepts/platform/platform-evolution Lead's two connected platform changes — file-to-API migration and the unified object model — what's changing, what isn't, and how to prepare your integration today. Lead is making two connected changes to how you integrate: moving every integration workflow from files to APIs, and unifying the platform's object model so the same concepts work the same way across every product. This page is where we describe those changes. Every other page in these docs describes the platform as it works today, and [Integration Surfaces by Product](/core-concepts/platform/integration-surfaces-by-product) states, product by product, exactly what that is. ## **Why the Platform Works the Way It Does Today** Lead's platform has two integration surfaces. The **core surface** covers the accounts Lead operates for your program. The **user surface** covers the products your customers hold. Lead built them at different times for different purposes, so the same concept can take a different shape depending on which surface you work with. That difference is real, and the upcoming unified object model closes it. ## **What's Changing** **From files to APIs.** Some workflows run on APIs today and some run on daily SFTP files. [Integration Surfaces by Product](/core-concepts/platform/integration-surfaces-by-product) shows the current state for each product. Over time, every file-based workflow gains an API equivalent, and new programs integrate entirely over APIs. **A unified object model.** Both surfaces move to the same shape. Three changes matter most: * **Balances and Transactions become API objects on the core surface.** You read a core balance or transaction directly from the API instead of only from daily reports. This change closes the file dependency described in [Integration Surfaces by Product](/core-concepts/platform/integration-surfaces-by-product). * **Account Numbers point to a Balance, not an Account.** A customer's Account Number attaches to that customer's balance directly, which removes the routing ambiguity that exists when an account holds more than one balance. * **IDs gain typed prefixes.** Typed IDs, such as `core_account_*` and `user_account_*`, replace the single `account_id` used across both surfaces today, so an object's ID indicates which surface it belongs to. Treat IDs as opaque strings and do not parse meaning out of them. * **The daily receivables sale becomes an API.** Credit and lending programs purchase each day's receivables through a sale object and webhooks instead of the Sales Request / Response file exchange — same daily cycle, same settlement amounts, structured and same-day. ## **What Is Not Changing** * The APIs and file feeds you use today keep working. * You do not need to re-integrate from scratch. * Nothing requires action from you until your program's migration window opens, and your Lead team contacts you before it does. ## **Preparing Your Integration Today** Do not build against the new model. Lead publishes API contracts only when they are available to test. The choices you make now determine how much work the transition takes later, and each item below is good practice today regardless. **Treat IDs as opaque strings.** Store them exactly as Lead returns them. Do not parse them, pattern-match on them, or derive meaning from their format beyond string, unique, and prefixed by object type. **Store IDs in a string column with generous length limits.** Typed prefixes make IDs longer than they are today. **Model balances as their own entity.** Do not treat a balance as a field on an account. An account can hold more than one balance, and Account Numbers attach to a balance rather than an account. Integrations that already model balances separately are well-prepared to absorb this change. **Record which surface an object comes from.** A single `account_id` shape covers both the core and user surfaces today, and typed IDs make the distinction explicit. Keep that distinction in your own data now and you avoid reconstructing it later. **Key reconciliation on object IDs, not file rows.** Balances and transactions arrive as daily files today and become API objects later. Reconciliation logic keyed to a filename, line position, or delivery date needs a rewrite at the transition. Logic keyed to the object's own ID does not. ## **How Changes Reach You** **Lead announces every change before it lands.** We announce new APIs and required changes in [Upcoming Changes](/upcoming-changes), following the lifecycle you already know: Announced, Sandbox Available, Enforcement Soon, and Released. Nothing requires action from you without advance notice, and sandbox access precedes enforcement. **Migration happens by cohort.** When your program's migration window opens, your Lead team contacts you with a specific plan. **Timing.** New programs begin integrating fully over APIs starting late 2026. Existing programs migrate in cohorts through 2027; your Lead team schedules yours with you. Concrete steps are announced in [Upcoming Changes](/upcoming-changes) as each becomes available to test. # Programs and Partners Source: https://docs.lead.bank/core-concepts/platform/programs-and-partners Understand the difference between a Lead partner and a program, why credentials are scoped per program, and who your Lead team contacts are. "Partner" and "program" are two terms you'll see throughout Lead's documentation. They're related but not interchangeable, and the distinction matters once you have more than one product live. ### **Partner** A Partner is your company — the fintech that has signed an agreement with Lead and is integrating against Lead's platform. A partner has one set of legal contracts, one due diligence file, one production tenant, and one Implementation Manager and Technical Account Manager assigned by Lead. ### **Program** A Program is a specific product or set of products you offer to your end customers under your Lead relationship. A single partner can run multiple programs — for example, a deposit account program and a separate consumer lending program — each with their own product type, target customers, and operational parameters. Each program has its own: * Product type (deposit, credit, lending, cards) and money-movement rails enabled * API credentials and SFTP folder, isolating data and authorization between programs * Risk parameters, transaction limits, and IP allowlist * Compliance configuration — KYC posture, OFAC screening cadence, RFI handling * Reporting and reconciliation files, delivered separately per program ### **Why the Separation Matters** **Credentials are scoped to a program.** A token issued for your deposit program cannot call lending endpoints. Treat each program as its own integration. **Reconciliation files are per-program.** If you run multiple programs, expect a separate Daily Activity, Daily Balance, and ACH Cash Reconciliation report for each. **Go-live is per-program.** A partner with two programs goes through sandbox testing, production testing, and go-live separately for each. The contracting workstream is shared; the integration and risk-approval workstreams are not. ### **Your Lead Team** Two Lead roles are your primary contacts throughout the relationship. **Implementation Manager (IM)**: Your lead point of contact from kickoff through go-live. Owns timelines, milestones, due diligence coordination, and cross-functional alignment across Product, Compliance, Legal, and Finance. **Technical Account Manager (TAM)**: Your technical point of contact. Handles sandbox configuration, credential provisioning, SFTP setup, IP allowlist changes, and integration support. Post-launch, your TAM becomes your primary ongoing contact. ### **Where Partner-Level Resources Live** **Technical documentation:** APIs, file schemas, integration guides — lives here on this site. **Operational and compliance resources:** SLAs, the risk management framework, program policies, due diligence materials, and data requirements — live on the Partner Site at [partners.lead.bank](http://partners.lead.bank). Your Implementation Manager provisions access during kickoff. # Versioning and Backwards Compatibility Source: https://docs.lead.bank/core-concepts/platform/versioning-and-backwards-compatibility How Lead versions its APIs, what counts as a breaking change, and the commitments Lead makes about notice, sandbox availability, and migration windows. ## **How Lead Versions Its APIs** Lead versions **per resource**, in the URL path. Different resources sit at different versions because they ship and evolve independently — the version prefix tells you which contract you're on, and nothing else. The current generally available version of every resource, and the next version where one is in progress: | **Resource** | **Current GA path prefix** | **Next version path prefix** | | :- | :- | :- | | Account Numbers | `/v1` | — | | ACH | `/v1` | — | | Applications | `/v0` | `/v2` (currently preview, targeting Q4 2026 beta) | | Blockchain Payments | `/v0` | — | | Cards | `/v0` | — | | Core Accounts | — | `/v2` (beta, available now) | | Core Balances | — | `/v2` (beta, available now) | | Core Transactions | — | `/v2` (beta, available now) | | Entities | `/v0` | `/v2` (currently preview, targeting Q4 2026 beta) | | Events | `/v1` | — | | Files | — | `/v2` (currently preview, targeting Q4 2026 beta) | | Fundings | `/v0` | `/v2` (currently preview, targeting Q4 2026 beta) | | Instant Payments | `/v1` | — | | Internal Transfers | `/v1` | — | | Lending disbursements (legacy) | `/v0` | — | | OAuth | `/v1` | — | | Originators | `/v0` | — | | Receivable Sales | — | `/v2` (currently preview, targeting Q4 2026 beta) | | Receivables | — | `/v2` (currently preview, targeting Q4 2026 beta) | | User Accounts, formerly known as Accounts | `/v0` | `/v2` (currently preview, targeting Q4 2026 beta) | | User Credit Balances, formerly known as Subledger Balances | `/v0` | `/v2` (currently preview, targeting Q4 2026 beta) | | User Credit Transactions | — | `/v2` (currently preview, targeting Q4 2026 beta) | | Wires | `/v1` | `/v2` (currently preview; dates to be announced in the [Wires API V2 Migration Guide](/products/wire/v2-migration)) | Keep using the current GA version until the next version is available. Lead announces migration timelines and sunset dates in [Upcoming Changes](/upcoming-changes). Sandbox simulators live under the corresponding version (`/v1/simulate/…`, `/v2/simulate/…`, plus `/v0/fundings/{id}/advance` and `/v0/simulate/lending/disbursements/{id}/advance`). A lower number does not mean less stable: `/v0` resources are production APIs. A resource's version only increments when Lead must make a breaking change to it — as with Wires V2, which supports Fedwire's ISO 20022 mandates. ## **How We Make Changes** **Additive changes are not breaking.** Lead may, without a version change: add new API endpoints; add new optional request fields; add new response fields; add new values to enums that are documented as extensible; add new event types; increase documented limits. Build your integration to tolerate unknown response fields and unknown event types. **Major breaking changes get a new version, notice, and sandbox time.** Removing or renaming fields, changing types or semantics, or removing endpoints happens only in a new resource version. Lead announces it in [Upcoming Changes](/upcoming-changes) with a migration guide and makes it available in sandbox before you need to move.  **Deprecations follow the same lifecycle.** When Lead schedules a version for retirement, the timeline appears in [Upcoming Changes](/upcoming-changes) (Announced → Sandbox Available → Enforcement Soon → Released) and the old version keeps working until the stated enforcement date.  **Preview APIs are documented before release.** Resources labeled **Preview** are not yet available in sandbox or production and can change before beta. Use their pages to plan an integration, not to build one. When a Preview resource moves to beta, Lead announces it in [Upcoming Changes](/upcoming-changes). It then becomes available to all partners in sandbox, and in production for select programs. **Beta APIs are the exception.** Resources labeled **API — Beta** may change without a version increment. Lead announces these changes in advance, and your Technical Account Manager works with you to implement them. # Program Launch Source: https://docs.lead.bank/get-started/program-launch Follow Lead's five-milestone implementation process from kickoff and funds flow alignment through sandbox testing, production testing, and go-live. Getting a program live at Lead involves three parallel workstreams: * Contracting * Due Diligence * Technical Integration  This page walks through how the process works, who owns what, and what needs to be true before your program can serve real customers. ## Your Lead Team Throughout the process, two Lead roles are your primary contacts. **Program Manager (PM)**: Your lead point of contact from kickoff through go-live. Owns timelines, milestones, due diligence coordination, and cross-functional alignment across Product, Compliance, Legal, and Finance. **Technical Account Manager (TAM)**: Your technical point of contact. Handles sandbox configuration, credential provisioning, SFTP setup, IP allowlist changes, and integration support. Post-launch, your TAM becomes your primary ongoing contact. ## The Three Workstreams Every program launch runs three workstreams in parallel. None of them wait for the others to finish before starting, but each has dependencies that gate what comes next. **Contracting** covers the Program Management Agreement (PMA) and any related legal documents. Lead drafts the PMA and works through it with your team asynchronously. Contracting must be executed before production testing and before go-live. **Due Diligence** covers compliance, risk, and operational review. Due diligence must be complete before go-live — target completion two weeks in advance to allow time for Lead's internal approval process. **Integration** covers the technical build — funds flow alignment, data schema, SFTP setup, API integration, and end-to-end testing. Your Technical Account Manager runs recurring syncs and is your primary point of contact throughout this workstream. > [!NOTE] > > **Additional Program Details** > > SLAs, risk management frameworks, program policies, and due diligence materials live on the Partner Site at [partners.lead.bank](http://partners.lead.bank). Your Program Manager provisions access during kickoff. ## Integration Milestones The integration workstream runs through five milestones, each of which gates the next. **1. Implementation Kickoff** Your first call with Lead's program and technical teams. You align on use cases, money movement, timelines, and due diligence requirements. After kickoff, Lead produces a proposed funds flow for your review and discussion. **2. Funds Flow and Data Schema** You align with Lead on two things: the flow of funds through your program, and the data schema that supports it — which objects come via API, which files come via SFTP, and the field-level schema for each. As part of this milestone, you provide Lead with the transaction event types your program generates. Lead maps these to the Lead schema and confirms alignment before sandbox testing begins. This step is a hard dependency — sandbox testing cannot start until the data schema is agreed on. > [!TIP] > > **Timing Requirement** > > One timing requirement to internalize now: all files submitted to Lead must arrive by 6:00 a.m. CT on T+1 (the next business day). This applies in both sandbox and production. **3. Sandbox Testing** Before sandbox testing begins, Lead completes environment setup. Here is the sequence: 1. You fill out the partner intake form. 2. Lead opens your financial accounts. 3. You send Lead your public SSH keys and webhook destination URL. 4. Lead sends you sandbox API credentials. 5. Lead sets up your SFTP directory and shares access. Once your environment is ready, sandbox testing begins. The goal is to validate data consistency, transaction types, and settlement flows across a representative set of accounts. Expect 1–2 weeks of active testing across multiple rounds. After seven consecutive days of successful tests, you can move to production testing. If you receive an "Account Number not configured to send outgoing originations" error during sandbox, contact your Technical Account Manager — outgoing ACH requires account-level configuration on Lead's side before it can be tested. Both SFTP files and API calls are in scope for sandbox testing: * **SFTP:** Accounts, Balances, Transactions, Non-Posted Transactions, Transaction Updates, Cards (if applicable) * **API:** Entity, Account Number, ACH, Wires, Internal Transfers, Events **4. Production Testing** Production testing begins with your own employees. You validate real money movement, fund flows, card transactions (via your issuing processor, if applicable), and settlements against production infrastructure. Lead requires the same seven consecutive days of successful tests before traffic can ramp to 100%. Expect approximately two weeks of production testing. To begin production testing, the following must be complete: * Partner intake questionnaire submitted and reviewed * Executed agreements in place * Due diligence sufficiently complete for internal employee testing * Partner accounts opened in production **5. Go Live** Your program is approved to serve all end customers. Before go-live, confirm the following are complete: * Full due diligence complete (target two weeks before go-live) * Lead internal risk assessment and approval complete * Production credentials issued and IP allowlist configured Once approved, your Technical Account Manager transitions from active integration support to ongoing post-launch support. # Make Your First Payment API Call Source: https://docs.lead.bank/get-started/quickstart/make-your-first-payment-api-call Authenticate to Lead, create an entity, assign an account number, simulate an incoming ACH credit, and send an outgoing ACH in sandbox. ### Before You Start You will need: * **Sandbox API credentials:** A `client_id` and `client_secret` provided by your Lead Technical Account Manager during kickoff. * **curl:** Installed on macOS by default; `curl --version` should print something. Any HTTP client works. * **Optional:** jq— for cleaner JSON output. Pipe responses through `| jq .` if you have it installed. > [!NOTE] > > **Sandbox Only** > > Every example uses [api.sandbox.lead.bank](http://api.sandbox.lead.bank). The same calls work against [api.lead.bank](http://api.lead.bank) in production once your program is approved for go-live, but you should never run this guide against production credentials. ## Steps 15 minutes We'll go through a simple flow to authenticate against Lead, create an entity, assign an account number, simulate an incoming ACH credit, and send an outgoing ACH. > [accordion] 1: Get an Access Token > > Lead uses OAuth2 client credentials. You exchange your `client_id` and `client_secret` for a short-lived access token (24-hour expiry by default) and pass that token as a Bearer header on every subsequent request. > > Replace `YOUR_CLIENT_ID` and `YOUR_CLIENT_SECRET` with the values from your Technical Account Manager. > > ```text theme={null} > curl -X POST https://api.sandbox.lead.bank/v1/oauth/token \ > -H 'Content-Type: application/json' \ > -d '{ > "grant_type": "client_credentials", > "client_id": "YOUR_CLIENT_ID", > "client_secret": "YOUR_CLIENT_SECRET", > "scope": "entity/read_write ach/read_write account_number/read_write" > }' > ``` > > You should see a response like this: > > ```text theme={null} > { > "access_token": "eyJhbGciOiJSUzI1NiIs...", > "token_type": "Bearer", > "scope": "entity/read_write ach/read_write account_number/read_write", > "expires_in": 86400 > } > ``` > > Save the `access_token` value as a shell variable so the next steps are easy to copy: > > ```text theme={null} > export LEAD_TOKEN="eyJhbGciOiJSUzI1NiIs..." > ``` > > > [!NOTE] > > > > **Scopes** > > > > Access tokens are scoped. Request only the scopes you need — and you can request a narrower set later for production. > [accordion] 2: Create an Individual Entity > > Every transaction at Lead starts with creating a representation for your customer in Lead's system. For illustrative purposes, the request below creates an example Individual Entity with minimal information provided. > > ```text theme={null} > curl -X POST https://api.sandbox.lead.bank/v0/entities \ > -H "Authorization: Bearer $LEAD_TOKEN" \ > -H 'Content-Type: application/json' \ > -H 'Idempotency-Key: quickstart-entity-001' \ > -d '{ > "type": "individual", > "client_customer_id": "customer-id-from-my-system", > "intended_roles": ["account_holder"], > "risk_score": "low", > "individual_details": { > "first_name": "Ada", > "last_name": "Lovelace", > "date_of_birth": "1990-12-10", > "identification_details": { > "type": "us_entity", > "tax_identification": { "type": "ssn", "value": "123456789" } > }, > "contact_methods": [ > { "type": "email", "email": "ada@example.com" } > ], > "address_details": { > "physical_address": { > "line_1": "123 Analytical Engine Way", > "city": "Brooklyn", > "state": "NY", > "postal_code": "11201", > "country": "US" > } > } > }, > "kyc_details": { "result": "passed", "screened_at": "2026-01-15T10:00:00Z" }, > "ofac_details": { "result": "passed", "screened_at": "2026-01-15T10:00:00Z" } > }' > ``` > > A successful response includes an `id` that starts with `entity_.` Save it for the next step: > > ```text theme={null} > export LEAD_ENTITY_ID="entity_abc123..." > ``` > > > [!NOTE] > > > > **Idempotency** > > > > Every write endpoint requires an Idempotency-Key header. If you retry the same request with the same key (e.g. after a network blip), Lead returns the original response instead of creating a duplicate. Use a fresh key per logical operation. > [accordion] 3: Retrieve the Entity > > Confirm the entity is queryable. You can fetch by Lead’s entity ID you supplied. > > ```text theme={null} > curl https://api.sandbox.lead.bank/v0/entities/$LEAD_ENTITY_ID \ > -H "Authorization: Bearer $LEAD_TOKEN" > ``` > > You should get back the same entity object you just created, with timestamps populated. > [accordion] 4: Create an Account Number > > Before you can receive or send money, you need an Account Number assigned to your account. Lead provides an account\_id during onboarding — this is your FBO account, not a per-user account. Use it directly to create an Account Number for each customer. > > **Create the account number:** > > ```text theme={null} > curl -X POST https://api.sandbox.lead.bank/v1/account_number \ > -H "Authorization: Bearer $LEAD_TOKEN" \ > -H 'Content-Type: application/json' \ > -H 'Idempotency-Key: quickstart-acct-num-001' \ > -d '{ > "account_id": "YOUR_ACCOUNT_ID" > }' > ``` > > Replace `YOUR_ACCOUNT_ID` with the `account_id` provided by your Technical Account Manager. > > A successful response includes an id that starts with account\_number\_xyz and the 10-digit DDA number alongside Lead's routing number. Save the ID — you'll use it in the next two steps: > > ```text theme={null} > export LEAD_ACCT_NUM_ID="account_number_xyz..." > ``` > > > [!NOTE] > > > > **Account Numbers and Routing** > > > > Lead assigns a real account number and routing number to every Account Number object. This is what counterparties use to send money to your customer. Multiple Account Numbers can map to a single Account — for example, one for ACH and one for wire. > [accordion] 5: Simulate an Incoming ACH Credit > > The sandbox provides simulation endpoints that are not available in production. They let you trigger inbound transactions so you can test the full lifecycle of a payment. The example below is for ACH, but wires, and instant payments are similar. > > ```text theme={null} > curl -X POST https://api.sandbox.lead.bank/v1/simulate/ach/incoming_ach \ > -H "Authorization: Bearer $LEAD_TOKEN" \ > -H 'Content-Type: application/json' \ > -H 'Idempotency-Key: quickstart-incoming-ach-001' \ > -d '{ > "account_number_id": "'$LEAD_ACCT_NUM_ID'", > "amount": 12500, > "currency_code": "USD", > "transaction_type": "credit", > "sec_code": "PPD", > "statement_descriptor": "DEPOSIT", > "sender_name": "Quickstart Co", > "sender_company_id": "1234567890", > "sender_routing_number": 121000248 > }' > ``` > > The response includes an id that starts with `ach_`. Copy it and substitute it for `{ach_id}` in the retrieve call below. Amounts are in cents — 12500 is \$125.00. > > ```text theme={null} > curl https://api.sandbox.lead.bank/v1/ach/{ach_id} \ > -H "Authorization: Bearer $LEAD_TOKEN" > ``` > > > [!NOTE] > > > > **Sandbox** > > > > ACH transactions don't advance through their lifecycle on real network timing in sandbox. Use `POST /v1/simulate/ach/{ach_id}/advance` to move the transfer through its states manually. > [accordion] 6: Send an Outgoing ACH > > Now send money out from your account. An outgoing ACH requires an Account Number on the sending side and a destination routing number and account number on the receiving side. > > ```text theme={null} > curl -X POST https://api.sandbox.lead.bank/v1/ach \ > -H "Authorization: Bearer $LEAD_TOKEN" \ > -H 'Content-Type: application/json' \ > -H 'Idempotency-Key: quickstart-outgoing-ach-001' \ > -d '{ > "account_number_id": "'$LEAD_ACCT_NUM_ID'", > "amount": 5000, > "currency_code": "USD", > "transaction_type": "debit", > "delivery_type": "next_business_day", > "sec_code": "PPD", > "statement_descriptor": "PAYMENT", > "counterparty": { > "name": "Jordan Smith", > "routing_number": "021000021", > "account_number": "9900000001", > "account_type": "checking" > } > }' > ``` > > A successful response returns an id that starts with `ach_` and an initial status of `created`. Save it: > > ```text theme={null} > export LEAD_ACH_ID="ach_abc123..." > ``` > > Retrieve the transfer to confirm its status: > > ```text theme={null} > curl https://api.sandbox.lead.bank/v1/ach/{id} \ > -H "Authorization: Bearer $LEAD_TOKEN" > ``` > > > [!NOTE] > > > > **Effective Entry Date** > > > > Setting `delivery_type` to `next_business_day` schedules the ACH for the next valid settlement date. Use `same_business_day` for same-day ACH if your program supports it. Lead derives the effective date automatically — see [*ACH → Timing & Availability*](/products/ach/timing) for cutoff times and valid date rules. > > > [!NOTE] > > > > **Sandbox** > > > > Outgoing ACH transfers don't submit to the real network. Use `POST /v1/simulate/ach/{ach_id}/advance` to move the transfer through its lifecycle states manually. ## What's Next * **[Webhooks](/api-integrations/using-the-api/webhooks):** Receive events instead of polling. Configure your endpoint and start listening for `ach.created`, `ach.posted`, and lifecycle events for every other object. * [**Idempotency & Errors:**](/api-integrations/using-the-api/idempotency) Error envelope, retry semantics, and the canonical error codes you’ll handle. * [**Move Money Guides:**](/api-integrations/using-the-api/authentication) Full per-rail walkthroughs for ACH, Wire, Instant Payments, Blockchain, and Internal Transfers. ## Troubleshooting | Error | Potential Fix | | - | - | | **401 Unauthorized** |
  • Token expired (24h default). Run Step 1 again.
  • Authorization header malformed. Should be exactly `Authorization: Bearer ` — note the space and capitalization.
| | **403 source\_ip\_not\_allowed** |
  • Your client’s public IP isn’t on the program allowlist.
  • Either add your office or VPN egress IP via your TAM (Technical Account Manager), or run the request from an allowlisted environment.
  • See [Auth & Security → IP Allowlist](/api-integrations/using-the-api/authentication#ip-allowlist).
| | **422 Unprocessable Entity on Create Entity** |
  • Most common cause: missing or malformed `kyc_details / ofac_details` when `intended_roles` includes `account_holder`, `minor_account_holder`, or `authorized_signer`. Sandbox accepts placeholder values, but they must be structurally valid.
  • Second most common: `intended_roles` mismatched with entity type. For `business` or `sole_prop`, only `account_holder` is valid.
| | **409 Conflict** |
  • You reused an Idempotency-Key with a different request body.
  • Either send the same body (and you’ll get the original response back), or pick a new key.
| # Originate Your First Loan Source: https://docs.lead.bank/get-started/quickstart/originate-your-first-loan Create a borrower entity, submit an application, open a credit account, define loan terms on a subledger balance, and originate a funding. ### Before You Start You will need: * **Sandbox API credentials:** A `client_id` and `client_secret` provided by your Lead Technical Account Manager during kickoff. * **curl:** Installed on macOS by default; `curl --version` should print something. Any HTTP client works. * **A Funding FBO provisioned for your program:** Lead opens this during onboarding. The Funding API moves money into your Funding FBO when the Funding object posts. * **Optional:** jq— for cleaner JSON output. Pipe responses through `| jq .` if you have it installed. > [!NOTE] > > **Sandbox Only** > > Every example uses [api.sandbox.lead.bank](http://api.sandbox.lead.bank). The same calls work against [api.lead.bank](http://api.lead.bank) in production once your program is approved for go-live, but you should never run this guide against production credentials. > [!TIP] > > If you have not already done [Make Your First Payment API Call](/get-started/quickstart/make-your-first-payment-api-call), start there — it covers authentication, idempotency, and the Entity API in more depth. ## Steps 25 minutes We'll walk through originating a simple \$5,000 personal term loan to an individual borrower, repaid monthly over 24 months. > [accordion] 1: Get an Access Token > > Same OAuth2 client credentials flow as the Payment Quickstart. Exchange your `client_id` and `client_secret` for a short-lived access token and pass it as a Bearer header on every subsequent request. > > ```text theme={null} > curl -X POST https://api.sandbox.lead.bank/v1/oauth/token \ > -H 'Content-Type: application/json' \ > -d '{ > "grant_type": "client_credentials", > "client_id": "YOUR_CLIENT_ID", > "client_secret": "YOUR_CLIENT_SECRET", > "scope": "entity/read_write application/read_write account/read_write subledger_balance/read_write funding/read_write" > }' > ``` > > Save the access\_token value as a shell variable: > > ```text theme={null} > export LEAD_TOKEN="eyJhbGciOiJSUzI1NiIs..." > ``` > > > [!NOTE] > > > > **Scopes** > > > > Lending workflows need broader scopes than payments. The scope list above covers everything in this guide. > [accordion] 2: Create the Borrower Entity > > Every loan starts with an Entity for the borrower. We'll create an Individual with placeholder KYC and OFAC results so the sandbox accepts it. > > ```text theme={null} > curl -X POST https://api.sandbox.lead.bank/v0/entities \ > -H "Authorization: Bearer $LEAD_TOKEN" \ > -H 'Content-Type: application/json' \ > -H 'Idempotency-Key: quickstart-loan-entity-001' \ > -d '{ > "type": "individual", > "client_customer_id": "qs-borrower-001", > "intended_roles": ["account_holder"], > "risk_score": "low", > "individual_details": { > "first_name": "Ada", > "last_name": "Lovelace", > "date_of_birth": "1990-12-10", > "identification_details": { > "type": "us_entity", > "tax_identification": { "type": "ssn", "value": "123456789" } > }, > "contact_methods": [ > { "type": "email", "email": "ada@example.com" } > ], > "address_details": { > "physical_address": { > "line_1": "123 Analytical Engine Way", > "city": "Brooklyn", > "state": "NY", > "postal_code": "11201", > "country": "US" > } > } > }, > "kyc_details": { "result": "passed", "screened_at": "2026-01-15T10:00:00Z" }, > "ofac_details": { "result": "passed", "screened_at": "2026-01-15T10:00:00Z" } > }' > ``` > > Save the returned `id` (starts with `entity_`): > > ```text theme={null} > export LEAD_ENTITY_ID="entity_abc123..." > ``` > [accordion] 3: Create the Application > > The Application is your record of the underwriting decision. Lead relies on this data to fulfill critical compliance requirements — including Fair Lending audits and adverse action tracking under **Regulation B (ECOA)** and **Regulation V (FCRA)**, **Military Lending Act (MLA)** status verification, and **BSA/AML** recordkeeping. Applications are always created in a terminal status (`approved`, `declined`, or `canceled`). Lead does not track in-flight applications; you finalize the underwriting decision on your side, then create the API object when you have a definitive result. > > For our approved \$5,000 loan: > > ```text theme={null} > curl -X POST https://api.sandbox.lead.bank/v0/applications \ > -H "Authorization: Bearer $LEAD_TOKEN" \ > -H 'Content-Type: application/json' \ > -H 'Idempotency-Key: quickstart-loan-app-001' \ > -d '{ > "client_application_id": "QS-LOAN-001", > "status": "approved", > "entities": { > "account_holders": ["'$LEAD_ENTITY_ID'"] > }, > "details": { > "product_name": "Personal Term Loan", > "credit": { > "is_secured": false, > "is_mla": false, > "currency": "USD", > "underwriting_grade": "A", > "limit": 500000, > "max_limit": 500000, > "report": { > "score": 760, > "pulled_at": "2026-04-01T09:30:00Z", > "source": "experian" > } > } > }, > "decision": { > "decided_at": "2026-04-01T10:00:00Z", > "reason": "Approved based on credit profile and debt-to-income ratio." > }, > "documents": [ > { > "document_id": "credit-pull-consent-ada-20260401", > "type": "credit_pull_consent", > "consented_at": "2026-04-01T09:25:00Z" > } > ] > }' > ``` > > Save the returned `id` (starts with `application_`): > > ```text theme={null} > export LEAD_APPLICATION_ID="application_xyz789..." > ``` > > > [!NOTE] > > > > **Documents** > > > > Document IDs reference filenames in your `/documents` SFTP directory. For this quickstart you can use any string — sandbox does not verify the file exists. In production, the file must be delivered to SFTP before referencing it. > [accordion] 4: Create the Credit-Enabled Account > > The Account is the legal account the borrower holds with Lead. For credit products, the Account is required and must reference an `application_id`. Capabilities tell Lead what type(s) of Balances the Account will hold — `credit_with_underwriting` for products requiring a credit Balance with an underwriting component (e.g., a loan with an application) and `credit_without_underwriting` for products requiring a credit Balance but do not have an underwriting component (e.g., courtesy overdraft). > > ```text theme={null} > curl -X POST https://api.sandbox.lead.bank/v0/accounts \ > -H "Authorization: Bearer $LEAD_TOKEN" \ > -H 'Content-Type: application/json' \ > -H 'Idempotency-Key: quickstart-loan-account-001' \ > -d '{ > "application_id": "'$LEAD_APPLICATION_ID'", > "capabilities": ["credit_with_underwriting"], > "entities": { > "account_holders": ["'$LEAD_ENTITY_ID'"] > }, > "details": { > "product_name": "Personal Term Loan", > "credit": { > "is_secured": false, > "is_mla": false, > "underwriting_grade": "A", > "currency": "USD", > "available_credit": 500000, > "limit": 500000, > "max_limit": 500000 > } > }, > "documents": [ > { > "document_id": "loan-agreement-ada-20260401", > "type": "loan_agreement", > "displayed_at": "2026-04-01T10:05:00Z" > } > ] > }' > ``` > > Save the returned `id` (starts with `account_`): > > ```text theme={null} > export LEAD_ACCOUNT_ID="account_def456..." > ``` > [accordion] 5: Create the Subledger Balance > > This is where the loan actually comes into existence. The Subledger Balance defines all the terms — amount, maturity, repayment schedule, interest — and is what Lead's ledger tracks throughout the life of the loan. When you create it, every outstanding amount (principal, interest, fees) is zero because no draw has happened yet. > > For a term loan, use `structure: non_revolving` — there's a fixed loan amount and repayments do not restore available credit. Use `structure: revolving` instead if you're opening a line of credit or credit card where the borrower can re-draw after repayment. > > ```text theme={null} > curl -X POST https://api.sandbox.lead.bank/v0/subledger_balances \ > -H "Authorization: Bearer $LEAD_TOKEN" \ > -H 'Content-Type: application/json' \ > -H 'Idempotency-Key: quickstart-loan-balance-001' \ > -d '{ > "account_id": "'$LEAD_ACCOUNT_ID'", > "client_subledger_balance_name": "Personal Term Loan - Ada Lovelace", > "currency_code": "USD", > "type": "credit", > "details": { > "structure": "non_revolving", > "is_interest_based": true, > "interest_rate": "9.990000", > "effective_apr": "10.250", > "autopay_method": "ach", > "expected_maturity_date": "2028-04-01", > "max_funding_amount": 500000, > "expected_finance_charge_amount": 53400, > "term": { "value": 24, "unit": "months" }, > "repayment_details": [ > { > "expected_payment_frequency": "monthly", > "expected_number_of_payments": 24, > "expected_first_payment_date": "2026-05-01", > "expected_first_payment_amount": 23058, > "expected_last_payment_date": "2028-04-01", > "expected_last_payment_amount": 23058, > "expected_payment_amount": 23058 > } > ] > } > }' > ``` > > Save the returned `id` (starts with `subledger_balance_`): > > ```text theme={null} > export LEAD_BALANCE_ID="subledger_balance_ghi789..." > ``` > > > [!NOTE] > > > > **Why Balance and Funding are Decoupled** > > > > You define loan terms once (Balance) but can draw funds against them many times (Funding). For a term loan this usually means one draw at origination, but for a line of credit you'll create multiple Funding objects against the same Balance throughout its life. > [accordion] 6: Create the Funding > > The Funding object instructs Lead to move principal from a Lead GL into your Funding FBO. Once posted, you can disburse those funds externally via ACH, wire, or instant payment — but that's a separate step on a payment rail. > > For this term loan, the borrower is taking the full \$5,000 as a single draw. There is no merchant origination fee (this isn't a BNPL product) and nothing is withheld for later disbursement. > > ```text theme={null} > curl -X POST https://api.sandbox.lead.bank/v0/fundings \ > -H "Authorization: Bearer $LEAD_TOKEN" \ > -H 'Content-Type: application/json' \ > -H 'Idempotency-Key: quickstart-loan-funding-001' \ > -d '{ > "subledger_balance_id": "'$LEAD_BALANCE_ID'", > "currency_code": "USD", > "principal": { > "external_disbursement_amount": 500000, > "withheld_amount": 0, > "merchant_origination_fee_amount": 0 > }, > "metadata": { > "client_draw_id": "QS-DRAW-001" > } > }' > ``` > > The response returns an id that starts with `funding_` and an initial `status` of `processing`. Save it: > > ```text theme={null} > export LEAD_FUNDING_ID="funding_jkl012..." > ``` > > > [!NOTE] > > > > **Principal Components** > > > > For a simple personal term loan, the entire principal goes to `external_disbursement_amount`. The other two fields cover other use cases: `withheld_amount` is for funds you'll disburse later and `merchant_origination_fee_amount` is for merchant fees (typically in BNPL loans). > [accordion] 7: Retrieve the Funding > > Funding objects move asynchronously from `processing` to `posted` (or `rejected`). Poll the Funding endpoint — or listen for the `funding.posted` webhook event — to confirm. > > ```text theme={null} > curl https://api.sandbox.lead.bank/v0/fundings/$LEAD_FUNDING_ID \ > -H "Authorization: Bearer $LEAD_TOKEN" > ``` > > When status flips to posted, the \$5,000 is sitting in your Funding FBO and ready to be disbursed externally. > > > [!NOTE] > > > > **Sandbox** > > > > Funding does not auto-advance in sandbox. Use `POST /v0/fundings/{id}/advance` to move the Funding from processing → posted (or processing → rejected) so you can test your webhook handlers and downstream disbursement logic. ## What's Next * **Disburse Funds Externally** Now that \$5,000 is in your Funding FBO, send it to the borrower via ACH, wire, or instant payment. * **Webhooks** Listen for `funding.posted` and `funding.rejected` instead of polling. Configure your endpoint per [Webhooks & Events.](/api-integrations/using-the-api/webhooks) * **Service the Loan** Report ongoing activity — interest accrual, principal repayments, fees — against the Subledger Balance via the Balance and Transaction files. See [Balance Reconciliation](/products/balances-and-transactions/balance-reconciliation). * **Multi-Draw Use Cases** For multi-draw term loans or lines of credit, create additional Funding objects against the same Subledger Balance over its life. The sum of all `principal.*` amounts across posted and processing Fundings cannot exceed the Balance's `max_funding_amount` (for `non_revolving`) or the available credit (for `revolving`). * **Closing the Loan** Once the balance is paid off and the loan is in a terminal status, update the Subledger Balance to `closed` via the Balance file. Closure requires all outstanding amounts to be zero. ## Troubleshooting | Error | Potential Fix | | :- | :- | | **401 Unauthorized** |
  • Token expired (24h default). Run Step 1 again.
  • Authorization header malformed. Should be exactly `Authorization: Bearer ` — note the space and capitalization.
| | **422 Unprocessable Entity on Create Application** |
  • `details.decision.adverse_action_notice` missing for a declined status. Required when the decision is declined.
  • `credit.limit` exceeds `credit.max_limit`. The assigned limit cannot be higher than what underwriting approved.
  • `client_application_id` starts with the reserved prefix `application_`. Pick a different prefix on your side.
| | **422 Unprocessable Entity on Create Entity** |
  • `application_id` missing. Required for credit accounts. The Account must reference the Application that authorized the credit.
  • `details.credit.available_credit` greater than `details.credit.limit`. Available credit cannot exceed the current limit.
  • Missing `authorized_signers` when account holders are commercial. Required for business or sole prop account holders.
| | **422 Unprocessable Entity on Create Subledger Balance** |
  • `type` is anything other than credit. Lending workflows require `credit`-type balances; deposit is not valid here.
  • `details.structure` missing or invalid. Must be non\_revolving for term loans or revolving for lines of credit and credit cards.
  • `details.expected_maturity_date`, `details.max_funding_amount`, `details.term`, or `details.expected_finance_charge_amount` missing for a `non_revolving` structure. All four are required.
  • `details.is_interest_based` missing. Required for credit-type Subledger Balances.
| | **422 Unprocessable Entity on Create Funding** |
  • Sum of `external_disbursement_amount` + `withheld_amount` is 0. At least one of the two must be greater than 0.
  • `merchant_origination_fee_amount` is greater than or equal to `external_disbursement_amount` + `withheld_amount`. The merchant fee must be less than total principal.
  • Total funding across all posted and processing Fundings against this Subledger Balance exceeds `max_funding_amount`. Only relevant for `non_revolving` structures.
| | **409 Conflict** |
  • You reused an Idempotency-Key with a different request body.
  • Either send the same body (and you'll get the original response back), or pick a new key.
| # Sandbox Environment Setup and Simulation Endpoints Source: https://docs.lead.bank/get-started/sandbox Set up Lead's sandbox environment, advance ACH and wire transfers using simulation endpoints, and validate your integration before go-live. Lead's sandbox is an isolated test environment where you can build and validate your integration without moving real money. Every call you make hits real API infrastructure — the only difference is that transactions are simulated and no funds settle on actual networks.\\ ## Access and Credentials Your Technical Account Manager provides sandbox credentials — a client\_id and client\_secret — during kickoff. API and SFTP credentials are separate, and both are separate from your production credentials. | | **Sandbox** | **Production** | | - | - | - | | API base | `https://api.sandbox.lead.bank` | `https://api.lead.bank` | | SFTP host | [sftp.sandbox.lead.bank](http://sftp.sandbox.lead.bank) | [sftp.lead.bank](http://sftp.lead.bank) | | Port | 22 | 22 | | Credentials | Provided at kickoff | Issued after go-live approval | | Real money | No | Yes | > [!NOTE] > > **No Credentials?** > > If you do not have credentials, contact your Technical Account Manager. ## Set Up Your Integration Lead supports three integration paths. Your sandbox setup covers whichever paths apply to your program — most partners use a hybrid approach of API and file. ### **API Only** If your program uses APIs exclusively, sandbox setup requires: 1. Lead issues your `client_id` and `client_secret` for the sandbox API. 2. You register your webhook endpoint URL with your Technical Account Manager. 3. You configure your IP allowlist with your Technical Account Manager. [→ Start with the Quickstart: Make Your First Payment API Call](/get-started/quickstart/make-your-first-payment-api-call) ### File Only (SFTP) If your program uses SFTP file delivery exclusively, sandbox setup requires: 1. Generate an SSH keypair: `ssh-keygen -t ed25519 -C "lead-integration" -f lead_sftp_key` 2. Send your public key to your Implementation Manager as plain text. 3. Verify Lead's sandbox host fingerprint: `ssh-keyscan sftp.sandbox.lead.bank 2>&1 | ssh-keygen -lf -` * Expected: `2048 SHA256:rCdk4LeHvxn5G3j7VDJvqH6oEMh844E7sHxoaxih2dE sftp.sandbox.lead.bank (RSA)` 4. Add Lead's key to your known hosts: `ssh-keyscan sftp.sandbox.lead.bank >> ~/.ssh/known_hosts` 5. Connect: `sftp -v -i ~/.ssh/your_key username@sftp.sandbox.lead.bank` Once connected, your SFTP directory follows this structure: * **Read/Write**: Folders where you are the submitter (customer, accounts, balances, transactions, etc.) * **Read Only**: Folders where Lead is the submitter (bank-account-reports, ach/incoming, etc.) The full folder structure and file naming conventions are in [File Delivery](/file-reference/delivery/overview). ### Hybrid (Most Common) Most programs use APIs for real-time money movement and entity onboarding, and SFTP files for daily reporting and reconciliation. Complete both the API and file setup steps above. ## What is Simulated All payment rails are available in sandbox, but no transactions submit to real networks. ACH entries do not go to the Fed, wires do not move through Fedwire or Swift, and FedNow payments do not reach real receiving institutions. SFTP files are validated against your schema but do not trigger real reconciliation or settlement. Because sandbox transactions do not follow real network timing, Lead provides simulation endpoints that let you advance a transfer through its lifecycle states manually. These endpoints exist only in sandbox — they return 404 in production. | Action | Endpoint | | - | - | | Advance an ACH through states | `POST /v1/simulate/ach/{ach_id}/advance` | | Trigger an inbound ACH | `POST /v1/simulate/ach/incoming_ach` | | Trigger an incoming ACH return | `POST /v1/simulate/ach/{ach_id}/incoming_return` | | Advance a wire through states | `POST /v1/simulate/wires/{wire_id}/advance` | | Trigger an inbound wire | `POST /v1/simulate/wires/incoming` | | Trigger an incoming wire return | `POST /v1/simulate/wires/{wire_id}/incoming_return` | | Trigger an inbound instant payment | `POST /v1/simulate/instant_payments/incoming` | | Trigger an incoming instant payment return | `POST /v1/simulate/instant_payments/{instant_payment_id}/incoming_return` | | Advance a funding (lending) | `POST /v0/fundings/{id}/advance` | ## Key Differences From Production > [accordion] ACH transactions require manual advancement. Instant payments and internal transfers do not. > > In production, ACH transfers progress through their lifecycle automatically based on network timing (for example for an outgoing ACH, `scheduled` → `processing` → `submitted` → `posted`). In sandbox, ACH transfers remain in the `scheduled` status until you explicitly advance them using the simulation endpoints. > > Use `POST /v1/simulate/ach/{ach_id}/advance` and the other simulation endpoints to move ACH transfers through different states and test your webhook handling, status polling, and reconciliation logic. > > **Instant payments and internal transfers behave differently.** Their statuses advance automatically in sandbox, so no manual advancement is required. > [accordion] International wires reach accepted but do not settle automatically.  > > Payments move to accepted status but do not advance further without manual simulation. Use `POST /v1/simulate/wires/{wire_id}/advance` to move them through the remaining states. > [accordion] KYC and OFAC are not enforced.  > > Sandbox accepts placeholder screening results — you can pass `"result": "passed"` for both `kyc_details` and `ofac_details` without running a real identity check. In production, your screening results must reflect actual verification. > > ```json theme={null} > "kyc_details": { "result": "passed", "screened_at": "2026-01-15T10:00:00Z" }, > "ofac_details": { "result": "passed", "screened_at": "2026-01-15T10:00:00Z" } > ``` > [accordion] Rate limits are looser.  > > Sandbox has higher per-minute request limits than production to support active integration work. Production limits are set per program and defined in your contract. > [accordion] Simulation endpoints return 404 in production.  > > Any path under `/v1/simulate` (and the lending funding advance endpoint) is sandbox-only. Do not call these endpoints in production — they return `404`. > [accordion] SFTP file validation runs but does not trigger reconciliation. > > Files you submit in sandbox are validated against your schema and will surface errors the same way production does — but they do not feed real reconciliation or accounting processes. ## Data Persistence and Resets Entities, accounts, and account numbers you create persist until you request a reset. If you need to reset your sandbox environment — for example, before a new test phase or to clear conflicting test data — contact your Technical Account Manager. ## What to Test Before Go-Live Before go-live, complete testing for each of the following: * Create entities, including KYC and OFAC fields * Create accounts and account numbers * Send and receive payments for each contracted rail * Trigger and handle returns and reversals * Receive and process webhook events * Submit SFTP files and confirm schema validation passes * Handle common error responses (401, 403, 409, 422) The specific testing milestones required before go-live are covered in [Program Launch](/get-started/program-launch). # Welcome to Lead Source: https://docs.lead.bank/get-started/what-is-lead Programmable financial services built to support any use case, quickly. Lead is a bank built for builders: programmable financial services delivered through REST APIs, with the compliance infrastructure of a regulated sponsor bank underneath. Partners use Lead to store money, move money, lend, and issue cards — separately or in combination. ## What You Can Build with Lead Lead organizes its capabilities into four product pillars. Most programs combine more than one. > [card] Lend > > Originate term loans and lines of credit — both secured & unsecured — and disburse funds to where they need to go. > [card] Issue > > Issue debit, prepaid, & credit cards through your card-issuing processor while Lead handles settlement flows & oversight. > [card] Move > > Send and receive payments and transfers across domestic, international, and blockchain rails. > [card] Store > > Hold customer funds in deposit accounts with FDIC insurance and optimized account structures for your program. ## **How Lead is put together** Lead represents every program with a small set of core objects — the same objects across every [product](/products/overview). The ones you'll meet first: | Object | What it Represents | | - | - | | Entity | A legal person or organization — an individual, sole proprietor, or business. The starting point for every customer relationship. KYC and OFAC screening apply at the Entity level. | | Account | A financial product held by one or more entities. | | Account Number | A routable address that money can be sent to or from. Multiple account numbers can map to a single account/balance. | | Balance | The current and available funds on an account, including any subledger balances you maintain. | | Transaction | An individual debit or credit posted to an account, with full lineage back to the originating payment. | | *Additional objects* | *See the [Object Model](/core-concepts/platform/object-model) for the complete set and how they connect.* | See the [Object Model](/core-concepts/platform/object-model) for the complete set of objects and how they connect. Two things to understand early, because they shape everything else: **which of Lead's APIs execute versus report** ([Executing vs. Reporting](/core-concepts/platform/executing-vs-reporting)) and **which integration surface each product uses today** — Lead is moving from a hybrid file-and-API model to fully API-based, and [Integration Surfaces by Product](/core-concepts/platform/integration-surfaces-by-product) states the current truth per product, with the forward story in [Platform Evolution](/core-concepts/platform/platform-evolution). > [!TIP] > > If you've worked with another BaaS platform, an Entity maps to a customer record, and an Account Number to a routable destination. > > For full relationship and lifecycle details, see [Object Model](/core-concepts/platform/object-model) in Core Concepts. ## Where to Start Pick the path that matches your role on the implementation team. **If you’re a developer:** * [**Make Your First Payment API Call (15 minutes)**](/get-started/quickstart/make-your-first-payment-api-call): Authenticate, create an entity, assign an account number, simulate an incoming ACH credit, and send an outgoing ACH. * [Originate Your First Loan (25 minutes)](/get-started/quickstart/originate-your-first-loan): Authenticate, create a borrower Entity, record the underwriting decision as an Application, open a credit-enabled Account, define the loan terms on a Subledger Balance, and execute your first Funding request. * [**Sandbox Environment**](/get-started/sandbox): Understand what's available and simulated. **If you’re a product or program manager:** * [**Program Launch**](/get-started/program-launch): The contracting, due diligence, and technical integration milestones from kickoff to testing and go-live. **If you’re leading compliance or risk:** * [**Partner Site**](https://partners.lead.bank/): SLAs, compliance and data requirements, risk management framework, program policies, and more. # The Account Number Object Source: https://docs.lead.bank/products/account-number/account-number-object Field-level reference for the Account Number object, including identifiers, assignment, and linkage to accounts. ```json theme={null} { "id": "account_number_xyz", "account_number": 123412341234, "routing_number": 123456789, "account_id": "account_xyz123", "client_customer_id": "", "entity_id": "entity_xyz123", "status": "active", "ach_controls": { "originator_id": "originator_xyz123", "incoming": { "accept_credit": true, "accept_debit": true, "counterparty_filter": "accept_all", "counterparty_company_ids_allowlist": [ 1234567890 ] }, "outgoing": { "counterparty_filter": "accept_all", "counterparty_account_numbers_allowlist": [ { "type": "us_domestic", "account_number": 123412341234, "routing_number": 123412341234 } ] } }, "wire_controls": { "incoming": { "counterparty_filter": "accept_all", "counterparty_account_numbers_allowlist": [ { "type": "us_domestic", "account_number": 123412341234, "routing_number": 123412341234 } ] }, "outgoing": { "counterparty_filter": "accept_all", "counterparty_account_numbers_allowlist": [ { "type": "us_domestic", "account_number": 123412341234, "routing_number": 123412341234 } ] }, "outgoing_international": { "counterparty_filter": "accept_all", "counterparty_international_account_numbers_allowlist": [ { "business_identifier_code": "CHASUS33", "account_identifier": { "value": "GB29NWBK60161331926819" } } ] } }, "internal_transfer_controls": { "incoming": { "counterparty_filter": "accept_all", "counterparty_account_number_ids_allowlist": [ "account_number_xyz123" ] }, "outgoing": { "counterparty_filter": "accept_all", "counterparty_account_number_ids_allowlist": [ "account_number_xyz123" ] } }, "instant_payment_controls": { "incoming": { "counterparty_filter": "accept_all", "counterparty_account_numbers_allowlist": [ { "account_number": 123412341234, "routing_number": 123412341234 } ] }, "outgoing": { "counterparty_filter": "accept_all", "counterparty_account_numbers_allowlist": [ { "account_number": 123412341234, "routing_number": 123412341234 } ] } }, "metadata": {}, "created_at": "2023-11-07T05:31:56Z", "updated_at": "2023-11-07T05:31:56Z" } ``` # Controls Source: https://docs.lead.bank/products/account-number/controls Block or allow transactions at the account number level. ## Overview Manage ACH, Wires, Instant Payments, and Internal Transfers by choosing which transactions to allow or block for each account number. ### **How It Works** Configure the controls through the create or update [Account number API](/api-reference/endpoint/account-number/create-an-account-number). **Examples** * To determine if incoming ACH credit is accepted, use `accept_credit`. * To determine if incoming ACH debit is accepted, use `accept_debit`. The `counterparty_filter`: * `accept_all` * `reject_all` * `allowlist_only` and the `counterparty_account_numbers_allowlist` determine which counterparties are allowed to send or receive payments. ### Default Behavior If no controls are configured, the defaults will maintain the current permissive behavior: * `accept_credit=true` * `accept_debit=true` * `counterparty_filter=accept_all` > [!TIP] > > The API will automatically prevent contradictory configurations, such as `accept_credit=false` combined with `counterparty_filter=accept_all`. ### Handling Returns When `accept_debit=false`, inbound ACH debits will be returned with return code: * **R16:** Access to the account is restricted due to action taken by the RDFI. > [!NOTE] > > For more return code details, view the [ACH Return & Rejections Codes guide](/products/ach/exceptions). ### Microdeposits & Reversals To support standard ACH account verification and reversal processes, the Lead system will continue to allow ACH microdeposits and reversals, even when account number controls are enabled. This ensures these processes continue to work smoothly while you maintain full control over all other ACH activity. ## Control Attributes ### ACH | **Attribute** | **Description** | **Type** | | - | - | - | | ach\_controls.originator\_id | Identifier of the ACH originator associated with this account number. | string | | ach\_controls.incoming.accept\_credit | Indicates whether this account number can receive ACH credits. | boolean | | ach\_controls.incoming.accept\_debit | Indicates whether this account number can receive ACH debits. | boolean | | ach\_controls.incoming.counterparty\_filter | Specifies which counterparties are allowed to send ACH transfers to this account number. Possible values: `accept_all`: All counterparties are allowed. `allowlist_only` : Only explicitly listed counterparties are allowed. `reject_all`: All counterparties are blocked. | enum | | ach\_controls.incoming.counterparty\_company\_ids\_allowlist | List of Company IDs permitted to send incoming ACH transfers when `counterparty_filter` is `allowlist_only`. | array | | ach\_controls.outgoing.counterparty\_filter | Specifies which counterparties this account number is allowed to send ACH transfers to. Possible values: `accept_all`: All counterparties are allowed. `allowlist_only`: Only explicitly listed counterparties are allowed. `reject_all`: All counterparties are blocked. | enum | | ach\_controls.outgoing.counterparty\_account\_numbers\_allowlist | List of permitted outgoing ACH counterparties when `counterparty_filter` is `allowlist_only`. Each entry includes: `type`: Counterparty account type (e.g., `us_domestic`) `account_number`: Counterparty account number `routing_number`: Counterparty routing number | array of objects | ### Wire | **Attribute** | **Description** | **Type** | | - | - | - | | wire\_controls.incoming.counterparty\_filter | Specifies which counterparties are allowed to send wire transfers to this account number. Possible values: `accept_all`: All counterparties are allowed. `allowlist_only`: Only explicitly listed counterparties are allowed. `reject_all`: All counterparties are blocked. | enum | | wire\_controls.incoming.counterparty\_account\_numbers\_allowlist | List of permitted incoming wire counterparties when `counterparty_filter` is `allowlist_only`. Each entry includes: `type`: Counterparty account type (e.g., `us_domestic`) `account_number`: Counterparty account number `routing_number`: Counterparty routing number | array of objects | | wire\_controls.outgoing.counterparty\_filter | Specifies which counterparties this account number is allowed to send wire transfers to. Possible values: `accept_all`: All counterparties are allowed. `allowlist_only`: Only explicitly listed counterparties are allowed. `reject_all`: All counterparties are blocked. | enum | | wire\_controls.outgoing.counterparty\_account\_numbers\_allowlist | List of permitted outgoing wire counterparties when `counterparty_filter` is `allowlist_only`. Each entry includes: `type`: Counterparty account type (e.g., `us_domestic`) `account_number`: Counterparty account number `routing_number`: Counterparty routing number | array of objects | | wire\_controls.outgoing\_international.counterparty\_filter | Specifies which counterparties this account number is allowed to send international wire transfers to. Possible values: `accept_all`: All counterparties are allowed. `allowlist_only`: Only explicitly listed counterparties are allowed. `reject_all`: All counterparties are blocked. | enum | | wire\_controls.outgoing\_international.counterparty\_account\_numbers\_allowlist | List of permitted outgoing international wire counterparties when `counterparty_filter` is `allowlist_only`. Each entry includes: `business_identifier_code`: Identifier of the counterparty financial institution (8 or 11 character BIC) `account_identifier`: Account identifier for the counterparty, including: `type`: Counterparty account identifier type (IBAN or `account_number`) `value`: Counterparty account identifier value (1-34 characters) | | ### Instant Payment | **Attribute** | **Description** | **Type** | | - | - | - | | instant\_payment\_controls.incoming.counterparty\_filter | Specifies which counterparties are allowed to send instant payments to this account number. Possible values: `accept_all`: All counterparties are allowed. `allowlist_only`: Only explicitly listed counterparties are allowed. `reject_all`: All counterparties are blocked. | enum | | instant\_payment\_controls.incoming.counterparty\_account\_numbers\_allowlist | List of permitted incoming instant payment counterparties when `counterparty_filter` is `allowlist_only`. Each entry includes: `account_number`: Counterparty account number `routing_number`: Counterparty routing number | array of objects | | instant\_payment\_controls.outgoing.counterparty\_filter | Specifies which counterparties this account number is allowed to send instant payments to. Possible values: `accept_all`: All counterparties are allowed. `allowlist_only`: Only explicitly listed counterparties are allowed. `reject_all`: All counterparties are blocked. | enum | | instant\_payment\_controls.outgoing.counterparty\_account\_numbers\_allowlist | List of permitted outgoing instant payment counterparties when `counterparty_filter` is `allowlist_only`. Each entry includes: `account_number`: Counterparty account number `routing_number`: Counterparty routing number | array of objects | ### Internal Transfers | **Attribute** | **Description** | **Type** | | - | - | - | | internal\_transfer\_controls.incoming.counterparty\_filter | Specifies which counterparties are allowed to send internal transfers to this account number. Possible values: `accept_all`: All counterparties are allowed. `allowlist_only`: Only explicitly listed counterparties are allowed. `reject_all`: All counterparties are blocked. | enum | | internal\_transfer\_controls.incoming.counterparty\_account\_number\_ids\_allowlist | List of permitted sending `account_number_id` values when `counterparty_filter` is `allowlist_only`. | array | | internal\_transfer\_controls.outgoing.counterparty\_filter | Specifies which counterparties this account number is allowed to send internal transfers to. Possible values: `accept_all`: All counterparties are allowed. `allowlist_only`: Only explicitly listed counterparties are allowed. `reject_all`: All counterparties are blocked. | enum | | internal\_transfer\_controls.outgoing.counterparty\_account\_number\_ids\_allowlist | List of permitted receiving `account_number_id` values when `counterparty_filter` is `allowlist_only`. | array | | created\_at | Timestamp the account number object was created, in ISO 8601 format. | string | | updated\_at | Timestamp when the account number object was last updated, in ISO 8601 format. | string | # Managing Account Numbers Source: https://docs.lead.bank/products/account-number/managing Create, assign, and manage the lifecycle of Account Numbers. | **Endpoint** | **Description** | | :- | :- | | `POST /v1/account_number` | Create an Account Number, optionally assigning it a `client_customer_id` or `entity_id` at creation. | | `POST /v1/account_number/{account_number_id}/assign` | Assign an unassigned Account Number to a customer. Pass exactly one of `client_customer_id` or `entity_id`. | | `PATCH /v1/account_number/{account_number_id}` | Update controls or metadata. | | `POST /v1/account_number/{account_number_id}/activate` | Reactivate an `inactive` Account Number. | | `POST /v1/account_number/{account_number_id}/deactivate` | Deactivate an `active` Account Number. It can no longer send or receive. | | `POST /v1/account_number/{account_number_id}/cancel` | Permanently cancel an Account Number. Terminal; the number is not recycled. | An Account Number can send and receive transfers only while it is `active`; see [Statuses](/products/account-number/statuses) for the full lifecycle and [Payment Controls](/products/account-number/controls) for the per-rail settings you can manage with the update endpoint. # Account Numbers: Routable Addresses for your Customers Source: https://docs.lead.bank/products/account-number/overview Create and assign account numbers for your end customers. Account numbers issued through Lead's platform are routable account numbers you can assign to your end customers. They can be used to send and receive funds. Throughout this page, *account* means the [Account (core) object](/core-concepts/platform/object-model#account-core). ```text theme={null} Entity (Lead or partner) └── Account └── Account Number (routable payment address) ``` ## Account Structure Funds may be held in an account in one of two models: a **pooled (omnibus) account** or **individual demand deposit accounts (DDAs)**. Account numbers can be provisioned under either model, and the underlying account structure does not change how they operate. The difference that matters is who maintains the ledger of individual customer balances. ### Pooled Accounts A **pooled account**, structured as a For Benefit Of (FBO) account, is a single account that Lead Bank holds, aggregating funds belonging to multiple end customers. You can still assign individual account numbers to each customer: the customer owns their assigned account numbers, and transactions initiated through them correspond to that customer's funds. Lead maintains the ledger of the pooled account . You (or a third-party ledger provider) maintain the ledger of individual customer balances that collectively make up the pooled funds, and report it to Lead daily. Pooled accounts can provide significant scaling and pricing advantages compared to opening an individual DDA for each end customer. > [!NOTE] > > Your program agreement may require daily reconciliation between your ledger and the pooled account balance held at Lead. Your Technical Account Manager can confirm what applies to your program. ### Demand Deposit Accounts (DDAs) A **demand deposit account (DDA)** is an individual bank account opened in the name of the owner, allowing the customer to access funds on demand. Funds are not pooled with other customers, so no partner-supplied ledger data is required to represent ownership of funds. ## Relationship Between Account & Account Number Objects On Lead's platform, **account objects** represent bank accounts in Lead's platform. Each account object is identified by an `account_id`. > [!TIP] > > Additional Account Numbers can be created and assigned to any customer with an active Entity, using either `entity_id` or `client_customer_id`. Multiple account numbers can belong to the same customer. See [Managing Account Numbers](/products/account-number/managing). ### Example The following example illustrates the relationship between Acme Inc's FBO account, which hosts multiple account numbers associated with Acme Inc's own customers, and its operating account. The `account_id` here refers to the [Account (core)](/core-concepts/platform/object-model#account-core) concept. ![Example of the relationship between account and account numbers.](https://mintcdn.com/lead/G0oWrxMVJhrUJrCL/images/account_id_example_flow.png?fit=max\&auto=format\&n=G0oWrxMVJhrUJrCL\&q=85\&s=1b18ce11de2266e03a16f14266a382cf) # Account Number Statuses Source: https://docs.lead.bank/products/account-number/statuses Description of statuses and lifecycle for account numbers. ## Lifecycle ![Diagram of the statuses and lifecycle for accounts.](https://mintcdn.com/lead/SW5Gs3xcSorCd26U/images/account-number-status-and-lifecycle-1.png?fit=max\&auto=format\&n=SW5Gs3xcSorCd26U\&q=85\&s=7e869a82670afa7920b65fd6d6f103dd) ## Statuses | **Status** | **Description** | **Notes** | | - | - | - | | unassigned | An Account Number is created but has not been assigned to a valid customer through either entity\_id or client\_customer\_id. | Cannot send or receive any transfers. | | active | An Account Number is assigned or re-activated with a valid customer. | Can receive and send (*if enabled*) transfers. | | inactive | An `active` Account Number being deactivated by the partner, or by Lead due to internal policies. | Cannot receive or send any transfers. | | canceled | This is a terminal status and can not be re-activated. Canceled Account Number will not be recycled for future usage. | Cannot send or receive any transfers. | ## Webhooks `account_number.created` fires when an Account Number is created. Status changes do not fire webhooks; poll `GET /v1/account_number/{account_number_id}` if you need to observe them. Status transitions are driven by the assign, activate, deactivate, and cancel endpoints; see [Managing Account Numbers](/products/account-number/managing). # Accounts API Best Practices Source: https://docs.lead.bank/products/accounts/best-practices Guidance on OAuth scopes, idempotency keys, capability selection, and entity sequencing when integrating with the Lead Accounts API. ## Use the Correct Authentication Scope Choose the right OAuth scope before making any API call: * `POST /v0/accounts`, `PATCH /v0/accounts/{id}`, and all status-transition endpoints require **`account/read_write`**. * `GET /v0/accounts/{id}` accepts either **`account/read`** or **`account/read_write`**. Use the least-privileged scope appropriate to the operation. If your integration only needs to retrieve accounts, use `account/read` and avoid provisioning broader write access. ## Use Idempotency Keys on All Write Operations You must include a unique `Idempotency-Key` header on every `POST`, `PATCH`, and `DELETE` request. Use a UUID (for example, `550e8400-e29b-41d4-a716-446655440000`). Key behaviors to be aware of: * If a request fails, use a new idempotency key when retrying — the original key stores the failed response for 48 hours and will replay it. Two exceptions on **409** Conflict: if the error code is `idempotency_key_conflict` and you have not reused this key for a different request, your identical request raced with itself — retry once with the same key to receive the original outcome. If the error code is conflict (resource modified concurrently), reload the resource and resubmit with a new key. * If a request succeeds (**200**), reusing the same idempotency key returns the cached response without creating a duplicate. * A request without the `Idempotency-Key` header returns 400 `operation_not_allowed`, with `Idempotency-Key` listed in `invalid_parameters`. ## Choose the Right Capabilities Every account must declare at least one capability at creation. Your program may have access to a subset of all supported\_capabilities; speak to your Partner Solutions contact if you need to expand to support for additional capabilities. Capabilities drive which fields are required and which compliance validations apply. * **`deposit`** — use for depository accounts (checking, savings). Does not require `application_id` or credit-specific fields. * **`credit_with_underwriting`** — use for credit products tied to an approved application. Requires `application_id` and the full `details.credit` object. * **`credit_without_underwriting`** — use for credit products that do not require underwriting (e.g., overdraft). Does not require `application_id` or credit-specific fields. An account may have multiple capabilities. For example, a checking account with overdraft would use `["deposit", "credit_without_underwriting"]`. Capabilities cannot be removed once added. If an account was created with incorrect capabilities, close it and create a new one. ## Create Entities First The Accounts API validates entity IDs on account creation. Before calling `POST /v0/accounts`, create the relevant entities using the Entity API and collect the `entity_`-prefixed IDs from those responses. Use the server-generated `id` (e.g., `entity_3frCuaBe93vyJZxK3yOhlVuriBY`) in the `entities.account_holders`, `entities.authorized_signers`, and `entities.authorized_users` arrays. Entity creation must be sequenced ahead of account creation — the Accounts API does not create entities on your behalf. ## Create Applications Before Credit Accounts For accounts with the `credit_with_underwriting` capability, the `application_id` field is required. The referenced application must be in `approved` status. Sequence your integration as: 1. Create entities via the Entity API. 2. Create the application via the Applications API, referencing the entity IDs. 3. Create the account via the Accounts API, referencing the `application_id` from step 2. On account creation, Lead validates that the account holder type and at least one account holder match between the application and the account. Mismatches return a `422` error. ## Understand Consumer vs. Commercial Accounts The `account_holder_type` field (`consumer` or `commercial`) is derived from the entity types in `entities.account_holders` — you do not set it directly: * **Individual** entities produce `consumer`. * **Business** or **sole proprietor** entities produce `commercial`. Do not mix individual entities with business or sole proprietor entities within `account_holders`. A single account may not contain both individual and business/sole proprietor account holders. Business and sole proprietor entities may be combined with each other within the same account — both produce an `account_holder_type` of `commercial`. Commercial accounts (those with business or sole proprietor account holders) require at least one entry in `entities.authorized_signers`. Each authorized signer entity must have the `authorized_signer` role assigned. Consumer accounts do not require authorized signers. ## Use Status-Transition Endpoints for Lifecycle Changes The Accounts API manages status through dedicated endpoints, not through `PATCH`: * **`POST /v0/accounts/{id}/deactivate`** — transitions `active` to `inactive`. Requires a `status_reason` (`dormant`, `frozen`, or `other`). * **`POST /v0/accounts/{id}/activate`** — transitions `inactive` back to `active`. No request body required. * **`POST /v0/accounts/{id}/close`** — transitions `active` or `inactive` to `closed`. Requires a `status_reason` (`entity_closed`, `client_closed`, `paid_off`, `charged_off`, or `canceled`). This is terminal and cannot be undone. * The Status transition endpoints additionally support self-serve error correction, allowing a transition from `closed` to `active`. These should only be used to correct a mistakenly reported Account - if an account can be reopened through the normal course of business, an `inactive` status, not a `closed` status should be used. Attempting to set `status` through `PATCH` has no effect. If an account needs to be closed and the status reason is `client_closed`, an adverse action notice (`details.adverse_action_notice`) is required on the account before or at the time of closure. ## Use PATCH for Data Updates Only `PATCH /v0/accounts/{id}` updates mutable data fields on an account. It does not support: * **Status changes** — use the dedicated status-transition endpoints. * **Entity relationship changes** — use the entity relationships endpoints. When patching: * Only include fields you want to update. Omitted fields remain unchanged. * `documents`, if provided, **replaces the entire existing list**. To add a document, include all existing documents plus the new one. * `capabilities`, if provided, can only add new capabilities. Existing capabilities are preserved and cannot be removed. The full updated list of `capabilities` should be provided when updating via `PATCH` - not just the new one(s). If you receive an error that your program does not support a capability, please reach out to Lead's Partner Solutions team to ensure approval for the capability being used. * Closed accounts cannot be updated. `PATCH` on a closed account returns a `422`. ## Handle Credit Report and Adverse Action Notice Fields as All-or-Nothing Two objects on the account follow an all-or-nothing pattern: * **`details.credit.report`** — if included, all three fields (`score`, `pulled_at`, `source`) must be present. Providing a partial set returns a `422`. * **`details.adverse_action_notice`** — if included, all three fields (`delivered_at`, `reason`, `delivery_method`) must be present. Providing a partial set returns a `422`. ## Retrieve Entity Relationships Separately The `GET /v0/accounts/{id}` response includes the derived `account_holder_type` but does not return the underlying entity ID lists. To see which entities are linked to an account and in which role (`account_holder`, `authorized_signer`, or `authorized_user`), use the entity relationships endpoint when it becomes available. # Accounts API Overview Source: https://docs.lead.bank/products/accounts/overview Report deposit and credit account data to Lead using the Accounts API, including creation, status transitions, OAuth scopes, and lifecycle management. ## Introduction The [Accounts API](/api-reference/endpoint/account/create-an-account) reports your end-customer account data to Lead for compliance oversight. You use it to create accounts, update account details, and manage account status throughout the account lifecycle. The API sits after Entity creation (and after Application creation for Lending use-cases) in the compliance onboarding sequence: **1. Entity API** Create entity records for each end customer. Lead validates KYC/KYB data at this step. **2. Applications API** Submit the terminal underwriting decision, referencing entity IDs from step 1. An approved application returns an `application_id`. Required for credit products only. **3. Accounts API** Create the account, referencing the `application_id` from step 2 (for credit products) or entity IDs directly (for deposit products). Accounts are created in `active` status. You can manage the account lifecycle through dedicated status-transition endpoints — activate, deactivate, and close. > [!NOTE] > > A separate OpenAPI spec covers the full schema definition for request and response bodies. This page provides conceptual context for integrating with the API. ## Authentication The Accounts API uses two OAuth scopes: * **`account/read_write`** — required for `POST /v0/accounts`, `PATCH /v0/accounts/{id}`, and all status-transition endpoints. Grants both read and write access. * **`account/read`** — sufficient for `GET /v0/accounts/{id}`. Grants read-only access. Use the least-privileged scope appropriate to your operation. ## Endpoints | Method | Path | Purpose | | :- | :- | :- | | `POST` | `/v0/accounts` | Create a new account. | | `GET` | `/v0/accounts/{id}` | Retrieve an account by ID. | | `PATCH` | `/v0/accounts/{id}` | Update mutable account properties. | | `POST` | `/v0/accounts/{id}/activate` | Transition an inactive account to active. | | `POST` | `/v0/accounts/{id}/deactivate` | Transition an active account to inactive. | | `POST` | `/v0/accounts/{id}/close` | Close an account (terminal). | ## Attributes ### Account Object | **Attribute** | **Type** | **Description** | | - | - | - | | id | string | Unique identifier for the account. Prefixed with `account_`. | | created\_at | timestamp | Lead server-generated ISO 8601 timestamp when the account was created. | | updated\_at | timestamp | Lead server-generated ISO 8601 timestamp when the account was last updated. | | application\_id | string | Associated application ID, if any. Prefixed with `application_`. This is required when the `credit_with_underwriting` capability is present on the Account. | | status | string | Current status of the account: `active`, `inactive`, or `closed`. | | status\_reason | string | Machine-readable reason for the current status. | | capabilities | array | How the account is used: `deposit`, `credit_with_underwriting`, or `credit_without_underwriting`. Lead will validate necessary data requirement submission corresponding to each use-case, and this informs which types of Balances can be created referencing this `account_id`. | | entities | object | Contains the derived `account_holder_type` (`consumer` or `commercial`). | | details | object | Core account details including product name, credit information, and adverse action notice. See `details` object below. | | documents | array | Compliance document references associated with the account. See `documents` array below. | | metadata | object | Arbitrary key-value pairs for storing additional information. | ### entities (object) | **Attribute** | **Type** | **Description** | | - | - | - | | account\_holder\_type | string | Derived from the entity types of the account holders. `consumer` if all account holders are individuals; `commercial` if all are businesses or sole proprietors. | ### details (object) | **Attribute** | **Type** | **Description** | | - | - | - | | product\_name | string | Your internal product name for the account. | | closed\_at | timestamp | ISO 8601 timestamp when the account was closed. Set by the `/close` endpoint. Read-only. | | credit | object | Credit-specific details. Required when capabilities include `credit_with_underwriting`. See `details.credit` below. | | adverse\_action\_notice | object | Adverse action notice details. Required when `status_reason` is `client_closed`. See `details.adverse_action_notice` below. | ### details.credit (object) | **Attribute** | **Type** | **Description** | | - | - | - | | is\_secured | boolean | `true` if the product is secured (collateral attached); `false` otherwise. | | is\_mla | boolean | `true` if the account holder is subject to the Military Lending Act; `false` otherwise. | | underwriting\_grade | string | Your internal underwriting grade for the account holder. | | currency | string | ISO 4217 currency code for the account (e.g., `USD`). | | available\_credit | integer | Available credit in minor units (e.g., cents). | | limit | integer | Current credit limit in minor units. | | max\_limit | integer | Maximum credit limit approved in underwriting, in minor units. | | scra | object | SCRA (Servicemembers Civil Relief Act) details. Optional. See `details.credit.scra` below. | | report | object | Credit bureau report data. Optional. If included, all three sub-fields (`score`, `pulled_at`, `source`) are required. See `details.credit.report` below. | ### details.credit.scra (object) | **Attribute** | **Type** | **Description** | | - | - | - | | start\_date | date | Start date for SCRA protections (`YYYY-MM-DD`). | | end\_date | date | End date for SCRA protections (`YYYY-MM-DD`). Optional. | ### details.credit.report (object) | **Attribute** | **Type** | **Description** | | - | - | - | | score | integer | Credit score returned by the bureau. Range: 300-850. | | pulled\_at | timestamp | ISO 8601 timestamp when the credit report was pulled. | | source | string | Credit bureau that issued the report: `equifax`, `experian`, or `transunion`. | ### details.adverse\_action\_notice (object) | **Attribute** | **Type** | **Description** | | - | - | - | | delivered\_at | timestamp | ISO 8601 timestamp when the adverse action notice was sent. | | reason | string | The reason stated in the adverse action notice. | | delivery\_method | string | How the notice was delivered: `email`, `text`, or `other`. | ### documents (array of objects) | **Attribute** | **Type** | **Description** | | - | - | - | | document\_id | string | Identifier for the document. | | type | string | Document type (e.g., `loan_agreement`, `esign_agreement`). | | consented\_at | timestamp | ISO 8601 timestamp when the account holder consented. Present on consent documents. | | displayed\_at | timestamp | ISO 8601 timestamp when the document was displayed. Present on disclosure documents. | ## Key Concepts **Account Capabilities** Every account declares one or more capabilities that inform Lead how the account is used. Capabilities determine which fields are required and which compliance validations apply. The three capabilities are: * **`deposit`** — a depository account (e.g., checking, savings). * **`credit_with_underwriting`** — a credit account tied to an approved application. Requires `application_id` and the full `details.credit` object. * **`credit_without_underwriting`** — a credit account that does not require underwriting (e.g., overdraft products). Does not require `application_id` or credit-specific fields. Capabilities cannot be removed once added. If an account was created with incorrect capabilities, close it and create a new account. **Status Lifecycle** Accounts are created in `active` status. Status transitions are managed through dedicated endpoints — not by setting a status field on `PATCH`. The three states are: * **`active`** — the account is operational. Default on creation. * **`inactive`** — the account is temporarily deactivated. Can be reactivated. * **`closed`** — the account is permanently closed. This is a terminal state and cannot be undone. **Consumer vs. Commercial Accounts** The `entities.account_holder_type` field (`consumer` or `commercial`) is derived from the entity types you supply — it is not set directly. Individual entities produce `consumer`; business or sole proprietor entities produce `commercial`. All entries in `account_holders` must share the same category — every entry an individual, or every entry a business or sole proprietor. Mixing an individual entity with a business or sole proprietor entity is not permitted, but business and sole proprietor entities may be combined within the same account. The underlying entity ID lists are not returned on the account object; to see which entities are linked and in which role, use the entity relationships endpoint. **Entity Prerequisites** Entities must exist in Lead's system before you can reference them in an account. Call the Entity API first to create entity records, then use the `entity_`-prefixed IDs in the `entities.account_holders`, `entities.authorized_signers`, and `entities.authorized_users` arrays of your account creation request. **Credit Accounts Require an Approved Application** For accounts with the `credit_with_underwriting` capability, the `application_id` field is required and must reference an application in `approved` status. Create the application through the Applications API before creating the account. # Accounts API Validation Rules and Errors Source: https://docs.lead.bank/products/accounts/validations Synchronous 422 validation responses for the Lead Accounts API, including required fields, capability rules, and the invalid_parameters error format. ## Overview All validation failures on the Accounts API are returned synchronously. Business logic errors return `422` responses with an `invalid_parameters` array that identifies which fields failed and why, so you can correct the request before retrying. ```json theme={null} { "code": "parameters_invalid", "title": "Your request parameters did not validate.", "detail": "The request is well-formed but contains semantic errors.", "invalid_parameters": [ { "parameter": "capabilities", "reason": "Account is missing required capabilities field" } ] } ``` *** ## POST /v0/accounts ### Required Fields | Parameter | Validation Rule | Error Reason | | :- | :- | :- | | `capabilities` | Required; minimum 1 value | `Account is missing required capabilities field` | | `entities.account_holders` | Required; minimum 1 element | `Account is missing required account_holders field` | | `details` | Required object | `property "details" is missing` | | `details.product_name` | Required | `property "product_name" is missing` | | `documents` | Required array (empty array is valid) | `Account is missing required documents field` | | `Idempotency-Key` header | Required on `POST`, `PATCH`, and `DELETE` | 400 `operation_not_allowed`, with `Idempotency-Key` named in `invalid_parameters` | *** ### Capability-Driven Validations Capabilities determine which additional fields are required. Your program may be configured to have one or more supported\_capabilities available to accounts you create. The `credit_with_underwriting` capability triggers the credit validation set. | Parameter | Validation Rule | Error Reason | | :- | :- | :- | | `application_id` | Required when capabilities include `credit_with_underwriting` | `application_id is required for credit_with_underwriting capability` | | `application_id` | Must reference an application in `approved` status | `application_id is not linked to an approved application` | | `details.credit` | Required object when capabilities include `credit_with_underwriting` | `missing parameter details.credit, which is required for credit_with_underwriting capability` | | `details.credit.is_secured` | Required within `credit` object | `missing parameter is_secured, which is required for credit capabilities` | | `details.credit.is_mla` | Required within `credit` object | `missing parameter is_mla, which is required for credit capabilities` | | `details.credit.currency` | Required within `credit` object. Must be a valid ISO 4217 code | `missing parameter currency, which is required for credit capabilities` | | `details.credit.underwriting_grade` | Required within `credit` object | `missing parameter underwriting_grade, which is required for credit capabilities` | | `details.credit.available_credit` | Required within `credit` object | `missing parameter available_credit, which is required for credit capabilities` | | `details.credit.limit` | Required within `credit` object | `missing parameter limit, which is required for credit capabilities` | | `details.credit.max_limit` | Required within `credit` object | `missing parameter max_limit, which is required for credit capabilities` | | `capabilities` | `credit_with_underwriting` requires at least one account holder with adult `account_holder` role eligibility. An account cannot add credit capabilities if every account holder is eligible only for `minor_account_holder`. Evaluated on POST, and on PATCH when `capabilities` is supplied. | `Account requires at least one adult account_holder-eligible account holder (account_requires_adult_account_holder)` | The adult account holder check evaluates computed role eligibility — the same evaluation surfaced in the Entity API's `role_details` — not the `intended_roles` submitted at entity creation. An adult `authorized_signer` on the account does not satisfy this requirement; the adult must hold `account_holder` eligibility. Any `account_holder`-eligible entity — an individual 18 or older, or a business or sole proprietorship — satisfies it. *** ### Entity Validations | Parameter | Validation Rule | Error Reason | | :- | :- | :- | | `entities.account_holders` | All entity IDs must resolve to existing entities | `expected N account holder entities but only M resolved successfully; one or more entity IDs were not found` | | `entities.authorized_signers` | All entity IDs must resolve to existing entities | `expected N authorized signer entities but only M resolved successfully; one or more entity IDs were not found` | | `entities.authorized_users` | All entity IDs must resolve to existing entities | `expected N authorized user entities but only M resolved successfully; one or more entity IDs were not found` | | `entities.account_holders` | Cannot mix individual entities with business or sole\_prop entities. business and sole\_prop entities may be combined. | `account holders contain mixed entity categories; all must be individuals (consumer) or all must be business and/or sole_prop (commercial). business and sole_prop entities may be combined within the commercial category.` | | `entities.authorized_signers` | Required (min 1) when account holders are business or sole proprietor entities | `Commercial account must have at least one authorized signer` | | Entity role requirements | Each entity must have the role eligibility corresponding to its relationship type. `entities.account_holders` may resolve to entities with either `account_holder` or, for approved programs, `minor_account_holder` eligibility. | `One or more entities have incorrect role assignments` | *** ### Application Match Validations When `application_id` is provided, the following must match between the application and the account: | Parameter | Validation Rule | Error Reason | | :- | :- | :- | | `application_id` | Referenced application must exist | `The referenced application was not found` | | `application_id` | Referenced application must be in `approved` status | `application_id is not linked to an approved application` | | Account holder type | Must match between the application and the account | `Account holder type does not match the linked application` | | Account holders, Authorized Signers | Must match between the Application and the Account on initial Account Creation | `Account Holders and Authorized Signers must match between the application and account on account creation. These may be changed via PATCH requests over the Account's lifecycle.` | *** ### Field Validations | Parameter | Validation Rule | Error Reason | | :- | :- | :- | | `details.credit.report.score` | If `report` object is provided, score is required; maximum value is 850 | `CreditScore is required with credit_pulled_at and credit_report_source, maximum value is 850` | | `details.credit.report.pulled_at` | Required when `report` object is provided | `CreditPulledAt is required with credit_score and credit_report_source, must be valid ISO8601 datetime` | | `details.credit.report.source` | Required when `report` object is provided; must be `equifax`, `experian`, or `transunion` | `CreditReportSource is required with credit_score and credit_pulled_at, must be one of: equifax, experian, transunion` | | `details.adverse_action_notice` | All three AAN fields required together (`delivered_at`, `reason`, `delivery_method`) or none | `Either all three adverse action fields are required or none` | | `details.adverse_action_notice` | Required when `status_reason` is `client_closed` | `Adverse action notice is required when status_reason is client_closed` | | `details.credit.scra.start_date` | Required when `scra` object is provided | `scra start_date is required when scra object is provided` | *** ## PATCH /v0/accounts/id | Validation | Error | | :- | :- | | Account must not be in `closed` status | 422 `parameters_invalid`: `Closed accounts may not be updated` | | After applying the patch, account must still satisfy all capability-driven validations | 422 `parameters_invalid` with specific field errors | | `documents`, if provided, replaces the entire list; each entry must be a valid `ComplianceDocument` | 422 `parameters_invalid` with document-level errors | | `capabilities`, if provided, can only add new capabilities (existing capabilities cannot be removed) | 422 `parameters_invalid`: `Capabilities cannot be removed from an account` | | If `capabilities` adds `credit_with_underwriting`, the account must include at least one adult `account_holder`-eligible account holder | 422 `parameters_invalid`: `account_requires_adult_account_holder` | *** ## Status Transition Validations | Endpoint | Validation Rule | Error Code | | :- | :- | :- | | `POST /v0/accounts/{id}/deactivate` | `status_reason` is required; must be `dormant`, `frozen`, or `other` | 422 `parameters_invalid` | | `POST /v0/accounts/{id}/close` | `status_reason` is required; must be `entity_closed`, `client_closed`, `paid_off`, `charged_off`, or `canceled` | 422 `parameters_invalid` | *** ## GET /v0/accounts/id | Validation | Error | | :- | :- | | `id` must match the pattern `^account_\w+$` | 400 `parameters_invalid`: `The format of the account ID is invalid.` | | Account must exist | 404: `The requested account was not found` | *** ## Authentication | Scenario | Error | | :- | :- | | Using an `account/read` token to call a write endpoint (`POST`, `PATCH`) | 403 `insufficient_scope` | | Using an unrelated scope token (e.g., `lending/read`) | 403 `insufficient_scope` | | Using an invalid or expired token | 403 `token_invalid` | # The ACH Object Source: https://docs.lead.bank/products/ach/ach-object Field-level reference for the ACH object, including amounts, counterparty details, SEC codes, and status fields. ```json theme={null} { "id": "ach_xyz001", "created_at": "2022-06-27T11:22:33Z", "updated_at": "2022-06-27T11:22:33Z", "status": "submitted", "amount": 5000, "account_id": "account_xyz123", "account_number_id": "account_number_xyz123", "direction": "outgoing", "delivery_type": "same_business_day", "transaction_type": "credit", "sec_code": "WEB", "currency_code": "USD", "statement_descriptor": "P2P Credit", "record_details": { "transaction_code": "checking_credit", "company_name": "Acme Inc.", "company_id": "1234", "company_discretionary_data": "Acme Inc.", "effective_date": "2022-06-27", "settlement_date": "2022-06-27", "individual_id": "string", "receiver_name": "string", "descriptive_date": "220627", "additional_information": "string", "trace_number": "123456789012345" }, "iat_details": { "transaction_type_code": "business", "destination_country": "CA", "originator_currency_code": "USD", "destination_currency_code": "CAD", "foreign_trace_number": "FRN-2024-98765-INTL", "additional_information": "Invoice 12345 - February 2022", "originator": { "name": "Acme Inc.", "street_address": "123 Main Street", "city_state_province": "New York*NY\\", "country_postal_code": "US*10001\\" }, "originating_financial_institution": { "name": "First National Bank", "identifier_type": "business_identifier_code", "identifier_code": "FNBUS33XXX", "branch_country": "US" }, "receiver": { "reference_number": "RCV-2024-001", "name": "Lara Smikle", "street_address": "456 Maple Avenue", "city_state_province": "Toronto*ON\\", "country_postal_code": "CA*M5H 2N2\\" }, "receiving_financial_institution": { "name": "Royal Bank of Canada", "identifier_type": "business_identifier_code", "identifier_code": "ROYCCAT2XXX", "branch_country": "CA" }, "foreign_correspondent_banks": [ { "name": "Citibank NA", "identifier_type": "business_identifier_code", "identifier_code": "CITIUS33XXX", "branch_country": "US" } ] }, "counterparty": { "name": "Lara Smikle", "account_number": "1032345678", "routing_number": "021000021", "account_type": "checking" }, "returns": [ { "type": "return", "status": "submitted", "return_code": "R02", "return_reason": "string", "trace_number": "123456789012345", "additional_information": "string" } ], "reversal": { "reversal_reason": "duplicate", "linked_ach_id": "string" }, "rejection": { "reason": "account_number_status", "details": "Account number account_123 is inactive." }, "correction": { "account_number": "1032345678", "routing_number": "021000021", "account_type": "checking" }, "metadata": { "additionalProp": "string" } } ``` # Returns, Reversals, & Exceptions Source: https://docs.lead.bank/products/ach/exceptions Details about processing or receiving ACH returns. Most ACH transfers post without issue. This page covers the three exception flows for when one doesn't: * **Return**: the receiving bank sends a transfer back, for reasons like a closed account, insufficient funds, or an unauthorized debit. You can return transfers you receive, and transfers you originate can be returned to you. * **Reversal**: you originated a transfer by mistake (a duplicate, a wrong amount) and initiate a correcting entry to recover the funds. * **Notification of Change (NOC)**: the receiving bank accepts your transfer but tells you a detail was incorrect, and provides the corrected value to use on future transfers. A few Nacha terms appear throughout: * **Originator**: the person or business that initiates an ACH transfer. * **ODFI** (Originating Depository Financial Institution): the bank that sends a transfer into the ACH network. * **RDFI** (Receiving Depository Financial Institution): the bank that receives it. ## Returns You can return an ACH transfer you received for any valid reason using [`POST /v1/ach/{ach_id}/return`](/api-reference/endpoint/ach/return-an-ach). External banks can likewise return transfers you originate; those arrive as status changes and webhooks on the original transfer (see [Statuses](/products/ach/statuses)). The deadline depends on the return reason: * **Standard returns** must be available to the ODFI by the opening of business on the second banking day after the original settlement date. * **Unauthorized debit returns** (R05, R07, R10, R11) have until the opening of business on the 60th calendar day after settlement, and require a signed Written Statement of Unauthorized Debit (WSUD). Obtain the WSUD before initiating the return and retain it for at least one year from the settlement date. You can submit a return before the original transfer reaches `posted`. Lead accepts the return request immediately, but does not send it to the Fed until the original transfer posts. ### Return Codes The `return_code` you pass to [`POST /v1/ach/{ach_id}/return`](/api-reference/endpoint/ach/return-an-ach) determines what the call does: a standard code initiates a return, a dishonor code dishonors an existing return, and a contest code contests an existing dishonored return. In every case you target the original transfer's `ach_id`, and the code must match the transfer's current position in the [return chain](/products/ach/statuses). > [!TIP] > > The complete list of return codes is in the [Nacha Operating Rules and Guidelines](https://nachaoperatingrulesonline.org/pubchange). **Standard return codes** initiate a return against a transfer you received: | Code | Description | Timing | WSUD Required | | - | - | - | - | | **R01** | Insufficient Funds | 2 Banking Days | No | | **R02** | Account Closed | 2 Banking Days | No | | **R03** | No Account / Unable to Locate Account | 2 Banking Days | No | | **R05** | Unauthorized Debit Using Corporate SEC Code | 60 Calendar Days | Yes | | **R07** | Authorization Revoked by Customer | 60 Calendar Days | Yes | | **R08** | Payment Stopped | 2 Banking Days | No | | **R09** | Uncollected Funds | 2 Banking Days | No | | **R10** | Customer Advises Originator is Not Known/Not Authorized | 60 Calendar Days | Yes | | **R11** | Authorization Revoked / Improperly Initiated Reversal | 60 Calendar Days | Yes | | **R14** | Representative Payee Deceased/Unable to Continue | 2 Banking Days | No | | **R15** | Beneficiary or Account Holder Deceased | 2 Banking Days | No | | **R16** | Account Frozen / Entry Returned per OFAC | 2 Banking Days | No | | **R17** | File Record Edit Criteria | 2 Banking Days | No | | **R22** | Invalid Individual ID Number | 2 Banking Days | No | | **R23** | Credit Entry Refused by Receiver | 2 Banking Days | No | | **R29** | Corporate Customer Advises Not Authorized | 2 Banking Days | No | A return can itself be disputed, and both sides of that dispute run through the same endpoint. Submitting a dishonor or contest code moves the original transfer through the corresponding return chain statuses (`pending_dishonored_return`, `return_dishonored`, `pending_contested_return`, `return_contested`). **Dishonored return codes** dishonor a return you received against a transfer you originated. Submit within 5 banking days of the return settling: | Code | Description | | - | - | | **R61** | Misrouted return | | **R62** | Return of erroneous or reversing debit | | **R67** | Duplicate return | | **R68** | Untimely return | | **R69** | Field error(s) | | **R70** | Permissible return entry not accepted / Return not requested by ODFI | **Contested dishonored return codes** contest a dishonor of a return you issued. Submit within 2 banking days of the dishonor settling: | Code | Description | | - | - | | **R71** | Misrouted dishonored return | | **R72** | Untimely dishonored return | | **R73** | Timely original return | | **R74** | Corrected return | | **R75** | Return not a duplicate | | **R76** | No errors found | | **R77** | Non-acceptance of R62 dishonored return | ### Late Returns If you suspect a debit from one of your accounts was unauthorized but the return window has passed, contact Lead promptly with documentation showing the authorization is invalid. Lead will review the request and, if appropriate, ask the ODFI for permission to make a late return. The same process can run against you as an Originator. Nacha requires Originators to retain proof of authorization for two years after the settlement date of the last debit, so keep authorization records ready to support or dispute late return requests. ## Reversals Use a reversal to correct a transfer you originated in error: a duplicate payment, a wrong amount, or a wrong receiver. Initiate it with [`POST /v1/ach/{ach_id}/reverse`](/api-reference/endpoint/ach/reverse-an-ach) within five banking days of the original settlement date. Reversals are only for genuine mistakes; never use them to claw back a transaction you believe is unauthorized (that is a return, initiated by the receiving side). How reversals behave: * A reversal is a separate ACH transfer with its own lifecycle and the same [statuses](/products/ach/statuses) as any other transfer. * The original transfer is annotated with a [reversal object](https://docs.lead.bank/api-reference/endpoint/ach/create-an-ach#response-reversal) containing the reversal reason and the [ID of the reversal transfer](https://docs.lead.bank/api-reference/endpoint/ach/create-an-ach#response-reversal-linked-ach-id). * No webhooks fire on the original transfer when a reversal is created. Watch the reversal transfer for status webhooks. * A reversal can itself be returned by the receiving bank. ### Return or Reversal? Who made the mistake determines the tool. If you originated it, reverse it. If you received it, return it. | Scenario | Lead's role | Action | | :- | :- | :- | | You sent the same ACH credit twice and need the funds back from the duplicate. | ODFI (credit, push) | Reversal, within five banking days | | You receive an ACH credit you don't recognize and suspect fraud. | RDFI (credit, push) | Return | | You pull scheduled ACH debits from a counterparty, and one was a mistake you need to send back. | ODFI (debit, pull) | Reversal, within five banking days | | A service provider you previously authorized pulls a debit you believe is in error. | RDFI (debit, pull) | Return | ## Notifications of Change Instead of returning a transfer, an RDFI can accept and post it but send back a Notification of Change (NOC): a notice that a detail of the transfer was incorrect, along with the corrected value to use on all future transfers to that receiver. You don't need to parse Nacha change codes. Lead normalizes each NOC into a `correction` object on the original ACH transfer, containing only the fields that changed. At least one field will be present: ```json theme={null} "correction": { "account_number": "1032345678", "routing_number": "021000021", "account_type": "checking" } ``` * `account_number`: the corrected counterparty account number. * `routing_number`: the corrected counterparty routing number. * `account_type`: the corrected counterparty account type, `checking` or `savings`. RDFIs must send an NOC within two banking days of the original entry's settlement date, and Lead delivers it to you within two banking days of settlement. Corrections arrive daily via webhook, the Return/NOC file, or Online Banking. ### What You Must Do * The transfer that triggered the NOC processes as usual; no action is needed on it. * Update your counterparty records with the corrected values within six banking days of receiving the correction, or before initiating the next transfer to that receiver, whichever is later. Originators of one-time payments are exempt. * Do not keep using the old details. Lead may reject a subsequent transfer to a corrected counterparty with the rejection reason `previously_corrected`, which references the ACH that carried the correction. Lead also monitors NOC activity and may reach out if the same correction keeps arriving. > [!TIP] > > Manage the corrections you receive proactively. If you have questions or see unexpected activity, contact Lead as soon as possible. Unmanaged NOCs carry real consequences: Nacha may impose monetary penalties depending on frequency and volume. Those fines may be charged to you under the Lead ACH Agreement, and Nacha can bar repeat violators from the ACH network. ### Mapping to Nacha Change Codes If you reconcile against raw Nacha data, such as the Return/NOC file, the common change codes map to `correction` fields as follows: | Nacha code | What was incorrect | `correction` fields populated | | :- | :- | :- | | C01 | Account number | `account_number` | | C02 | Routing number | `routing_number` | | C03 | Routing number and account number | `routing_number`, `account_number` | | C05 | Account type (transaction code) | `account_type` | | C06 | Account number and account type | `account_number`, `account_type` | | C07 | Routing number, account number, and type | `routing_number`, `account_number`, `account_type` | # Managing Originators Source: https://docs.lead.bank/products/ach/managing-originators Create, update, activate, deactivate, and cancel ACH Originators. | **Endpoint** | **Description** | | :- | :- | | `POST /v0/originators` | Create an Originator. Requires `entity_id`, `account_id`, `company_name`, and `ach`. | | `GET /v0/originators` | List all Originators. | | `GET /v0/originators/{originator_id}` | Retrieve an Originator. | | `PATCH /v0/originators/{originator_id}` | Update an Originator. | | `POST /v0/originators/{originator_id}/activate` | Activate an Originator. | | `POST /v0/originators/{originator_id}/deactivate` | Deactivate an Originator. | | `POST /v0/originators/{originator_id}/cancel` | Permanently cancel an Originator. | An Originator can originate ACH only while it is `active`; see [Originator Statuses](/products/ach/originator-statuses) for the full lifecycle. # The Originator Object Source: https://docs.lead.bank/products/ach/originator-object Field-level reference for the Originator object, which carries your ACH origination parameters. ```json theme={null} { "id": "string", "account_id": "string", "entity_id": "string", "company_id": "string", "company_name": "string", "status": "pending", "ach": { "allowed_sec_codes": [ "WEB" ], "nested_third_parties": [ "entity_xyz123" ], "limits": { "calendar_day_maximum_amount": { "credit": 0, "debit": 0 }, "rolling_30_calendar_day_maximum_amount": { "credit": 0, "debit": 0 } } }, "metadata": {}, "created_at": "2022-06-27T11:22:33Z", "updated_at": "2022-06-27T11:22:33Z" } ``` ## Attributes | **Attribute** | **Type** | **Description** | | - | - | - | | id | string | ID of the Originator object. | | account\_id | string | The ID of the Account object that originated ACH transactions will settle to. | | entity\_id | string | The ID of the Entity object that represents the identity of the owner of the Originator. | | company\_id | string | A 10-digit unique identifier used to identify the company in ACH transactions. This value populates the Company Identification field in ACH batch headers. | | company\_name | string | The name of the company initiating ACH transactions. This value populates the Company Name field in ACH batch headers and may appear on counterparty bank statements. | | status | string | The current status of the Originator object. Possible values: `pending`, `active`, `inactive`, `rejected`, `suspended`, `canceled`. See [Originator Statuses](/products/ach/originator-statuses). | | ach | object | Configuration and limits specific to ACH transaction origination. | | allowed\_sec\_codes | array of strings | The Standard Entry Class (SEC) codes this Originator is permitted to use when initiating ACH transactions. Possible values: `CCD`, `PPD`, `WEB`, `CIE`, `TEL`. | | nested\_third\_parties | array of strings | A list of Entity IDs representing third parties that this Originator is authorized to initiate ACH transactions on behalf of. Used in payment facilitation or nested third-party payment models. | | limits | object | Transaction limits governing the Originator's ACH activity. All amounts are in cents. | | calendar\_day\_maximum\_amount | object | The maximum total amount the Originator can initiate within a single calendar day. `credit`: (int64) Maximum daily credit amount in cents. `debit`: (int64) Maximum daily debit amount in cents. | | rolling\_30\_calendar\_day\_maximum\_amount | object | The maximum total amount the Originator can initiate within a rolling 30 calendar day period. `credit`: (int64) Maximum rolling 30-day credit amount in cents. `debit`: (int64) Maximum rolling 30-day debit amount in cents. | | metadata | object | A set of key-value pairs that can be used to store additional information related to this Originator. Useful for internal references, tagging, or integration with external systems. | # Originator Statuses Source: https://docs.lead.bank/products/ach/originator-statuses Statuses and lifecycle transitions for ACH Originators. | **Status** | **Description** | | :- | :- | | `pending` | The Originator has been created and is not yet active. | | `active` | The Originator can be used to originate ACH transactions. | | `inactive` | The Originator has been deactivated and cannot originate. It can be reactivated. | | `rejected` | The Originator was not approved for use. | | `suspended` | Lead has suspended the Originator. Contact your Technical Account Manager. | | `canceled` | The Originator has been permanently canceled. This is a terminal status. | Status changes do not fire webhooks; poll `GET /v0/originators/{originator_id}` to observe them. # Originators: Managing ACH Origination Parameters Source: https://docs.lead.bank/products/ach/originators Create and manage ACH origination parameters. > [!NOTE] > > If you only originate ACH from a single ACH Company ID, you will **not** need to create Originators.\ > \ > If you require the ability to originate ACH from multiple ACH Company IDs, please work with your implementations manager to request access and approval to use the Originator API. An Originator defines required parameters that allow authorized partners to initiate ACH transactions through Lead's FedACH connection. Originators are tied to a specific Account and Entity, and define the permissions, SEC codes, and transaction limits governing their ACH activity. ## How an Originator Is Used An Originator takes effect through the Account Numbers that send ACH. Once your Originator is [`active`](/products/ach/originator-statuses), set `ach_controls.originator_id` on each sending Account Number (see [Payment Controls](/products/account-number/controls)). Outgoing entries from those Account Numbers then carry that Originator's `company_id` and `company_name` in the ACH batch header, subject to its `allowed_sec_codes` and limits. See [Sending ACH](/products/ach/sending-ach) for the full origination flow. # ACH at Lead: Transfers Over FedACH Source: https://docs.lead.bank/products/ach/overview Receive or send ACH transfers through the FedACH network. > [!NOTE] > > **Upcoming change** > > Lead is making more of the ACH lifecycle visible. ACH entries will show events that were hidden before, new statuses, and dishonored and contested returns. If you use ACH statuses or webhooks, update your integration before Lead enforces the change in Q4 2026. > > See [ACH status lifecycle expansion](/upcoming-changes#ach-status-lifecycle-expansion) on Upcoming Changes. The FedACH system, operated by the Federal Reserve, is an electronic payment network that processes Automated Clearing House (ACH) transactions in the United States, clearing and settling payments through multiple processing windows each business day. Lead has a direct connection to the FedACH network. **Use ACH when** you need a low-cost, high-volume rail for recurring payments, payroll, loan disbursements, or consumer-initiated transfers where same-day or next-day settlement is acceptable. ACH is the only Lead rail on which a posted payment can later be returned; plan for [returns](/products/ach/exceptions) as part of your integration, not as an exception. **What you can do:** [send outgoing credits and debits](/products/ach/sending-ach) with a `delivery_type` of [`same_business_day` or `next_business_day`](/products/ach/timing); [receive incoming entries](/products/ach/receiving-ach); cancel an outgoing entry while it is still cancellable; return incoming entries, reverse your own erroneous entries, and handle [Notifications of Change](/products/ach/exceptions). For outgoing ACH, Lead supports the CCD, PPD, TEL, WEB, and CIE SEC codes; incoming entries may additionally carry IAT for cross-border transactions; Lead does not originate outgoing IAT. Sending your first ACH end-to-end is covered in [Make Your First Payment API Call](/get-started/quickstart/make-your-first-payment-api-call). # Receiving ACH Source: https://docs.lead.bank/products/ach/receiving-ach Handle incoming ACH credits and debits: controls, statuses, webhooks, and returning entries you do not want. Incoming ACH entries are originated by external institutions, so there is no endpoint to call: entries addressed to your Account Numbers arrive on their own. Each one appears as an [ACH object](/products/ach/ach-object) with an `incoming` direction, and webhooks tell you when one arrives and posts. An incoming **credit** deposits funds into your account; an incoming **debit** pulls funds out, under an authorization your customer gave the originator. ## Controlling What You Accept Each Account Number's [ACH controls](/products/account-number/controls) govern what it can receive: * `incoming.accept_credit` and `incoming.accept_debit`, both `true` by default. When `accept_debit` is `false`, inbound debits are automatically returned with return code `R16`. * `incoming.counterparty_filter`: accept all counterparties (default), an allowlist of company IDs, or reject all. ## Endpoints You don't call anything to receive an entry, but these endpoints are how you observe and act on incoming activity: | **Endpoint** | **Description** | | :- | :- | | `GET /v1/ach?direction=incoming` | List incoming entries. Also filterable by `account_number_id`, `status`, and `created_at`. | | `GET /v1/ach/{ach_id}` | Retrieve a single entry, for example when a webhook delivers its ID. | | `POST /v1/ach/{ach_id}/return` | Return an incoming entry you don't want. | ## Statuses Incoming entries have a shorter lifecycle than outgoing: `scheduled` → `posted`, with a manual review detour when a validation rule requires it. Incoming entries cannot be canceled. The table below is an excerpt; [ACH Statuses](/products/ach/statuses) is the canonical reference, including the return chain. | **Status** | **Description** | **Webhook** | | :- | :- | :- | | `scheduled` | Lead accepted the incoming entry; it is waiting to post. | `ach.scheduled` | | `under_review` | A validation rule triggered manual review by Lead Payment Ops. | `ach.under_review` | | `rejected` | The entry failed validation or manual review and will not post. Terminal. | `ach.rejected` | | `posted` | The entry posted: a credit was deposited, or a debit was withdrawn. | `ach.posted` | See the [incoming transition diagram](/products/ach/statuses#incoming-ach-transitions) for the full lifecycle, including the return chain. ## Events | **Event** | **What happened** | **Recommended action** | | :- | :- | :- | | `ach.scheduled` | An incoming entry arrived and was accepted. | Record it. If it's an unexpected debit, evaluate whether to return it once posted. | | `ach.under_review` | The entry is in manual review. | Wait. Lead may reach out for more information. | | `ach.rejected` | The entry will not post. | No funds moved. Nothing to reconcile. | | `ach.posted` | Funds moved. | Update balances in your system. For debits, confirm the pull was authorized. | | `ach.pending_return` / `ach.returned` | A return of this entry is in progress or complete. | Reconcile the reversal of funds. | ## Returning Entries You Don't Want You can return any incoming entry, most commonly an unauthorized or erroneous debit, with `POST /v1/ach/{ach_id}/return` and an appropriate return code. Deadlines are strict: standard returns have two banking days from settlement, and unauthorized debit returns have sixty calendar days plus a signed WSUD. See [Returns, Reversals, & Exceptions](/products/ach/exceptions) for codes, deadlines, and cutoffs. You can submit the return before the entry reaches `posted`; Lead holds it and sends it to the Fed once the original posts. > [!NOTE] > > Incoming entries may carry the `IAT` SEC code for cross-border transactions, with the additional detail in the object's `iat_details`. Lead does not originate outgoing IAT. ## Testing in Sandbox Trigger an incoming entry with `POST /v1/simulate/ach/incoming_ach`, and simulate a counterparty returning one of your outgoing entries with `POST /v1/simulate/ach/{ach_id}/incoming_return`. See [Sandbox Testing](/products/ach/sandbox). # Sandbox Testing Source: https://docs.lead.bank/products/ach/sandbox Test ACH transactions. ## Sandbox Simulation > Move test ACH transfers through their full lifecycle and receive the same webhooks you'll see in production. In production, an ACH transfer moves through its lifecycle automatically based on network timing. In sandbox, transfers are not submitted to the Federal Reserve, so they don't progress on their own. Instead, you advance each transfer manually using simulation endpoints. Each status change fires the same webhook you'll receive in production, so you can test your webhook handling, status polling, and reconciliation logic end to end. Before testing, review [ACH Statuses](/products/ach/statuses) so you know which statuses to expect at each step. ## Simulation Endpoints These endpoints exist only in the sandbox. They return `404` in production. | Action | Endpoint | | - | - | | Advance an ACH to its next status | `POST /v1/simulate/ach/{ach_id}/advance` | | Trigger an incoming ACH | `POST /v1/simulate/ach/incoming_ach` | | Trigger an incoming ACH return | `POST /v1/simulate/ach/{ach_id}/incoming_return` | > [!NOTE] > > A transfer in the `under_review` status cannot be advanced. This applies to all transfers, incoming and outgoing, including returns. Manual review is not simulated in the sandbox, so a transfer that enters `under_review` will stay there. If this happens, create a new test transfer, and see [Validations & best practices](/products/ach/validations) for how to avoid triggering a review. ## Test an Outgoing ACH 1. Create the transfer with the standard endpoint: `POST /v1/ach`. The transfer enters the `scheduled` status and stays there until you advance it. 2. Advance it with `POST /v1/simulate/ach/{ach_id}/advance`. Each call moves the transfer to the next status in the production lifecycle: `scheduled → processing → submitted → posted`. Three advance calls take a transfer from `scheduled` to `posted`. 3. Confirm you receive the expected webhook after each advance before making the next call. > [!TIP] > > Wait several minutes between the create call and each advance call. The sandbox uses the same batch-based processing as production, and each status change runs validations that take a few minutes to complete. If you advance a transfer before the previous step finishes, webhooks may arrive duplicated or out of order. ## Test an Incoming ACH Use `POST /v1/simulate/ach/incoming_ach` to create an incoming transfer to one of your accounts. In production, this is a transfer another institution originates, so there is no standard endpoint to create one yourself. ## Test Returns Use `POST /v1/simulate/ach/{ach_id}/incoming_return` to simulate a return initiated by the other institution. To initiate a return yourself, use the standard return endpoint described in [Returns, Reversals, & Exceptions](/products/ach/exceptions). ## What Is and Isn't Real * No funds move, and Fed processing windows don't apply. You control timing entirely through the advance endpoint. * Everything else behaves like production: statuses, webhooks, and validation behavior match what your integration will see live. # Sending ACH Source: https://docs.lead.bank/products/ach/sending-ach Send outgoing ACH credits and debits: request requirements, statuses, webhooks, and cancellation. An outgoing ACH is either a **credit**, which pushes funds from your account to the counterparty, or a **debit**, which pulls funds from the counterparty into your account. ## Prerequisites * **Origination is configured at onboarding.** Your ACH originator identity (company name and company ID) is set up on your program by your Technical Account Manager. You do not pass originator details on requests. * Your token needs the `ach/read_write` scope. * The sending Account Number must be `active`, and its [outgoing ACH controls](/products/account-number/controls) must permit the counterparty. By default all counterparties are permitted. > [!NOTE] > > The [Originator API](/products/ach/originators) is only for programs that create and maintain additional originators as part of a third-party sending setup. Most programs never call it. ## Endpoints | **Endpoint** | **Description** | | :- | :- | | `POST /v1/ach` | Create an outgoing ACH. Requires an `Idempotency-Key` header. | | `POST /v1/ach/{ach_id}/cancel` | Cancel an outgoing ACH that is still in a cancellable status. | | `POST /v1/ach/{ach_id}/reverse` | Reverse an erroneous entry you originated, within five banking days of settlement. | ## Request Requirements | **Field** | **Requirement** | | :- | :- | | `account_number_id` | The Account Number the funds leave (credit) or arrive in (debit). | | `amount` | Amount in cents. Same Day ACH is capped at \$1,000,000 per transfer; larger same-day requests process as next-day. | | `currency_code` | ISO 4217 code. | | `transaction_type` | `credit` (push funds to the counterparty) or `debit` (pull funds from the counterparty). | | `delivery_type` | `same_business_day` or `next_business_day`. Determines the cutoff schedule; see [Timing & Availability](/products/ach/timing). | | `sec_code` | One of `CCD`, `PPD`, `TEL`, `WEB`, `CIE`. Incoming entries may additionally carry `IAT`, but Lead does not originate outgoing IAT. | | `statement_descriptor` | The description that appears on the counterparty's statement. | | `counterparty` | Object with `name`, `routing_number`, `account_number`, and `account_type` (`checking` or `savings`). | Optional fields include `individual_id`, `descriptive_date`, `additional_information`, and `metadata`. See [Create an ACH](/api-reference/endpoint/ach/create-an-ach) for the full schema and [The ACH Object](/products/ach/ach-object) for every response field. ```json theme={null} { "account_number_id": "account_number_xyz", "amount": 5000, "currency_code": "USD", "transaction_type": "credit", "delivery_type": "next_business_day", "sec_code": "PPD", "statement_descriptor": "PAYMENT", "counterparty": { "name": "Jordan Smith", "routing_number": "021000021", "account_number": "9900000001", "account_type": "checking" } } ``` A successful response returns the ACH object in the `scheduled` status. ## Statuses The happy path for an outgoing ACH is `scheduled` → `processing` → `submitted` → `posted`. Entries that trip a validation rule detour through manual review. The table below is an excerpt; [ACH Statuses](/products/ach/statuses) is the canonical reference, including the return chain. | **Status** | **Description** | **Cancellable** | **Webhook** | | :- | :- | :- | :- | | `scheduled` | Accepted by Lead, waiting for further processing. | Yes | `ach.scheduled` | | `processing` | Lead is preparing the entry for submission to the Fed. | No | `ach.processing` | | `submitted` | Submitted to the Fed for processing. | No | `ach.submitted` | | `posted` | Completed and posted to the receiving bank account. Funds at another bank may take a few hours to appear. | No | `ach.posted` | | `under_review` | A validation rule triggered manual review by Lead Payment Ops. | Yes | `ach.under_review` | | `approved` | Manual review passed; the entry continues processing. | Yes | `ach.approved` | | `rejected` | Validation or manual review failed. Terminal. | No | `ach.rejected` | | `canceled` | You canceled the entry before Lead began processing it. Terminal. | No | `ach.canceled` | See the [outgoing transition diagram](/products/ach/statuses#outgoing-ach-transitions) for the full lifecycle, including the return chain. ## Events Act on webhooks rather than assuming success from the 200: | **Event** | **What happened** | **Recommended action** | | :- | :- | :- | | `ach.under_review` | The entry is in manual review. | Wait. Lead may reach out for more information. Cancel if no longer needed; see [Validations](/products/ach/validations) to avoid reviews. | | `ach.rejected` | The entry will not process. | Inspect `rejection.reason` and `rejection.details`, fix the issue, and resubmit if appropriate. | | `ach.posted` | The transfer completed. | Mark the payment settled in your system. | | `ach.pending_return` / `ach.returned` | The receiving bank is returning a posted entry. | Handle per [Returns, Reversals, & Exceptions](/products/ach/exceptions). | | `ach.corrected` | A Notification of Change arrived for this entry. | Update your counterparty records from the `correction` object before the next transfer. | ## Testing in Sandbox Outgoing ACH does not advance automatically in sandbox: entries stay in `scheduled` until you advance them with `POST /v1/simulate/ach/{ach_id}/advance`. See [Sandbox Testing](/products/ach/sandbox) for the sequence and timing. # ACH Statuses Source: https://docs.lead.bank/products/ach/statuses Description of ACH statuses and transitions. ## ACH Statuses | **Status** | **Direction** | **Description** | **Cancellable** | | - | - | - | - | | **scheduled** | Incoming, Outgoing | The ACH has been accepted by the Lead platform and is waiting for further processing. | Incoming: N Outgoing: Y | | **processing** | Outgoing | The Lead platform is preparing the ACH for submission to the Fed for processing. | N | | **submitted** | Outgoing | The Lead platform has submitted the ACH transfer for Fed processing. | N | | **posted** | Incoming, Outgoing | The ACH transfer has successfully completed and has been posted to the receiving bank account. *For outbound, if the receiver is at a different bank, the funds may take a few hours to appear.* | N | | **canceled** | Outgoing | The ACH transfer has been cancelled and will not be processed. This is a terminal status. | N | | **under\_review** | Incoming, Outgoing | The ACH transfer has triggered a validation rule that requires further review by the Lead Payment Ops team. Please see best practices on how to avoid this status. We may reach out to you for additional information. | Incoming: N Outgoing: Y | | **approved** | Outgoing | A successful result of a manual review. This indicates that the ACH transfer will continue to process. | Y | | **rejected** | Incoming, Outgoing | An unsuccessful result of a manual review, indicating that Lead Payment Ops has detected an issue with the ACH transfer. Review the data in the rejection hash to determine what to fix and resubmit a corrected ACH transfer if appropriate. This is a terminal status. Please reach out to support via your Slack channel if you have further questions about this decision. | N | | **pending\_return** | Incoming, Outgoing | The Lead platform has received notice that a previously posted ACH transfer is going to be returned. From here, the payment will move to `returned` if successful, or back to `posted` if not (which will not trigger a new ach.posted webhook). | N | | **pending\_dishonored\_return** | Incoming, Outgoing | A request to dishonor a previously returned ACH is in progress. | Y | | **pending\_contested\_return** | Incoming, Outgoing | A request to contest a previously dishonored return is in progress. | Y | | **returned** | Incoming, Outgoing | A return processed successfully, and the original ACH transaction is now returned. | N | | **return\_dishonored** | Incoming, Outgoing | A dishonored return processed successfully, and the original ACH transaction is now dishonored. | N | | **return\_contested** | Incoming, Outgoing | A contested return processed successfully, and the original ACH transaction is now contested. | N | ## Incoming ACH Transitions ```mermaid placement="top-left" actions={true} theme={null} graph LR start --> |If required|under_review start --> rejected under_review --> scheduled under_review --> rejected start --> scheduled scheduled --> posted posted -.->|If return initiated| pending_return pending_return -.->|Return rejected| posted subgraph Return Chain pending_return -.->|Return posts| returned returned -.->|If return is dishonored| pending_dishonored_return pending_dishonored_return -.->|Dishonor posts| return_dishonored return_dishonored -.->|If dishonor is contested| pending_contested_return pending_contested_return -.->|Contest posts| return_contested pending_contested_return -.->|Contest rejected| return_dishonored end classDef classy stroke:#555,fill:#F4F6F8,rx:12,ry:12,font-size:16px,font-weight:bold; class scheduled,posted,returned,under_review,rejected,pending_return,pending_dishonored_return,pending_contested_return,return_dishonored,return_contested classy; ``` ### Outgoing ACH Transitions ```mermaid placement="top-left" actions={true} theme={null} graph LR subgraph Manual Review under_review --> approved approved --> canceled under_review --> canceled end under_review --> rejected scheduled -.->|If required| under_review scheduled -.->|If validation fails| rejected scheduled --> processing scheduled --> canceled approved --> processing processing --> submitted submitted --> posted subgraph Return Chain pending_return --> returned returned -.->|If dishonored| pending_dishonored_return pending_dishonored_return --> return_dishonored pending_dishonored_return -.->|Dishonor rejected| returned return_dishonored -.->|If contested| pending_contested_return pending_contested_return --> return_contested end posted -.->|If returned| pending_return classDef classy stroke:#555,fill:#F4F6F8,rx:12,ry:12,font-size:16px,font-weight:bold; class scheduled,canceled,processing,submitted,posted,returned,under_review,rejected,approved,pending_return,pending_dishonored_return,pending_contested_return,return_dishonored,return_contested classy; ``` ## Types of Transfers ACH transactions can involve various types of transfers beyond standard payments. The following are specific ACH transfer types that may occur in different scenarios. | **Type** | **Description** | | - | - | | ACH return | A returned ACH item that could not be posted to the receiver's account for any reason. This can occur due to issues such as insufficient funds, closed accounts, or incorrect account details. | | Reversal | An ACH entry initiated to correct a previously originated transaction that was sent in error. Reversals should only be used for genuine mistakes, such as duplicate payments or incorrect amounts, and must not be used for unauthorized transactions. | | Dishonored return | A return entry rejected by the ODFI (Originating Depository Financial Institution). Dishonored returns are only allowed for valid reasons, such as improper or untimely returns. | | Contested dishonored return | A return entry used by the RDFI (Receiving Depository Financial Institution) to challenge a dishonored return. This process is rare and only permitted in specific circumstances, such as when an ODFI improperly dishonors a valid return. | ## Rejection Case Lifecycle In most cases, an ACH transaction will move naturally through the status lifecycle. In some instances, when a transaction requires a manual review, the originally requested action may be rejected. In this case, the ACH transaction will transition back to its original status before the action was requested. For example, if an ACH transaction is `posted` and a return is initiated, the status will transition to `pending_return` . If the return transaction requires manual review, and the review result is to reject the return request, the ACH transaction will transition back to `posted` to reflect the actual current state of the transaction. # ACH Timing & Availability Source: https://docs.lead.bank/products/ach/timing Lead's ACH processing windows, cutoff times, and how settlement timing is determined. Lead submits ACH entries to the Fed in six processing windows each business day. A transfer goes out in the next window after it passes validation, provided it reaches Lead before that window's cutoff. Cutoffs are firm: anything received after a cutoff is queued for the next available window, with no exceptions. Two things determine when a transfer settles: * **How you asked for it to be delivered.** For API transfers, the [`delivery_type`](/api-reference/endpoint/ach/create-an-ach#body-delivery-type) you choose at creation: `same_business_day` or `next_business_day`. For file submissions, the [`effective_date` fields in the file](/file-reference/balances-and-transactions/transactions-schema). * **Which window your submission lands in**, based on the cutoff times below. All times are Central Time. Business days are weekdays that are not Federal Reserve holidays; transfers submitted on a weekend or holiday settle on the next business day. Submit as early as you can ahead of a cutoff to avoid slipping into the next window. ## Same Day ACH Transfers created with `delivery_type: same_business_day` settle within hours, through the first three windows of the day: | **Lead's Cutoff** | **Settlement** | | - | - | | 9:00 a.m. CT | 12:00 p.m. CT, same business day | | 1:15 p.m. CT | 4:00 p.m. CT, same business day | | 2:00 p.m. CT | 5:00 p.m. CT, same business day | Submit before 2:00 p.m. CT on a business day to settle that day. After 2:00 p.m. CT, a same-day transfer is converted to next-day delivery and settles at 7:30 a.m. CT on the next business day. After 10:00 p.m. CT on the evening before a business day, it is instead carried in that business day's same-day windows and settles at 12:00 p.m. CT. On a weekend or holiday, it settles at 7:30 a.m. CT on the next business day. > [!NOTE] > > Nacha caps Same Day ACH at \$1,000,000 per transfer. A `same_business_day` transfer over that amount is processed as next-day. ## Next Day ACH Transfers created with `delivery_type: next_business_day` settle at 7:30 a.m. CT on the next business day, whichever of the six windows they go out in: | **Lead's Cutoff** | **Settlement** | | :- | - | | 9:00 a.m. CT | 7:30 a.m. CT, next business day | | 1:15 p.m. CT | 7:30 a.m. CT, next business day | | 3:15 p.m. CT | 7:30 a.m. CT, next business day | | 6:30 p.m. CT | 7:30 a.m. CT, next business day | | 9:15 p.m. CT | 7:30 a.m. CT, next business day | | 10:00 p.m. CT | 7:30 a.m. CT, next business day | Submit before 10:00 p.m. CT on a business day to settle at 7:30 a.m. CT the next business day. After 10:00 p.m. CT, the transfer misses the overnight window: it is processed with the next day's transfers and settles at 7:30 a.m. CT on the business day after that. For example, a transfer submitted Tuesday at 10:30 p.m. CT settles Thursday morning, while a transfer submitted late Friday night still settles Monday. ## ACH Returns Returns use all six windows and settle same-day through the 3:15 p.m. CT window: | **Lead's Cutoff** | **Settlement** | | :- | :- | | 9:00 a.m. CT | 12:00 p.m. CT, same business day | | 1:15 p.m. CT | 4:00 p.m. CT, same business day | | 3:15 p.m. CT | 5:00 p.m. CT, same business day | | 6:30 p.m. CT | 7:30 a.m. CT, next business day | | 9:15 p.m. CT | 7:30 a.m. CT, next business day | | 10:00 p.m. CT | 7:30 a.m. CT, next business day | Settlement timing is separate from return deadlines. A return must still be submitted within its Nacha return window; see [Returns, Reversals, & Exceptions](/products/ach/exceptions) for those rules and Lead's return cutoffs. ## Try It Pick a submission time and type to see when a transfer is expected to settle. The estimator applies the cutoff tables above, including weekends and Federal Reserve holidays. If the estimator doesn't load, the tables above contain the same rules. # Validations & Best Practices Source: https://docs.lead.bank/products/ach/validations Best practices to reduce ACH validation exceptions. ## **Overview** > [!TIP] > > Lead applies various validation checks on all ACH transactions processed through our systems. In the event of a validation failure: * **API-based ACH**: the individual transaction may be queued for manual review by a Lead processor in cases that require more research or could be immediately rejected at submission time * **File-based ACH**: if an individual entry in a Nacha file fails validation, Lead will reject the entire file and report via Slack about any individual entry validation exceptions For ACH API integrations, we may inform you synchronously for validation failures that do not need a manual review with a real time HTTP 422 error response. For other cases where a manual review or additional processing is required, we will inform you asynchronously via `ach.rejected` webhook. Please see the table below to determine which validations are synchronous or asynchronous. While it is not always possible to prevent all validation failures, following these best practices can reduce the likelihood of exceptions: | Validation | Best Practice | Is Rejection Synchronous via API? | | - | - | - | | account\_number\_not\_active | Verify that the account number used for an ACH transaction is in active status before initiating a transfer. | Y | | aggregate\_limit\_exceeded | Periodically review ACH transaction volume and ensure that daily/monthly aggregate limits set with Lead are sufficient for your business. | N | | client\_customer\_not\_present | Ensure all account numbers have a valid entity\_id | Y | | disallowed\_counterparty | Periodically review disallowed counterparty lists to ensure accuracy | Y | | disallowed\_sec\_code | Ensure that you are utilizing the proper SEC codes approved by Lead for your use cases | Y | | invalid\_format | This indicates a failure to format inputs correctly in an API, or a failure to properly format a Nacha spec file. Ensure you follow all guidance. | Y | | non\_sufficient\_funds | Monitor and manage the balance in the originating account to prevent NSF (Non-Sufficient Funds) scenarios. | N | | ofac\_rejection | Institute proper screening procedures to help prevent sanctions list matches. | N | | per\_transaction\_limit\_exceeded | Periodically review ACH transaction volume and ensure that per transaction limits set with Lead are sufficient for your business. | Y | | previously\_corrected | React promptly to `ach.corrected` webhooks to prevent subsequent transactions from being flagged. | N | | related\_prenote\_exception | If you utilize prenotifications, ensure that you do not submit any live transactions until after three banking days from the date of the prenote. | N | | return\_untimely | Submit returns as soon as possible to ensure they are processed within the allowed timeframe. | Y | | reversal\_rejection | When in doubt, reach out to Lead payment processors to ensure you are properly setting reversal codes for your use case. | N | | unexpected\_return\_code | Ensure you are adhering to Nacha guidance on proper use of return codes for your use case. | N | | unexpected\_routing\_number | Ensure that the recipient's routing number is accurate before submitting an ACH transaction. | Y | # Balance Reconciliation Source: https://docs.lead.bank/products/balances-and-transactions/balance-reconciliation Understand end-of-day account balances. ## Overview Lead tracks the end-of-day account balance for `type` = `credit` or `deposit`, along with other applicable balances depending on your programs. > [!NOTE] > > For specific validations performed, refer to [Balances and Transactions Files Validations](/file-reference/balances-and-transactions/balance-validations). ## Deposit Balance | **Reconciliation** | **Description** | | - | - | | balance | Tracks the end-of-day deposit balances (e.g., debit cards, deposit accounts, FBO accounts) for the customer. `balance` reconciles against the daily activity of `transactions.amount`. | | interest\_accrued\_balance (if applicable) | Applies to deposit programs that offer interest to customers. It reconciles against the daily activity of `transactions.amount` for `transactions.type` across `interest_accrued` and `interest_paid`. See [Interest Accrued Balance](/products/balances-and-transactions/balance-reconciliation#examples) for examples. | | rewards\_balance (if applicable) | Applies to deposit programs that offer rewards (e.g., a debit card with rewards). It reconciles against the daily activity of `transactions.amount` for `transactions.type` across `rewards_earned`, `rewards_spent`, `rewards_redeemed`, `debit`, `credit`, and `refund`. See [Rewards Balance](/products/balances-and-transactions/balance-reconciliation#examples) for examples. | | dispute\_balance | Tracks the end-of-day dispute balances (e.g., disputes on card transactions) for the customer. It reconciles against the daily activity of `transactions.amount` for `transactions.type` across `dispute_provisional`,`dispute_lost`, and `dispute_won`. See [Dispute Balance](/products/balances-and-transactions/balance-reconciliation#examples) for examples. | | charge\_off\_balance | Applies to overdrawn deposit balances that have been charged off. It tracks the end-of-day charge-off balance for the customer and reconciles against the daily activity of `transactions.amount` for `transactions.type` across `charge_off`. See [Charge Off Balance](/products/balances-and-transactions/balance-reconciliation#examples) for examples. | ## Credit Balance | **Reconciliation** | **Description** | | :- | :- | | balance | Tracks the end-of-day credit balances (e.g., loans, credit cards) for the customer. It reconciles against the daily activity of `transactions.amount` except for `transactions.type` across `charge_off_recovery` and `dispute_won`, which do not affect the credit balance. | | balance | Represents the outstanding balance across principal, fees, and interest: - Each sub-amount of outstanding balance is reconciled against day over day transactions that affect that sub-amount. For example, if outstanding interest is increased by \$10, then we would expect to see a transaction that has an `interest_amount` of \$10. Similarly, if outstanding fees are decreased by \$20 due to a payment, then we would expect to see a transaction that has a `fees_amount` of -\$20. - Additionally, `reallocation` transaction types can be used to move outstanding amounts from one sub-amount to another e.g. \$10 from outstanding interest is reduced and instead applied to principal. | | rewards\_balance (if applicable) | Applies to credit programs that offer rewards (e.g., a credit card with rewards). It reconciles against the daily activity of `transactions.amount` for `transactions.type` across `rewards_earned`, `rewards_spent`, `rewards_redeemed`, `disbursement`, `client_credit`, and `refund`. See [Rewards Balance](/products/balances-and-transactions/balance-reconciliation#examples) for examples. | | dispute\_balance | Tracks the end-of-day dispute balances (e.g., disputes on card transactions) for the customer. It reconciles against the daily activity of `transactions.amount` for `transactions.type` across `dispute_provisional`,`dispute_lost`, and `dispute_won`. See [Dispute Balance](/products/balances-and-transactions/balance-reconciliation#examples) for examples. | | charge\_off\_balance | Applies to charged-off credit balances. It tracks the end-of-day charge-off balance for the customer and reconciles against the daily activity of `transactions.amount` for `transactions.type` across `charge_off` and `charge_off_recovery`. See [Charge Off Balance](/products/balances-and-transactions/balance-reconciliation#examples) for examples. | | past\_due\_balance | Applies to past due balances. It tracks the end-of-day past due balance for the customer. There is no reconciliation against `transactions.amount` and credit balance enters past due status if the customer fails to make the scheduled payment by the due date. See [Past Due Balance](/products/balances-and-transactions/balance-reconciliation#examples) for examples. | ## Examples > [accordion] Rewards > > > [!NOTE] > > > > Applicable to Both Deposit and Credit Balances if your program offers rewards. > > For rewards, Lead tracks `rewards_balance` and `rewards_unit` in the Balance file as well as rewards transactions affecting the balance. > > ### Rewards on the Debit Card or Deposit Balance > > | **Type** | **Amount Action** | **Rewards Amount** | **Example** | > | - | - | - | - | > | debit | Applied (-) / Reversed (+) | 0 or positive (+) / 0 or negative (-) | A \$100 `debit` transaction earns 1,000 rewards units. Not all transactions affect rewards. - `balance` decreases by `amount`. - `rewards_balance` may or may not increase by `rewards_amount` depending on whether `debit` transaction affects rewards. | > | refund | Applied (+) / Reversed (-) | 0 or negative (-) / 0 or positive (+) | A \$100 `refund` reverses 1,000 rewards units. Not all transactions affect rewards. - `balance` increases by `amount`. - `rewards_balance` may or may not decrease by `rewards_amount` depending on whether `refund` transaction affects rewards. | > | credit | Applied (+) / Reversed (-) | 0 or negative (-) / 0 or positive (+) | A \$100 `credit` reverses 1,000 rewards units. Not all transactions affect rewards. - `balance` increases by `amount`. - `rewards_balance` may or may not decrease by `rewards_amount` depending on whether `credit` transaction affects rewards. | > | dispute\_provisional | Applied (+) | 0 or negative (-) | A dispute for a transaction is in progress. This transaction originally had 1,000 rewards associated with it. - `balance` increases by `amount`. - `rewards_balance` may or may not decrease by `rewards_amount` depending on whether the partner reduces the rewards associated with the dispute transaction. | > | dispute\_lost | Applied (-) | 0 or positive (+) | A dispute for a transaction is lost. - `balance` decreases by `amount`. - `rewards_balance` may or may not increase by `rewards_amount` depending on whether the partner increases the rewards associated with the dispute lost transaction. | > | rewards\_earned | Applied (0) / Reversed(0) | Positive (+) / negative (-) | 1,000 rewards units are added to the rewards balance, which increases to 1,000 units. This does not affect the deposit balance. - `balance` is unaffected. - `rewards_balance` increases by `rewards_amount`. | > | rewards\_spent | Applied (0) / Reversed(0) | Negative (-) / Positive (+) | 1,000 rewards units are deducted from the rewards balance. This does not affect the deposit balance. - `balance` is unaffected. - `rewards_balance` decreases by `rewards_amount`. | > | rewards\_redeemed | Applied (+) / Reversed (-) | Negative (-) / Positive (+) | A \$1.00 cashback is credited to the deposit balance, reducing the rewards amount accordingly. - `balance` increases by `amount`. - `rewards_balance` decreases by `rewards_amount`. | > > ### Rewards on the Credit Card > > | **Type** | **Amount Action** | **Rewards Amount** | **Example** | > | :- | :- | :- | :- | > | disbursement | Applied (+) / Reversed (-) | 0 or positive (+) / 0 or negative (-) | A \$100 disbursement earns 1,000 rewards units. Not all transactions affect rewards. - `balance` increases by `amount`. - `rewards_balance` may or may not increase by `rewards_amount` depending on whether `disbursement` transaction affects rewards. | > | refund | Applied (-) / Reversed (+) | 0 or negative (-) / 0 or positive (+) | A \$100 refund reverses 1,000 rewards units. Not all transactions affect rewards. - `balance` decreases by `amount`. - `rewards_balance` may or may not decrease by `rewards_amount` depending on whether `refund` transaction affects rewards. | > | client\_credit | Applied (-) / Reversed (+) | 0 or negative (-) / 0 or positive (+) | A \$100 client credit reverses 1,000 rewards units. Not all transactions affect rewards. - `balance` decreases by `amount`. - `rewards_balance` may or may not decrease by `rewards_amount` depending on whether `client_credit` transaction affects rewards. | > | dispute\_provisional | Applied (-) / Reversed (+) | 0 or negative (-) / 0 or positive (+) | A dispute for a transaction is in progress. This transaction originally had 1,000 rewards associated with it. - `balance` decreases by `amount`. - `rewards_balance` may or may not decrease by `rewards_amount` depending on whether the partner reduces the rewards associated with the dispute transaction. | > | dispute\_lost | Applied (+) / Reversed (-) | 0 or positive (+) / 0 or negative (-) | A dispute for a transaction is lost. - `balance` increases by `amount` - `rewards_balance` may or may not increase by `rewards_amount` depending on whether the partner increases the rewards associated with the dispute lost transaction. | > | rewards\_earned | Applied (0) / Reversed(0) | Positive (+) / Negative (-) | 1,000 rewards units are added to the rewards balance, increasing it to 1,000 units. This does not affect the credit balance. - `balance` is unaffected. - `rewards_balance` increases by `rewards_amount`. | > | rewards\_spent | Applied (0) / Reversed(0) | Negative (-) / Positive (+) | 1,000 rewards units are deducted from the rewards balance. This does not affect the credit balance. - `balance` is unaffected. - `rewards_balance` decreases by `rewards_amount`. | > | rewards\_redeemed | Applied (-) / Reversed (+) | Negative (-) / Positive (+) | A \$1.00 cashback is applied to the credit balance, reducing both the credit balance and the rewards amount accordingly. - `balance` decreases by `amount`. - `rewards_balance` decreases by `rewards_amount`. | > [accordion] Dispute Balance > > > [!NOTE] > > > > Applicable to both deposit and credit balances. > > For disputes, Lead tracks `dispute_balance` (if Credit: across balance, principal, interest and fees) in the Balances file as well as dispute transactions affecting the balance. Below are examples of disputes for deposit and credit balances. > > ### Disputes on the Deposit Balance > > | **Type** | **Amount Action** | **Example** | > | - | - | - | > | dispute\_provisional | Applied (+) | The customer's deposit balance is \$1,000. Customer disputes a \$50 charge from a merchant. - `balance` increases by \$50 to \$1,050 while the dispute is in progress. - `dispute_balance` increases by \$50 to \$50 while the dispute is in progress. | > | dispute\_won | Applied (-) | Customer wins the dispute of \$50 transaction. - `balance` is unaffected at \$1,050. - `dispute_balance` decreases by \$50 to \$0. | > | dispute\_lost | Applied (-) | Customer loses the dispute of \$50 transaction. - `balance` decreases by \$50 to \$1,000. - `dispute_balance` decreases by \$50 to \$0. | > > ### Disputes on the Credit Balance > > | **Type** | **Amount Action** | **Example** | > | :- | :- | :- | > | dispute\_provisional | Applied (-) | The customer's credit balance is \$1,000. Customer disputes a \$50 charge from a merchant. - `balance` decreases by \$50 to \$950 while the dispute is in progress. - `dispute_balance` increases by \$50 to \$50 while the dispute is in progress. | > | dispute\_won | Applied (-) | Customer wins the dispute of \$50 transaction. - `balance` is unaffected at \$950. - `dispute_balance` decreases by \$50 to \$0. | > | dispute\_lost | Applied (+) | Customer loses the dispute of \$50 transaction. - `balance` increases by \$50 to \$1,000. - `dispute_balance` decreases by \$50 to \$0. | > [accordion] Charge Off Balance > > > [!NOTE] > > > > Applicable to both deposit and credit balances. > > For charge offs, Lead tracks `charge_off_balance` (if Credit: across balance, principal, interest and fees) in the Balances file as well as charge-off transactions affecting the balance. Below are examples of charge-offs for deposit and credit balances. > > ### Charge Offs on the Deposit Balance > > | **Type** | **Amount Action** | **Example** | > | - | - | - | > | charge\_off | Applied (+) | The customer is overdrawn \$100 (deposit balance = -\$100) and has surpassed the threshold for repayment. A charge-off transaction of \$100 is run. - `balance` increases by \$100 to \$0. - `charge_off_balance` increases by \$100 to \$100. | > | charge\_off\_recovery | Applied (-) | Customer deposits \$100 to pay off the `charge_off_balance`. - `balance` is unaffected at \$0. - `charge_off_balance` decreases by \$100 to \$0. | > > ### Charge Offs on the Credit Balance > > | **Type** | **Amount Action** | **Example** | > | :- | :- | :- | > | charge\_off | Applied (-) | A \$100 loan (credit balance = \$100) has been charged off. - `balance` decreases by \$100 to \$0. - `charge_off_balance` increases by \$100 to \$100. | > | charge\_off\_recovery | Applied (-) | Customer deposits \$100 to pay off the `charge_off_balance`. - `balance` is unaffected at \$0. - `charge_off_balance` decreases by \$100 to \$0. | > [accordion] Interest Accrued Balance > > > [!NOTE] > > > > Applicable to deposit balance only if your program offers interest. > > For deposit balances, Lead tracks `interest_accrued_balance` to record cumulative interest accrued. `interest_accrued` and `interest_paid` impact `interest_accrued_balance`, while `interest_paid` also affects the deposit balance. > > For example, with a beginning deposit balance of \$100, interest accrues at \$1 daily, reaching \$30 by month-end. > > * day 1-30: The `interest_accrued_balance` increases daily. At month-end, the deposit balance remains \$100, and `interest_accrued_balance` is \$30. > * After `interest_paid`, the deposit balance becomes \$130, and `interest_accrued_balance` resets to \$0. > > ### Interest on the Deposit Balance > > | **Type** | **Amount Action** | **Example** | > | - | - | - | > | interest\_accrued | Applied (+) / Reversed (-) | Interest accrues \$1 daily. - `balance` is unaffected. - `interest_accrued_balance` increases by \$1 daily. By day 30, `interest_accrued_balance` is \$30. | > | interest\_paid | Applied (+) / Reversed (-) | \$30 of accrued interest is paid to the customer on day 30. - `balance` increases by \$30 to \$30. - `interest_accrued_balance` decreases by \$30 to \$0. | > [accordion] Past Due Balance > > > [!NOTE] > > > > Applicable to credit balance only. > > For credit balances, Lead tracks `past_due_balance` for any loans that are past due. `past_due_balance` is not directly affected by `transactions.amount`. Instead, credit balance enters past due status if the customer fails to make the scheduled payment by the due date. > > See the example below for how `past_due_balance` interacts with `balance`. > > For simplicity, we assume all past due balances apply to principal only. However, in reality, past due amounts may be distributed across principal, fees, and interest. > > * A \$500 loan payment is due on March 1st, but the customer misses the payment. > * April 1st: Loan is 30+ Days Past Due. `balance` remains unchanged at \$500, but the loan is now classified as past due. Outstanding balances and past due balances are updated accordingly across principal, interest, and fees. > * `balance`: \$500 > * `outstanding_principal`: \$500 > * `outstanding_interest`: \$0 > * `outstanding_fees`: \$0 > * `past_due_balance`: \$500 > * `past_due_principal`: \$500 > * `past_due_interest`: \$0 > * `past_due_fees`: \$0 > * July 1st: Loan is 120+ Days Past Due and Charged Off. Loan remains unpaid for 120+ days.\ > The partner charges off the loan, moving the balance to `charge_off_balance`. `transactions.amount` of \$500 is recorded under `transactions.type` = `charge_off`. Note: Charge-off timelines may vary between closed-end and open-end loans and must follow applicable regulatory guidelines. > * `balance`: \$0 (loan is fully charged off) > * `outstanding_principal`: \$0 > * `outstanding_interest`: \$0 > * `outstanding_fees`: \$0 > * `past_due_balance`: \$0 (past due balance is cleared) > * `past_due_principal`: \$0 > * `past_due_interest`: \$0 > * `past_due_fees`: \$0 > * `charge_off_balance`: \$500 (loan is now recorded as a charge-off) > * `charge_off_principal`: \$500 > * `charge_off_interest`: \$0 > * `charge_off_fees`: \$0 # Balance Statuses Source: https://docs.lead.bank/products/balances-and-transactions/balance-statuses The balance lifecycle — status and status_reason pairs, what inactive means for validation, the two terminal statuses including receivable_transferred, and the checks that guard transitions. Balance statuses describe **your report** of a balance's state — you are the ledger of record, you determine when a balance's status changes, and you communicate it through your daily [Balance file reporting](/products/balances-and-transactions/overview). Every balance carries a **status** and a **status\_reason**, which pair together to define its state. ## The Statuses | **Status** | **Meaning** | **`status_reason` values** | | :- | :- | :- | | `active` | Fully functional and operating as expected. Default on creation — via the [Subledger Balance API](/products/lending/balance-object) for credit balances, or via the daily Balance file for deposit balances. | `active` | | `inactive` | You have taken action to restrict activity on the balance. **Lead runs no additional validations on inactive balances during daily reporting** — you are expected to take action on them according to your own policies. | `dormant` · `frozen` · `other` | | `closed` | **Terminal.** The balance is no longer active. | `entity_closed` · `client_closed` · `paid_off` · `charged_off` · `canceled` | | `receivable_transferred` | **Terminal — credit balances only.** Any outstanding receivable(s) on the balance has been transferred from Lead to you ([balance-sheet models](/products/lending/balance-sheet-models)). Reachable from `active` or `inactive`. **After setting this status, omit the balance from all subsequent Balance files.** Use is limited to specific use cases — ask your Technical Account Manager whether it applies to your program. | `receivable_sold_to_partner` | ## Reporting the Lifecycle * **Active and inactive balances appear in every day's file** until you transition them to a terminal status — a balance missing from a day's file without a terminal transition is a validation failure, not an implicit closure ([troubleshooting](/file-reference/balances-and-transactions/troubleshooting)). The one exception is `receivable_transferred`, which is omitted from all files *after* the transition is reported. * **Terminal transitions are guarded:** a balance cannot be reported into `closed` or `receivable_transferred` while any [Funding](/products/lending/funding-object) against it is still `processing` — the file fails with `balance_cannot_be_terminal_with_processing_funding`. Wait for the Funding to reach `posted` or `rejected`, then report the transition. * **Creation is guarded from October 6, 2026:** every new balance must reference a valid parent [Account](/products/accounts/overview) ([Upcoming Changes](/upcoming-changes#account-validation-during-new-balance-creation)) # Balance and Transactions Source: https://docs.lead.bank/products/balances-and-transactions/overview Reporting customer activity across deposit and credit products to Lead. > [!WARNING] > > **Upcoming Changes** > > We're introducing additional validation to ensure every Balance references a valid parent Account. Partners submitting Balance files should review their account creation and file generation workflows before validation is enforced on October 6, 2026. > > 👉 [View Details](/upcoming-changes#account-validation-during-new-balance-creation) ## What You're Reporting and Why A **Balance** is your customer's position in a product on an [Account](/products/accounts/overview): for deposit products, the money they hold; for credit products, the loan or line and the outstanding position against it. A **Transaction** is an individual item of activity against a balance. Because you are the ledger of record for your customers, these are **reporting** objects ([Executing vs. Reporting](/core-concepts/platform/executing-vs-reporting)) — you maintain them in your systems and report them to Lead, and Lead's compliance oversight of your program depends on their accuracy and timeliness. ## Deposit Balances Deposit balances are created and maintained entirely through the daily files. Lead reconciles what you report against its own records of the money on the core surface, including — where your program uses them — `rewards_amount`, `dispute_balance`, `charge_off_balance`, and `interest_accrued_balance` alongside `balance`. ## Credit Balances Credit balances are additionally **created** through the Subledger Balance API — the object itself, its two structures (`non_revolving` / `revolving`), and its terms live on [The Balance Object](/products/lending/balance-object) in Lending & Receivables — and then **serviced** through the same daily files as everything else. The distinction matters operationally: the position you report gates what happens next. Available credit — which limits the next [Funding](/products/lending/funding-object) draw — is computed from what you report, so reporting accuracy is load-bearing, not just compliance-relevant. Credit reconciliation covers `balance` and its components `principal`, `fees`, and `interest`, plus `rewards_amount`, `dispute_balance`, `charge_off_balance`, and `past_due_balance` where applicable — the same components readable back on the Balance object's live position. ## The Daily Reporting Rhythm Balance and Transaction files are due by **6:00 a.m. CT** the business day after the activity (T+1). Two habits keep the rhythm healthy: * **Report empty days explicitly.** Submit an empty file on days with nothing to report — silence is indistinguishable from a broken pipeline. * **Watch the alert channel.** Every submission produces a [Slack alert](/file-reference/delivery/slack-alerts): 🟢 on validation success, 🔴 with an error code, detail, and action on failure. Fix the flagged file, upload the corrected version, and Lead re-validates the latest version of each file in the batch. Error codes and resolutions: [File Submission Validation Errors](/file-reference/delivery/errors) and [Balances & Transactions Files Troubleshooting](/file-reference/delivery/slack-alerts). ## Reconciliation Lead reconciles your reported positions daily against one invariant: > **balance on T = balance on T−1 + the transactions affecting the balance on T** Assert the same identity in your own pipeline before submission — a file that fails it at Lead will fail with a balance-mismatch error naming the expected sum and the delta, but catching it pre-submission keeps your reporting day clean. Full mechanics: [Balance Reconciliation](/products/balances-and-transactions/balance-reconciliation). ## Today's Transports **Reporting** runs on the daily files; **credit-balance creation** runs on the Subledger Balance API. API successors for the daily reporting are planned — same flows, migration in cohorts with notice ([Platform Evolution](/core-concepts/platform/platform-evolution)). Until they ship, the file schemas are authoritative. ## In This Section [Transaction Types](/products/balances-and-transactions/transaction-types) — the classification every reported transaction carries · [Balance Statuses](/products/balances-and-transactions/balance-statuses) — the balance lifecycle and who changes it (you do; there are no lifecycle webhooks) · [Balance Reconciliation](/products/balances-and-transactions/balance-reconciliation) — how your reported positions are reconciled against Lead's records. The credit Balance object itself — creation, structures, terms — lives in [Lending & Receivables](/products/lending/balance-object). ## Reference API Reference: [Subledger Balance endpoints](/api-reference/endpoint/subledger-balance/create-a-subledger-balance) · File Reference: [Balances](/file-reference/balances-and-transactions/balances-schema) & [Transactions](/file-reference/balances-and-transactions/transactions-schema) schemas · [Balance & Transaction Validations](/file-reference/balances-and-transactions/balance-validations) # Transaction Types Source: https://docs.lead.bank/products/balances-and-transactions/transaction-types The four-field classification every reported transaction carries — type, fee_type, action, and transfer_type — with the full deposit and credit type tables, per-type polarity, and dispute semantics. Every transaction you report in the daily [Transactions file](/file-reference/balances-and-transactions/transactions-schema) carries a classification that Lead uses for accounting entries, account reconciliation, and ongoing program oversight. This page is the semantic reference for that classification; the field-by-field schema lives in the [File Reference](/file-reference/balances-and-transactions/transactions-schema). > [!TIP] > > Map your ledger's transactions to Lead's transaction types **before going live** — the mapping must be approved by Lead's accounting team, and your implementation team will provide a tool for completing this request during onboarding. If activity in your ledger doesn't fit a type below, raise it during mapping rather than bending a type to fit. ## The Four-Field Classification | **Field** | **What it says** | **Values** | | :- | :- | :- | | `type` | What kind of activity this is. | Differs by product surface — see the [Deposit](#deposit-transaction-types) and [Credit](#credit-transaction-types) tables. | | `fee_type` | Which fee, when `type` is `fee`. | `atm` · `overdraft` · `periodic_maintenance` · `card` · `international_transaction` · `other` | | `action` | Whether the activity is being applied or backed out. | `applied` — posted, assessed, or accrued activity affecting the underlying balance · `reversed` — reversed or returned activity | | `transfer_type` | The rail the money moved on, if any. | The table below. | A reversal is a **new transaction** with `action: reversed` — you never delete or mutate a previously reported record. Note the polarity flip per type in the tables below: a reversal moves the balance in the opposite direction of the corresponding `applied` transaction. Corrections to fields like `settlement_date` on an already-reported transaction go through the [Transactions Updates file](/file-reference/balances-and-transactions/transactions-update-schema) instead. ## Transfer Types If the transaction was conducted via a Lead API or payment rail, also provide `transfer_ids` on the record — the Lead-generated transfer object IDs (e.g., the ACH ID) that tie your reported customer activity to the [money movement](/core-concepts/platform/money-movement) Lead executed. | **`transfer_type`** | **Meaning** | | :- | :- | | `ach` | ACH transactions. | | `wire` | Wire transactions. | | `international_wire` | International wire transactions. | | `instant_payment` | Instant payment transactions. | | `check` | Check transactions. | | `card` | Card transactions. | | `oct` | Original credit transactions — push-to-card. | | `aft` | Account funding transactions — transfers funding a card account. | | `internal_transfer` | Transfers within accounts at Lead. Also used to report [Blockchain Payments](/products/blockchain-payments/overview) transactions. | | `external_transfer` | Transfers between accounts at Lead and external bank accounts. | | `no_money_movement` | Activity on an end-customer balance with no money movement within Lead — e.g., a customer moving money between two USD pockets, a dispute won where provisional credit was applied earlier, or interest accrued but not yet paid. Used when no settlement is needed. | | `out_of_bank_settlement` | Activity affecting a customer balance held at accounts outside Lead but due to Lead customers. | **`transfer_type` is required** for these types (optional elsewhere — any valid enum may be provided): * **Deposit balances:** `debit`, `credit`, `refund`, `dispute_provisional`, `escheatment` * **Credit balances:** `disbursement`, `payment`, `refund`, `client_credit`, `dispute_provisional` ## Deposit Transaction Types Polarity is from the balance's perspective: positive increases the deposit balance, negative decreases it. | **Type** | **Fee Type** | **Description** | **Action (amount polarity)** | | :- | :- | :- | :- | | `debit` | — | Debit applied to the deposit balance (e.g., outgoing payments). Allowed transfer types: `ach`, `wire`, `international_wire`, `instant_payment`, `check`, `card`, `oct`, `aft`, `internal_transfer`, `external_transfer`, `out_of_bank_settlement`, `no_money_movement`. | Applied (−) · Reversed (+) | | `credit` | — | Credit applied to the deposit balance (e.g., incoming deposits). Allowed transfer types: as `debit`, minus `card`. | Applied (+) · Reversed (−) | | `refund` | — | Refund of a debit transaction. Allowed transfer types: `card`. | Applied (+) · Reversed (−) | | `dispute_provisional` | — | Dispute filed and in progress: `balance` **and** `dispute_balance` each increase by `amount`. Reversed unwinds a provisional credit (e.g., removed without the dispute resolving in the customer's favor): both decrease. Allowed transfer types: `internal_transfer`, `external_transfer`, `out_of_bank_settlement`, `no_money_movement`. | Applied (+) · Reversed (−) | | `dispute_won` | — | Customer wins: `balance` unaffected; `dispute_balance` decreases by `amount`. Reversed: `dispute_balance` increases. | Applied (−) · Reversed (+) | | `dispute_lost` | — | Customer loses: `balance` and `dispute_balance` each decrease by `amount`. Reversed: both increase. | Applied (−) · Reversed (+) | | `escheatment` | — | Transfer of unclaimed or abandoned funds to the state after a period of inactivity. Allowed transfer types: `ach`, `wire`, `check`, `internal_transfer`, `external_transfer`, `out_of_bank_settlement`, `no_money_movement`. | Applied (−) | | `charge_off` | — | Write-off of unpaid negative balances, typically overdraft: `balance` increases; `charge_off_balance` increases. | Applied (+) · Reversed (−) | | `charge_off_recovery` | — | Full or partial recovery of a charge-off: `balance` unaffected; `charge_off_balance` decreases. | Applied (−) · Reversed (+) | | `rewards_earned` | — | Earns rewards only; balance unaffected — `amount` is 0. | Applied (0) · Reversed (0) | | `rewards_spent` | — | Spends rewards only; balance unaffected — `amount` is 0. | Applied (0) · Reversed (0) | | `rewards_redeemed` | — | Rewards balance redeemed to credit the balance. | Applied (+) · Reversed (−) | | `fee` | `atm` | ATM withdrawal fees. | Applied (−) · Reversed (+) | | `fee` | `overdraft` | Overdraft fees. | Applied (−) · Reversed (+) | | `fee` | `periodic_maintenance` | Periodic maintenance fees (e.g., monthly or annual). | Applied (−) · Reversed (+) | | `fee` | `card` | Card-related fees. | Applied (−) · Reversed (+) | | `fee` | `international_transaction` | International transaction fees. | Applied (−) · Reversed (+) | | `fee` | `other` | Other deposit-related fees. | Applied (−) · Reversed (+) | | `interest_accrued` | — | Accrued interest: `balance` unaffected; `interest_accrued_balance` increases. | Applied (+) · Reversed (−) | | `interest_paid` | — | Paid interest: `balance` increases; `interest_accrued_balance` decreases. | Applied (+) · Reversed (−) | | `adjustment` | — | Balance adjustments not captured by the types above (e.g., funding or reducing a balance outside the normal course of business). **Use only if aligned with Lead.** | Applied (+/−) | ## Credit Transaction Types > [!TIP] > > Every credit transaction must include `amount` = `principal_amount` + `fee_amount` + `interest_amount` — the same decomposition [the Balance's live position](/products/lending/balance-object#the-live-position) tracks and [reconciliation](/products/balances-and-transactions/balance-reconciliation) asserts. If your program offers rewards, the rewards fields are also required. Polarity is from the balance's perspective — the balance is what the customer *owes*, so draws are positive and payments negative. | **Type** | **Fee Type** | **Description** | **Action (amount polarity)** | | :- | :- | :- | :- | | `disbursement` | — | **Principal only:** disbursement of the credit balance, increasing the overall balance and generating a receivable ([Receivables & the Daily Sale](/products/lending/receivables-and-the-daily-sale)). Affects `outstanding_principal` only. When reporting a posted [Funding](/products/lending/funding-object), use `transfer_type: internal_transfer` with `funding_id`, and `fee_amount` must equal the Funding's `other_fees.borrower_origination_fee_amount` ([troubleshooting](/file-reference/balances-and-transactions/troubleshooting)). Allowed transfer types: `card`, `internal_transfer`, `no_money_movement`. | Applied (+) | | `payment` | — | **Across principal, fees, and interest:** payment towards the credit balance. Allowed transfer types: `ach`, `wire`, `international_wire`, `instant_payment`, `check`, `internal_transfer`, `external_transfer`, `out_of_bank_settlement`, `no_money_movement`. | Applied (−) · Reversed (+) | | `refund` | — | **Across principal, fees, and interest:** refund of a credit balance, such as a full refund. Allowed transfer types: as `payment`, plus `card`. | Applied (−) | | `cancellation` | — | **Across principal, fees, and interest:** cancellation of a credit balance (e.g., the user cancels their loan). Allowed transfer types: `no_money_movement`. | Applied (−) | | `client_credit` | — | **Across principal, fees, and interest:** partial credit or refund applied to the balance. Allowed transfer types: `no_money_movement`. | Applied (−) · Reversed (+) | | `charge_off` | — | **Across principal, fees, and interest:** full or partial charge-off: `balance` decreases; `charge_off_balance` increases. | Applied (−) · Reversed (+) | | `charge_off_recovery` | — | Full or partial recovery of a charge-off: `balance` unaffected; `charge_off_balance` decreases. | Applied (−) · Reversed (+) | | `dispute_provisional` | — | **Across principal, fees, and interest:** dispute filed and in progress: `balance` decreases; `dispute_balance` increases. Reversed unwinds a previously applied provisional credit: `balance` increases, `dispute_balance` decreases. Allowed transfer types: `no_money_movement`. | Applied (−) · Reversed (+) | | `dispute_won` | — | Customer wins: `balance` unaffected; `dispute_balance` decreases. Reversed: `dispute_balance` increases. | Applied (−) · Reversed (+) | | `dispute_lost` | — | Customer loses: `balance` increases; `dispute_balance` decreases. Reversed: `balance` decreases, `dispute_balance` increases. | Applied (+) · Reversed (−) | | `rewards_earned` | — | Earns rewards only; `balance` unaffected — `amount` is 0. | Applied (0) · Reversed (0) | | `rewards_spent` | — | Spends rewards only; `balance` unaffected — `amount` is 0. | Applied (0) · Reversed (0) | | `rewards_redeemed` | — | Rewards redeemed to credit the balance. | Applied (−) · Reversed (+) | | `fee` | `card` | **Fee only:** card-related fees. | Applied (+) · Reversed (−) | | `fee` | `international_transaction` | International transaction fees. | Applied (+) · Reversed (−) | | `interest_accrued` | — | **Interest only:** accrued interest — `interest_amount` nonzero; `principal_amount` and `fee_amount` zero. | Applied (+) · Reversed (−) | | `reallocation` | — | Reallocation across principal / interest / fees — net-zero to `amount`. | Applied (0) | > [!TIP] > > All three dispute types (`dispute_provisional`, `dispute_won`, `dispute_lost`) support both `applied` and `reversed`: a `reversed` transaction unwinds a previously reported dispute transaction of the same type, moving `balance` and `dispute_balance` in the opposite direction of the corresponding `applied` transaction. ## Reference [Transactions Schema](/file-reference/balances-and-transactions/transactions-schema) — every field, requiredness, and data types, including `transfer_ids`, `funding_id`, `original_transaction_id`, and the per-type `settlement_date` rules · [Balance Reconciliation](/products/balances-and-transactions/balance-reconciliation) — the identities these classifications feed · [Balances & Transactions Files Troubleshooting](/file-reference/balances-and-transactions/troubleshooting) — the validation errors and fixes. # Your Banking Infrastructure (Core Surface) Source: https://docs.lead.bank/products/banking-infrastructure/overview The Lead-managed bank accounts behind your program, how you read them today, and the core APIs that are rolling out. Behind every program sit real bank accounts on Lead's core: the **FBO** that pools your customers' deposits, and the **operating, settlement, revenue, and reserve accounts** your program runs on. Lead opens and manages these during onboarding. You do not create them; you read them. Today you read them through the [Daily Balance](/file-reference/reports/daily-balance) and [Daily Activity](/file-reference/reports/daily-activity) reports, online banking, and the `account_id` values on payment objects and [Account Numbers](/products/account-number/overview). As the core APIs roll out, you can also read them directly over the API. This is the **core surface** described on the [Object Model](/core-concepts/platform/object-model) page. Lead is the actor here, which is why the data comes *from* Lead rather than being reported *by* you. That is the mirror image of [Customers & Accounts](/products/entity/overview), where you are the ledger of record. > [!NOTE] > > The Core Account, Core Balance, and Core Transaction APIs are in beta. Beta APIs may change without a version increment. Changes are announced in advance and your Technical Account Manager works with you on them. ## Core Surface The foundational accounts you use to operate your program. Lead opens them for you during onboarding and manages their lifecycle; you read them through the online banking UI, the daily reports, and the core APIs, but you don't open or close them yourself. The core APIs return each one with a `type`. * **FBOs.** Pooled "For Benefit Of" accounts that hold your customers' funds in aggregate. In the core APIs an FBO is `attributed` when its funds are attributed to customers through user balances, and `direct` when it is not. * **Operating accounts.** Day-to-day DDAs for operating, revenue, reserve, settlement, network settlement, and so on. In the core APIs these are `direct`. * **Shadow accounts.** Secondary sweep or placement positions such as IntraFi ICS. In the core APIs these are `shadow`. Read only; nothing transacts against them and account numbers never attach. ## Two ways to read the core surface > [tab] Today (account\_id) > > On the objects you use today, an account and its balance are one thing. A core account is one of your FBOs, operating DDAs, or shadow accounts, identified by `account_`, and it carries the balance. > > * **Identifier:** `account_`, as it appears on account numbers and payment objects. > * **Balance:** read from the [Daily Balance report](/file-reference/reports/daily-balance) or online banking. > * **Transactions:** read from the [Daily Activity report](/file-reference/reports/daily-activity) or online banking. > * **Held by:** your Lead or partner entity. Opened and managed by Lead. > > ```text theme={null} > Entity (Lead or partner) > └── Account (account + balance combined, account_) > └── Account Number (routable payment address) > ``` > [tab] Core APIs (/v2) > > The core APIs split the same account into three read-only resources. Every ID carries its object type as a prefix. > > * **Core Account** (`core_account_*`). The bank account: name, `type`, status, and the entities that hold it. See [Core Accounts](/products/core-account/overview). > * **Core Balance** (`core_balance_*`). The balance position within the account: posted, holds, sweeps, overdraft, interest, and a derived spendable figure. One per account today. See [Core Balances](/products/core-balance/overview). > * **Core Transaction** (`core_transaction_*`). A ledger entry that changed a core balance, with a `type` naming the rail or mechanism that created it. See [Core Transactions](/products/core-transaction/overview). > > ```text theme={null} > Entity (Lead or partner) > └── Core Account (core_account_*) > └── Core Balance (core_balance_*) > ├── Core Transaction (core_transaction_*) > └── Account Number (routable payment address, where permitted) > ``` > > All three are on `/v2/` and each has a single read scope: `core_account/read`, `core_balance/read`, `core_transaction/read`. ## How the two models relate The accounts are the same bank accounts. What changes is how you refer to them. Core objects carry typed IDs: `core_account_*` and `core_balance_*`. The `account_id` on your v1 account numbers and payment objects is a different identifier. The core endpoints do not accept it, and there is no lookup by legacy `account_id`. Read the balance with `GET /v2/core_balances/{core_balance_id}`; its `core_account_id` field gives you the parent core account. `account_id` keeps working on v1 and is not removed during the migration window. What does not change: * v1 account numbers and payment objects keep working through the migration window. Nothing is removed from them. * Typed IDs are opaque strings. Store them as returned. Do not parse them or derive meaning from the prefix beyond object type. * The Daily Balance and Daily Activity reports are unchanged. The core APIs return the same figures and the same entries on demand. ## Account Number The routing number and account number pair that lets money reach an account on Lead's payment rails. A single core account can have many — for example, one for each end customer whose funds are pooled in an FBO. Account Numbers hang off core accounts. Even when you assign one to an individual customer, it attaches to the core account — the customer is carried on the account number's `entity_id` — so an inbound payment lands on the core account first and is attributed to the customer from there. * **Today:** An Account Number points to a core Account (via `account_id`). * **Core APIs:** Under the core APIs the same account number attaches to the core balance. See [The Core Account Object](/products/core-account/core-account-object). * **Lifecycle:** Unassigned → active ↔ inactive → canceled. canceled is terminal; Account Numbers are never reused. See [Account Number Statuses](/products/account-number/statuses). * **Controls:** Per-rail allow/block rules for incoming and outgoing payments are set at the Account Number level. See [Controls](/products/account-number/controls). > [!TIP] > > All of Lead's money-movement APIs (ACH, wires, instant payments, and internal transfers) are indexed off the account number. You originate a payment by referencing an `account_number_id`, and Lead resolves the account it settles against. ## Transaction (core) Debits and credits on a core account are generated by Lead — you don't report them. They appear in the [Daily Activity Report](/file-reference/reports/daily-activity), the online banking UI, and the [core transaction API](/products/core-transaction/overview). ## Lead manages, you read * You cannot create, update, activate, deactivate, or close any core object. Lead manages every state transition. * Core objects do not emit webhooks today. Poll the list endpoints instead. Payment objects keep their own webhooks. * You cannot reverse a core transaction. Corrections are new, offsetting transactions. ## In This Section * [Core Accounts](/products/core-account/overview) Beta * [Core Balances](/products/core-balance/overview) Beta * [Core Transactions](/products/core-transaction/overview) Beta * [Core Objects in Sandbox](/products/banking-infrastructure/sandbox) * [Account Numbers](/products/account-number/overview) # Core Objects in Sandbox Source: https://docs.lead.bank/products/banking-infrastructure/sandbox What core accounts, balances, and transactions return in sandbox, and what you can and cannot test against them. > [!NOTE] > > Beta access for sandbox functionality is targeted for October 9, 2026. ## What exists Your sandbox program has core accounts, core balances, and core transactions you can list and retrieve the same way as in production: ```text theme={null} GET /v2/core_accounts GET /v2/core_balances?core_account_id={id} GET /v2/core_transactions?core_balance_id={id} ``` ## How balances and transactions behave Sandbox returns a static response for core balances and core transactions. The figures and entries you read are fixed sample data. New activity in sandbox does not reach the core objects. Simulated ACH, wires, instant payments, and internal transfers do not create core transactions and do not change any core balance. Use the sandbox core endpoints to test how your integration reads these objects, not to reconcile simulated payments. ## What you can test * Requesting the `core_account/read`, `core_balance/read`, and `core_transaction/read` scopes and calling each endpoint with them. * Parsing every field on the three objects, including `amounts`, `overdraft`, and `interest` on a balance. * List filters and cursor pagination: `type` on accounts, `core_account_id` on balances, `core_balance_id`, `type`, and the `created_at` window on transactions. * Error handling. ## What you cannot test * A balance changing in response to a simulated payment. * A core transaction appearing for a simulated payment, or joining a payment's core transaction ID to a core transaction. * Status changes. Core accounts and balances stay `active` in sandbox, and there is no simulate endpoint to deactivate or close one. ## Related [Sandbox Environment](/get-started/sandbox) · [ACH Sandbox Testing](/products/ach/sandbox) · [The Core Balance Object](/products/core-balance/core-balance-object) · [The Core Transaction Object](/products/core-transaction/core-transaction-object) # Blockchain Payments FAQ Source: https://docs.lead.bank/products/blockchain-payments/faq Common questions about using blockchain payments. > [accordion] Can we reuse existing Lead entities for blockchain payments, or do we need to create new ones? > > You can reuse existing entities. If you already have Lead customers set up (for example, from previous integrations), you don't need to create new entity objects. Simply reference them when you initiate blockchain payments. > [accordion] Do we need an entity for every user, or just at the account level? > > Entities represent the end-customer (the person or business sending or receiving funds). You need one entity per customer account. > [accordion] Why does the payment request require both the creditor's address and creditor\_agent information? > > The creditor is the person or business receiving funds outside of Lead. We need their address to verify who they are for compliance. The `creditor_agent` tells us how and where to send funds - for example, which bank in which country. Together, these identify both "who" receives the funds and "how" to deliver them. > [accordion] What's the difference between the debtor and creditor? > > * **Debtor**: The Lead customer sending the funds (the source) > * **Creditor**: The receiver outside of Lead (the destination) > [accordion] Where do I find the account identifier information? > > The account identifier is the source of your funds: your Lead account number. > > * Register an account number via the API if you don't have one already > * Retrieve your account number using the account retrieval endpoint > * Use the `account_number_id` as your debtor account identifier > [accordion] How do I use idempotency with blockchain payments? > > Include the `Idempotency-Key` header in your POST request. This ensures that if your request times out or fails, you can safely retry without accidentally creating duplicate payments. > [accordion] When will I get a 409 Conflict error, and what does it mean? > > A 409 response means your request was received and processing has started. Because payments process asynchronously, this can happen even if your original request hasn't completed yet. > > Here's what each scenario means: > > * **Same key + same request body + still processing** → 409 (processing continues; check webhooks or poll by ID for status) > * **Same key + different request body + still processing** → 409 (key is locked to the original body) > * **Same key + same request body + completed (within 48 hours)** → Replays the original response (no reprocessing) > * **Same key + different request body + completed (within 48 hours)** → 403 (key is locked; use a new key) > * **Same key + any request body + expired (over 48 hours)** → Treated as a new request and processed normally > > To track payment status, subscribe to webhooks or fetch the payment object by its ID. > [accordion] If a transfer is rejected after funds leave my account, where do the funds go? > > In the rare case of a rejection, the movement of funds requires manual intervention. Please reach out to Lead if you have an issue. > [accordion] Can transfers be clawed back after they've settled? > > Yes, but only in rare cases (fraud, sanctions violations, or operational errors). Here's how we handle it: > > * **Sanctions issues**: Detected before funds move. You'll receive a webhook notification and a message via Slack with details. > * **Fraud or operational errors**: If detected after settlement, we'll notify you via Slack with next steps for reclaiming funds. > [accordion] Can transfers be cancelled after they have been created? > > Not at this time. Please reach out to Lead if you have an issue. # Blockchain Payments at Lead: Stablecoins and Cross-Border Payouts Source: https://docs.lead.bank/products/blockchain-payments/overview Send stablecoins. Send foreign currency over blockchain rails. ## Overview A blockchain payment is a transfer of funds that occurs over blockchain networks. Lead converts funds between USD and stablecoins and enables USD payouts to international corridors by routing through blockchain infrastructure.  Blockchain payments use the same API structure as other Lead payment rails, allowing you to treat stablecoins as another settlement option alongside wires and ACH. Our API abstracts blockchain complexity away, so you initiate transfers without managing wallets, on-chain transactions, or network operations.  ### How Blockchain Payments Work Blockchain payments move funds from a Lead entity to various destinations. You always have a Lead customer or entity that initiates the transfer, and the source of funds is always USD held in your Lead account. **Your destination options:** * External stablecoin wallet (yours or a third party's) * Your Lead account (as USD) * Foreign currency bank account (MXN, COP, BRL, EUR, GBP) When you initiate a payment via the API, you specify your source account, your destination (wallet or bank account), and the amount. Lead handles currency conversion, settlement across blockchain rails, and delivery to your specified destination. ## **Sending Blockchain Payments** #### Requirements To send blockchain payments, you need: * **A Lead business account** with deposit accounts for fiat sources * **An entity registered in Lead's system** — as the sender, you must always be a Lead entity #### Sending Payments **1. POST** Use the `POST /v0/blockchain_payments` endpoint to initiate any blockchain payment. **2. Critical Components** Two critical components define each transfer operation: 1. **Debtor:** This specifies where the funds come from — always a Lead account number. 2. **Creditor:** This specifies where the funds are going. You configure these inline for each individual payment request. **3. Requirements** Every request requires: 1. **Source account**: A Lead account number that a Lead entity owns 2. **Destination details**: A blockchain wallet address or bank account 3. **Amount and currency**: The instructed amount in USD, plus the settlement currency 4. **Payment purpose**: The reason for the transfer ## Blockchain Payment Object ```json theme={null} { "id": "blockchain_payment_8888", "debtor": { "account_identifier": { "type": "account_number_id", "value": "account_number_1234" }, "entity_id": "entity_67890" }, "creditor": { "payment_rail": "spei", "clabe": { "account_number": "00218090010000001234" }, "type": "business", "business": { "business_name": "Acme Mexico SA de CV" }, "address": { "line_one": "Av. Reforma 123", "city": "Ciudad de México", "country": "MX", "postal_code": "06600" } }, "creditor_agent": { "bank_name": "BBVA México", "country_code": "MX", "address": { "line_one": "Av. Paseo de la Reforma 505", "city": "Ciudad de México", "country": "MX", "postal_code": "06500" } }, "amounts": { "instructed_amount": 1000000, "instructed_currency_code": "USD", "settlement_currency_code": "MXN", "settlement_amount": 17461350, "settlement_exchange_rate": 1746 }, "payment_purpose": { "type": "invoice_payment" }, "reference": "INV-MXN-2026-001", "status": "posted", "created_at": "2026-02-24T11:22:33Z", "updated_at": "2026-02-24T11:22:33Z" } ``` ## Get Started Learn how to call the `POST /v0/blockchain_payments` endpoint to send USD from your Lead account. > [card] [USD Funding Source](/products/blockchain-payments/usd-funding-source) > > Debtor sends dollars from Lead. # Returns & Rejections Source: https://docs.lead.bank/products/blockchain-payments/returns-and-rejections ## Returns A return occurs when money leaves an account number but cannot reach its final destination. Lead models a return as a separate linked object: the original payment transitions to `posted`, and the linked return object carries the reversal. On a foreign exchange (FX) payout where currency conversion has already happened, Lead converts the funds back to USD at the new spot rate. The amount returned may not equal the amount you sent. ### Return Life Cycle ![Status Diagram For Docs (blockchain Payments) Page 1](https://mintcdn.com/lead/fkreJ13a-5Pe7tf3/images/Status-Diagram-for-Docs-\(blockchain_payments\)---Page-1.png?fit=max\&auto=format\&n=fkreJ13a-5Pe7tf3\&q=85\&s=726646728aaa9ded1c8ed397bff7b2c5) ### Sample Object ```json theme={null} { "id": "blockchain_payment_1234", "debtor": { ... }, "creditor": { ... }, // ... "return": { "code": "account_closed", "reason": "The destination account has been closed." }, "related_blockchain_payments": { // present only on the return payment "original_blockchain_payment_id": "blockchain_payment_5678", // present only on the original payment "return_blockchain_payment_ids": ["blockchain_payment_9012"] } } ``` ### Return Reasons | **Code** | **Description** | **Partner action** | | :- | :- | :- | | `account_closed` | The receiving account is closed and cannot accept the payment. | Send a new payment to a different destination account. | | `account_number_incorrect` | The destination account number is incorrect. | | | `payment_returned` | The receiving institution returned the payment for a reason with no more specific code. | Confirm the destination account details with the creditor before sending a new payment. | Every return code is terminal: the returned payment settles at `posted` with the funds back in the debtor account, so resubmitting the same payment unchanged returns it again. ## Rejections A rejection occurs when a payment never leaves the debtor account. Lead models a rejection as a terminal state in the `blockchain_payment` lifecycle. ### Rejection Reasons Each reason is either **terminal** — resubmitting the same payment cannot succeed — or **retryable**, meaning you can resubmit the same payment once the transient condition clears. | **Code** | **Description** | **Partner action** | | :- | :- | :- | | `payment_could_not_be_processed` | The payment could not be processed. | **Terminal** — Take no action. The cause is usually a compliance flag or a rejection by the receiving agent. | | `name_mismatch` | The name in the request does not match the name on the account. | **Terminal** — Send a new payment with the corrected beneficiary name. | | `name_not_validated` | Validation of the receiving account's name did not finish in time. | **Retryable** — Submit the same payment again; it succeeds once verification of the beneficiary name completes. | | `account_closed` | The receiving account is closed. | **Terminal** — Send a new payment to a different destination account. | | `account_number_incorrect` | The receiving account number is incorrect. | **Terminal** | ## Exceptions An account can close in the narrow window after Lead validates it but before the payment posts. If the account closes before validation, Lead rejects the payment. If it closes after validation but before the payment posts, the payment results in a return. ![Status Diagram For Docs (blockchain Payments) Page 1 (1)](https://mintcdn.com/lead/fkreJ13a-5Pe7tf3/images/Status-Diagram-for-Docs-\(blockchain_payments\)---Page-1-\(1\).png?fit=max\&auto=format\&n=fkreJ13a-5Pe7tf3\&q=85\&s=3248b38e616b41398b248032d774f2e1) # Statuses & Events Source: https://docs.lead.bank/products/blockchain-payments/statuses The statuses and webhook events for blockchain payments. ## Statuses | Status | Description | Webhook Event | | - | - | - | | `created` | Payment initiated in Lead's system. | `.payment_created` | | `under_review` | Payment flagged for manual review by compliance. | `.payment_under_review` | | `submitted` | Funds transferred to destination, settlement in progress. | `.payment_submitted` | | `posted` | Settlement complete, funds delivered to destination. | `.payment_posted` | | `rejected` | Payment rejected by Lead or partner; funds reversed. | `.payment_rejected` | | `canceled` | Payment canceled by Lead or customer. | `.payment_canceled` | #### Funding Source: USD at Lead ![Global Money Movement Page 1 (56)](https://mintcdn.com/lead/jWNk1F1P6GyMYHcT/images/Global-money-movement---Page-1-\(56\).png?fit=max\&auto=format\&n=jWNk1F1P6GyMYHcT\&q=85\&s=bc42996335cdf30428c599ca088a165b) ## Events | **Event** | **Description** | | :- | :- | | `.payment_created` | Lead creates the blockchain payment object. | | `.payment_under_review` | Compliance flags the payment for manual review. Lead either rejects the payment or clears it to continue. | | `.payment_submitted` | Lead submits the payment. | | `.payment_posted` | The payment posts and the funds arrive in the destination account or wallet. | | `.payment_rejected` | Lead or its partners reject the payment. | | `.payment_canceled` | Lead cancels the payment when the funds never arrive. | ## Returns A payment Lead submits successfully can still come back — for example, when the receiving account is closed. Lead credits the funds to the debtor and records the return on two payment objects: the original payment, and a new return payment carrying the funds back. The original payment settles at `posted`. There is no separate returned status, so read the `return` object to tell a delivered payment from a returned one. | **Field** | **Where It Appears** | **Description** | | :- | :- | :- | | `return.code` | Original payment and return payment | Machine-readable reason for the return: `account_closed`, `account_number_incorrect`, or `payment_returned`. | | `return.reason` | Original payment and return payment | Description of the same reason, for display to your customer. | | `related_blockchain_payments.return_blockchain_payment_ids` | Original payment | The return payments carrying the funds back. | | `related_blockchain_payments.original_blockchain_payment_id` | Return payment | The payment the funds come back for. | The return payment carries `payment_purpose.type: return` and moves straight to `posted`. The `return` purpose is response-only; Lead rejects a create request that sends it. Lead sends a `.payment_created` webhook for the return payment, followed by `.payment_posted`. Retrieve the return payment with [Retrieve a Blockchain Payment](/api-reference/endpoint/blockchain-payment/retrieve-a-blockchain-payment), using the ID from `related_blockchain_payments`. The list endpoint omits return payments. ## **Example Webhook Payload** Every blockchain payment webhook event shares this payload shape. ```json theme={null} { "id": "event_12345", "created_at": "2026-02-24T11:22:33Z", "event": "blockchain_payment.posted", "object": { "id": "blockchain_payment_8888", "debtor": { "account_identifier": { "type": "account_number_id", "value": "account_number_1234" }, "entity_id": "entity_67890" }, "creditor": { "payment_rail": "spei", "clabe": { "account_number": "00218090010000001234" }, "type": "business", "business": { "business_name": "Acme Mexico SA de CV" }, "address": { "line_one": "Av. Reforma 123", "city": "Ciudad de México", "country": "MX", "postal_code": "06600" } }, "creditor_agent": { "bank_name": "BBVA México", "country_code": "MX", "address": { "line_one": "Av. Paseo de la Reforma 505", "city": "Ciudad de México", "country": "MX", "postal_code": "06500" } }, "amounts": { "instructed_amount": 1000000, "instructed_currency_code": "USD", "settlement_currency_code": "MXN", "settlement_amount": 17461350, "settlement_exchange_rate": 1746 }, "payment_purpose": { "type": "invoice_payment" }, "reference": "INV-MXN-2026-001", "status": "posted", "created_at": "2026-02-24T11:22:33Z", "updated_at": "2026-02-24T11:22:33Z" } } ``` # Supported Blockchains and Fiat Rails Source: https://docs.lead.bank/products/blockchain-payments/supported-blockchains-and-fiat-rails Details about the rails and currencies Lead supports today. When you use blockchain payments, keep the following in mind: > [!CAUTION] > > Funds sent to **unsupported asset/blockchain pairs** or to **incorrect addresses** may be **irretrievable and permanently lost**. > [!CAUTION] > > Make sure you send amounts above the transaction minimum. See [Transaction Minimums](#transaction-minimums) below. > [!WARNING] > > Lead does not support USDB for users in the EEA due to regulatory restrictions. ## Supported Rails & Currencies | Rail | Currency | | - | - | | `ach` | Settlement currency must be set to **USD** | | `wire` | Settlement currency must be set to **USD** | | `sepa` | Settlement currency must be set to **EUR** | | `swift` | Settlement currency must be set to **USD** | | `spei` | Settlement currency must be set to **MXN** | | `pix` | Settlement currency must be set to **BRL** | | `faster_payments` | Settlement currency must be set to **GBP** | | `bre_b` | Settlement currency must be set to **COP** | | `co_bank_transfer` | Settlement currency must be set to **COP** | | `solana` | Settlement currency must be set to **USDC** or **USDB** | | `base` | Settlement currency must be set to **USDC** or **USDB** | | `ethereum` | Settlement currency must be set to **USDC** or **USDB** | > [!NOTE] > > Additional blockchains and currencies available upon request. Reach out to your Technical Account Manager for more details. ## **Transaction Minimums** The minimum is **\$3.00 on every rail** — `300` minor units (for example, cents) of `instructed_amount`. If you submit an `instructed_amount` below `300`, Lead rejects the payment at creation and returns HTTP `422` with an `invalid_parameters` entry for `amounts.instructed_amount`. Lead accepts only `USD` for `instructed_currency_code` — the debtor is always an `account_number_id` — so the minimum is the same \$3.00 regardless of the destination rail or its settlement currency. # USD Funding Source Source: https://docs.lead.bank/products/blockchain-payments/usd-funding-source Request to send USD to a foreign currency, or USD to stablecoins. The following examples show requests where the debtor sends dollars and the creditor receives foreign currency (over blockchain rails) or stablecoins. ## POST /v0/blockchain\_payments **Auth Scope:** blockchain\_payment/read\_write  ## Examples ### Fiat-Fiat ##### Request ```json theme={null} { "debtor": { "account_identifier": { "type": "account_number_id", "value": "account_number_1234" }, }, "creditor": { "payment_rail": "pix", "pix_key": { "pix_key": "12345678909", "document_number": "12345678900" }, "type": "business", "business": { "business_name": "Acme Brazil Ltda" }, "address": { "line_one": "Rua das Flores 100", "city": "Sao Paulo", "country": "BR", "postal_code": "01311-000" } }, "creditor_agent": { "bank_name": "Banco Santander Brasil", "country_code": "BR" }, "amounts": { "instructed_amount": 50000, "instructed_currency_code": "USD", "settlement_currency_code": "BRL" }, "payment_purpose": { "type": "invoice_payment" }, "reference": "INV-2026-001", } ``` ##### Success Response (200) ```json theme={null} { "id": "blockchain_payment_1234", "debtor": { "account_identifier": { "type": "account_number_id", "value": "account_number_1234" }, "entity_id": "entity_67890" }, "creditor": { "payment_rail": "pix", "pix_key": { "pix_key": "12345678909", "document_number": "12345678900" }, "type": "business", "business": { "business_name": "Acme Brazil Ltda" }, "address": { "line_one": "Rua das Flores 100", "city": "São Paulo", "country": "BR", "postal_code": "01311-000" } }, "creditor_agent": { "bank_name": "Banco Santander Brasil", "country_code": "BR", }, "amounts": { "instructed_amount": 50000, "instructed_currency_code": "USD", "settlement_currency_code": "BRL", "settlement_amount": 255700, "settlement_exchange_rate": 511 }, "payment_purpose": { "type": "invoice_payment" }, "reference": "INV-2026-001", "status": "created", "created_at": "2026-02-24T11:22:33Z", "updated_at": "2026-02-24T11:22:33Z" } ``` ### Fiat-to-Crypto ##### Request ```json theme={null} { "debtor": { "account_identifier": { "type": "account_number_id", "value": "account_number_1234" }, }, "creditor": { "payment_rail": "solana", "wallet": { "wallet_address": "9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM" }, "type": "individual", "individual": { "first_name": "Jane", "last_name": "Doe" }, "address": { "line_one": "456 Solana Ave", "city": "Miami", "country": "US", "state": "FL", "postal_code": "33101" } }, "amounts": { "instructed_amount": 10099, "instructed_currency_code": "USD", "settlement_currency_code": "USDC" }, "payment_purpose": { "type": "payment_for_services" }, "reference": "SOL-TRANSFER-001", } ``` ##### Success Response (200) ```json theme={null} { "id": "blockchain_payment_5678", "debtor": { "account_identifier": { "type": "account_number_id", "value": "account_number_1234" }, "entity_id": "entity_67890" }, "creditor": { "payment_rail": "solana", "wallet": { "wallet_address": "9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM" }, "type": "individual", "individual": { "first_name": "Jane", "last_name": "Doe" }, "address": { "line_one": "456 Solana Ave", "city": "Miami", "country": "US", "state": "FL", "postal_code": "33101" } }, "amounts": { "instructed_amount": 10099, "instructed_currency_code": "USD", "settlement_currency_code": "USDC", "settlement_amount": 10099 }, "payment_purpose": { "type": "payment_for_services" }, "reference": "SOL-TRANSFER-001", "status": "created", "created_at": "2026-02-24T11:22:33Z", "updated_at": "2026-02-24T11:22:33Z" } ``` # Checks FAQ Source: https://docs.lead.bank/products/checks/faq Frequently asked check questions. > [accordion] What cut-off times does Lead support for receiving X9 files? > > For outgoing check forwards (Deposit a Check), submit files to Lead by 6:30 a.m. ET for same-day settlement at 8:30 a.m. ET. For outgoing returns, the cut-off is 12:30 a.m. ET, also settling at 8:30 a.m. ET. > [accordion] How frequently can you submit X9 files? > > You can submit files intraday. Lead supports three settlement windows: 8:30 a.m., 1:00 p.m., and 5:30 p.m. ET. Target the first morning window for standard check forwards. > [accordion] What is the processing timeline after Lead receives your X9 file? > > After Lead receives a positive ACK from the Fed, Lead makes GL movements promptly. Funds become available to your customers upon crediting of the Customer FBO. Final settlement occurs on the `settlementDate` in the file — typically the same day for the 8:30 a.m. window. > [accordion] When do returns appear after initial file submission? > > Returns from the paying bank arrive via X9 files through the Fed and Lead forwards them to you as they are received. There is no fixed service-level agreement from the paying bank — returns can arrive within a few days or, in some cases, later. > [accordion] At what point is a deposit considered accepted? > > A deposit is accepted once Lead receives a positive ACK from the Fed and credits the Customer FBO. Funds are immediately available for spending at that point. > [accordion] Does Lead support conditional crediting before Fed settlement? > > No. Lead does not credit customers before receiving a positive ACK from the Fed on outgoing X9 files. > [accordion] How does lead communicate returns? > > Lead sends returns to you via X9 return files, following the Write a Check flow. When the paying bank contacts Lead's operations team directly outside of the Fed, Lead opens a case and contacts you as needed. > [accordion] Are there different cut-off times for Same-Day vs. Next-Day processing? > > Same-day settlement is available via the 8:30 a.m. ET window (submit your file by 6:30 a.m. ET). The 1:00 p.m. and 5:30 p.m. ET windows provide additional intraday settlement on the same business day. Checks on Pacific Island bank routing numbers (1214 or 3214 prefix) always settle the next business day. # Checks at Lead Source: https://docs.lead.bank/products/checks/overview Understand check flows utilizing the X9 file standard. Lead's Checks capabilities let you offer two primary check flows to your end-users: **depositing checks** and **writing checks**. Both flows use the [X9 file standard](https://www.frbservices.org/binaries/content/assets/crsocms/financial-services/check/setup/frb-x937-standards-reference.pdf) — an electronic check format that includes front and back check images along with structured payment data — and route through the Federal Reserve (Fed). > [!NOTE] > > Lead processes all checks via X9 files. There is no API-based check submission. ## Key Terminology The table below defines the core terms used throughout these guides. | **Term** | **Definition** | | :- | :- | | **Write a Check** | A customer writes a check and gives it to a recipient. The recipient deposits it at their bank, which submits it to the Fed. Lead receives the X9 file from the Fed and debits the customer account. | | **Deposit a Check** | A customer deposits a check via your app. You send Lead an X9 file; Lead submits it to the Fed and credits the customer account. | | **X9 File** | The standard electronic check file format. Each file contains check images (front and back) plus structured data: amount, check number, account number, and routing number. | | **Incoming X9** | An X9 file Lead receives from the Fed. Used in the Write a Check flow — results in a debit to the customer account. | | **Outgoing X9** | An X9 file Lead sends to the Fed. Used in the Deposit a Check flow — results in a credit to the customer account. | | **Settlement Date** | The date the Fed finalizes the funds movement for a given check file. | | **Return** | A check rejected after initial processing. For example, because the account is closed or fraud is suspected. Returns travel back via X9 files. | | **MICR Line** | Magnetic Ink Character Recognition. The printed line at the bottom of a check containing the routing number, account number, and check number. | | **Remote Deposit Capture (RDC)** | The process of depositing a check by photographing it in a mobile app rather than visiting a branch. | ## Write a Check Flow The Write a Check flow begins when your customer writes a check and gives it to a recipient. The recipient deposits it at another financial institution, which submits the check to the Fed. The Fed delivers it to Lead as an incoming X9 file. > [!NOTE] > > **Note** > > Lead does not provide check printing services. Partners are expected to use their own check printing vendor. > [!TIP] > > **Flow Summary** > > Your customer writes a check → The recipient deposits it at their bank → The receiving bank sends an X9 file to the Fed → The Fed delivers the X9 file to Lead → Lead routes it to you → Lead debits the customer account. ## Returns A return occurs when you determine that an incoming check must not be honored. To return a check, submit an outgoing X9 file containing the return entries. This follows the same path as the Deposit a Check flow. Common return reasons include: * Check details do not match the outstanding check registry * Check has already been redeemed (duplicate presentment) * Suspected fraud * Account closed or insufficient funds When handling a return, you have the following options: * Correct the check details and post to the customer account * Make a balance adjustment on the customer account * Submit an X9 return file to Lead (standard return) * Initiate a late check return by contacting Lead directly > [!WARNING] > > **Timing** > > Submit standard check returns within 24 hours of settlement. Returns initiated after this window are considered late and require direct coordination with Lead's operations team. ## Deposit a Check Flow The Deposit a Check flow begins when your customer deposits a check — typically by photographing it in your mobile app using Remote Deposit Capture (RDC). You send Lead an X9 file, Lead submits it to the Fed, and Lead credits funds to your customer. > [!TIP] > > **Flow Summary** > > Your customer photographs the check → You validate and process the check → You send an X9 file to Lead → Lead checks your daily limit → Lead submits the X9 file to the Fed → The Fed sends an acknowledgement (ACK) → Lead credits the customer FBO → Funds settle at the Fed. > [!WARNING] > > **Funds Availability** > > Funds become immediately available for spend once Lead credits the Customer FBO. Lead notifies you in advance of any change to this policy. ## Validation and Fraud Controls Lead acts as a pass-through in the Deposit a Check flow. You are responsible for all check losses. **Build robust pre-submission controls appropriate for your risk appetite before going live.** ## Returns from the Paying Bank After Lead submits a check to the Fed and the Fed delivers it to the paying bank, the paying bank may return the check — for example, if the account is closed or fraud is detected. There are two ways a return reaches you: * The paying bank submits an X9 return file to the Fed. The Fed routes it to Lead, who forwards it to you via the Write a Check flow. * The paying bank contacts Lead's operations team directly, outside of the Fed. Lead's team opens a case and contacts you as needed. If you absorb the loss or charge it back to your customer, that is an internal funds movement in your system. To formally return a check, submit an outgoing X9 return file to Lead. ## Additional Resources * [Fed X9 Standards Reference: ](https://www.frbservices.org/binaries/content/assets/crsocms/financial-services/check/setup/frb-x937-standards-reference.pdf)[frbservices.org](http://frbservices.org) # Check Settlement Source: https://docs.lead.bank/products/checks/settlement Lead supports three intraday settlement windows aligned with Fed processing schedules for checks. | **File Type** | **Submit By (ET)** | **Settlement Time (ET)** | | :- | :- | :- | | **Outgoing Checks** | 6:30 a.m. | 8:30 a.m. | | **Outgoing Returns** | 12:30 a.m. | 8:30 a.m. | | **Incoming Checks** | — | 8:30 a.m. / 1:00 p.m. / 5:30 p.m. | | **Incoming Returns** | — | 8:30 a.m. / 1:00 p.m. / 5:30 p.m. | > [!TIP] > > **Next Business Day Settlement** > > Checks drawn on Pacific Island banks — those with routing numbers beginning with 1214 or 3214 — always settle the next business day, regardless of submission time. # The Core Account Object Source: https://docs.lead.bank/products/core-account/core-account-object Field-level reference for the Core Account object, including account types and entity relationships. > [!NOTE] > > The Core Accounts API is in beta. Beta APIs can change without a version increment. Changes are announced in advance, and your Technical Account Manager works with you on them. See [Versioning and backwards compatibility](/core-concepts/platform/versioning-and-backwards-compatibility). A core account is a bank account on Lead's core. Lead creates one for each account your program needs during onboarding. You read them with `GET /v2/core_accounts` and `GET /v2/core_accounts/{id}`. ```json theme={null} { "id": "core_account_2xYv6Kn3Jp7QuS2lY5mAbC0dE4f", "name": "Partner FBO", "type": "attributed", "status": "active", "entities": { "account_holder_type": "lead", "account_holders": ["entity_lead_001"], "authorized_users": [] }, "created_at": "2026-03-02T14:00:00Z", "updated_at": "2026-03-02T14:00:00Z" } ``` ## Fields | Field | Type | Description | | :- | :- | :- | | `id` | string | Unique identifier, prefixed `core_account_`. | | `name` | string | Human-readable name set by Lead, for example "Consumer FBO" or "Operating DDA". Matches the account title you see in the Daily Balance report and online banking. | | `type` | enum | What the account is for: `attributed`, `direct`, or `shadow`. See [Account types](#account-types). | | `status` | enum | `active`, `inactive`, or `closed`. Lead manages all transitions. See [Core Account Statuses](/products/core-account/statuses). | | `entities` | object | Who holds the account. See [The entities block](#the-entities-block). | | `created_at`, `updated_at` | timestamp | RFC 3339, UTC. | ## Account types * `attributed`**.** An FBO whose funds are fully attributed to end customers. Each customer's share is a user balance beneath this account. Most consumer deposit programs have one of these. * `direct`**.** Everything else your program runs on: operating, settlement, revenue, and reserve DDAs, and any FBO that is not attributed at the customer level. Account numbers can attach directly to a direct account's balance, so payments can route to it. * `shadow`**.** A sweep or placement position, such as IntraFi ICS, that mirrors funds held elsewhere. You can read its balance. Nothing transacts against it directly and account numbers never attach. ## The entities block | Field | Type | Description | | :- | :- | :- | | `account_holder_type` | enum | `lead` if Lead holds the account, `partner` if your company does. | | `account_holders` | array | Entity IDs of the holders. | | `authorized_users` | array | Entity IDs of authorized users. | The entities referenced here are `lead` or `partner` entities that Lead sets up during onboarding. They are read only, so you cannot create or update them. Retrieve one with `GET /v2/entities/{id}` once Entity v2 is turned on for your program. Entity v0 does not return them, and `GET /v0/entities/{id}` returns `404`. See [Entity v2](/v2/products/entity/overview). ## List and retrieve `GET /v2/core_accounts` returns every core account visible to your program. Filters: * `type`. One of `attributed`, `direct`, `shadow`. * `limit`, `starting_after`, `ending_before`. Cursor pagination. Cursors are core account IDs. `GET /v2/core_accounts/{id}` returns one account. Returns `404` if the ID does not exist or belongs to another program. Neither endpoint triggers webhooks or business validations. Errors are the standard set on the [Errors](/api-reference/using-the-api/errors) page. ## Related [Core Account Overview](/products/core-account/overview) · [Core Account Statuses](/products/core-account/statuses) · [The Core Balance Object](/products/core-balance/core-balance-object) · [Account Numbers](/products/account-number/overview) # Core Accounts: The Bank Accounts Behind Your Program Source: https://docs.lead.bank/products/core-account/overview What a core account is, what the type field is for, who holds it, and how it relates to balances, transactions, and account numbers. > [!NOTE] > > The Core Accounts API is in beta. Beta APIs can change without a version increment. Changes are announced in advance, and your Technical Account Manager works with you on them. See [Versioning and backwards compatibility](/core-concepts/platform/versioning-and-backwards-compatibility). A core account is a real bank account on Lead's core. Lead opens one for each account your program needs during onboarding: the FBO that pools your customers' deposits, and the operating, settlement, revenue, and reserve accounts your program runs on. You do not create, change, or close them. You read them. Throughout this section, *account* means a core account. Your customers' accounts are user accounts and are documented under [Customers & Accounts](/products/entity/overview). ## Account types Every core account has a `type`: `attributed`, `direct`, or `shadow`. Use it to find the account you need. Filter on `direct` to find the accounts you can originate payments from, and on `attributed` to find the FBO your customer balances settle into. [The Core Account Object](/products/core-account/core-account-object) defines each type. ## Who holds a core account Each core account names the entities that hold it: whether Lead or your company is the account holder, plus any authorized user. [The Core Account Object](/products/core-account/core-account-object) documents the `entities` block. ## How core accounts relate to the rest of the model * **Core balance.** Each core account has one core balance today. The balance is where the money is: posted funds, holds, sweeps, overdraft, and interest. Read it with the [Core Balances API](/products/core-balance/overview). * **Core transactions.** Every ledger entry that changes the balance is a core transaction. You list them by balance, not by account. See [Core Transactions](/products/core-transaction/overview). * **Account numbers.** On a direct account, account numbers attach to the core balance and make it routable. See [Account Numbers](/products/account-number/overview). * **Payments.** ACH, wires, instant payments, and internal transfers reference an `account_number_id`. Lead resolves the core balance and core account behind it. ## What you can do List and retrieve your core accounts. Both operations are read only. ## What you cannot do * Create, update, activate, deactivate, or close a core account. Lead manages every transition. See [Core Account Statuses](/products/core-account/statuses). * Subscribe to webhooks today. Core accounts change rarely, so cache the list and refresh it daily or when your Lead team tells you an account has been added. See [Banking Infrastructure](/products/banking-infrastructure/overview#lead-manages-you-read) for what is planned. ## In this section * [The Core Account Object](/products/core-account/core-account-object) * [Core Account Statuses](/products/core-account/statuses) # Core Account Statuses Source: https://docs.lead.bank/products/core-account/statuses Lifecycle of a core account, who changes it, and how to observe a change. > [!NOTE] > > The Core Accounts API is in beta. Beta APIs can change without a version increment. Changes are announced in advance, and your Technical Account Manager works with you on them. See [Versioning and backwards compatibility](/core-concepts/platform/versioning-and-backwards-compatibility). Lead manages every core account status. You never call an endpoint to change one, and the status you read is whatever Lead has set. This page tells you what each status means and what to expect when one changes. ## Lifecycle ```mermaid theme={null} flowchart LR subgraph live [ ] direction TB active <--> inactive end active --> closed inactive --> closed style live fill:none,stroke:none ``` ## Statuses | **Status** | **Description** | **Notes** | | - | - | - | | `active` | The account is operating normally. | Its core balance can move, and account numbers on that balance can transact. | | `inactive` | Lead has paused the account. Funds stay on the ledger. | Account numbers on the balance cannot send or receive while the account is inactive. | | `closed` | Lead has closed the account on the core. Terminal. | The account stays readable so historical core transactions still resolve. | ## Transitions `active` and `inactive` move between each other. Either can move to `closed`. Nothing moves out of `closed`. Your Lead team will tell you before an account you depend on is deactivated or closed. Status changes are rare. ## Relationship to the core balance A core account and its core balance normally change status together. If you see them disagree, treat the balance as authoritative for whether money can move, and contact your Technical Account Manager. Account numbers keep their own status, so an account number can show `active` and still not transact while its account is inactive. If payments fail unexpectedly, check the core account and core balance status first. ## Webhooks Core accounts do not emit events today. Status changes are Lead-initiated and rare, so poll `GET /v2/core_accounts/{id}` at the cadence your use case needs. A daily refresh is enough for most programs. ## Related [The Core Account Object](/products/core-account/core-account-object) · [Core Balance Statuses](/products/core-balance/statuses) · [Account Number Statuses](/products/account-number/statuses) · [Webhooks & Events](/api-reference/using-the-api/webhooks) # The Core Balance Object Source: https://docs.lead.bank/products/core-balance/core-balance-object Field-level reference for the Core Balance object, including the amounts definitions and formulas, overdraft, and interest. > [!NOTE] > > The Core Balances API is in beta. Beta APIs can change without a version increment. Changes are announced in advance, and your Technical Account Manager works with you on them. See [Versioning and backwards compatibility](/core-concepts/platform/versioning-and-backwards-compatibility). A core balance is a balance position within a core account. It is where the money actually sits. Read them with `GET /v2/core_balances` and `GET /v2/core_balances/{id}`. ```json theme={null} { "id": "core_balance_2xYw9Lp4Kq8RvT3mZ6nBcD1eF7g", "core_account_id": "core_account_2xYv6Kn3Jp7QuS2lY5mAbC0dE4f", "name": "Partner FBO", "status": "active", "currency_code": "USD", "amounts": { "spendable": 2070115, "cash_available": 1070115, "posted": 1080115, "sweeps": 0, "holds": 10000 }, "overdraft": { "limit": 1000000, "used": 0, "unused": 1000000 }, "interest": { "rate": null, "accrued": 0 }, "created_at": "2026-03-02T14:00:00Z", "updated_at": "2026-09-25T15:50:50Z" } ``` ## Fields | Field | Type | Description | | :- | :- | :- | | `id` | string | Unique identifier, prefixed `core_balance_`. | | `core_account_id` | string | The parent core account. | | `name` | string | Human-readable name set by Lead. | | `status` | enum | `active`, `inactive`, or `closed`. Lead managed. See [Core Balance Statuses](/products/core-balance/statuses). | | `currency_code` | string | ISO 4217. | | `amounts` | object | The balance breakdown. See [The amounts block](#the-amounts-block). | | `overdraft` | object | Overdraft facility on this balance. See [The overdraft block](#the-overdraft-block). | | `interest` | object | Interest position. See [The interest block](#the-interest-block). | | `created_at`, `updated_at` | timestamp | RFC 3339, UTC. | All amounts are signed integers in minor units. `1500` is \$15.00. ## The amounts block Five figures, two of them derived. | Field | Description | | :- | :- | | `posted` | Everything that has fully posted to the ledger. This is the closing balance figure you see in the Daily Balance report. | | `holds` | Funds that are reserved for pending transactions. | | `sweeps` | Funds sitting in linked sweep balances (for example IntraFi) that can be drawn back on demand. | | `cash_available` | Actual cash net of holds. `posted` minus `holds`. | | `spendable` | What you can move right now. `cash_available` plus `overdraft.unused` plus `sweeps`. | > [!WARNING] > > `spendable` may include overdraft capacity. A balance with `cash_available` of zero can still show a positive `spendable` if the account has an overdraft limit. Do not present `spendable` as cash on hand. ## The overdraft block | Field | Description | | :- | :- | | `limit` | The maximum overdraft facility on this balance. Zero if none. | | `used` | Overdraft currently drawn. | | `unused` | Remaining capacity. `limit` minus `used`. This is the portion that flows into `spendable`. | ## The interest block | Field | Description | | :- | :- | | `rate` | Annualized rate as a decimal string with six places, for example `"1.000000"`. | | `accrued` | Interest accrued but not yet posted, in minor units. | ## List and retrieve `GET /v2/core_balances` returns every core balance visible to your program. Filters: * `core_account_id`. Balances under one core account. * `limit`, `starting_after`, `ending_before`. Cursor pagination. Cursors are core balance IDs. `GET /v2/core_balances/{id}` returns one balance. `404` if the ID does not exist or belongs to another program. Each request reads Lead's core directly, so the figures reflect the ledger at the time of the request. ## Related [Core Balance Overview](/products/core-balance/overview) · [Core Balance Statuses](/products/core-balance/statuses) · [The Core Account Object](/products/core-account/core-account-object) · [The Core Transaction Object](/products/core-transaction/core-transaction-object) · [Daily Balance report](/file-reference/reports/daily-balance) # Core Balances: Where Your Program's Money Sits Source: https://docs.lead.bank/products/core-balance/overview What a core balance is, which figure to use for what, and how it relates to the account, transactions, and account numbers. > [!NOTE] > > The Core Balances API is in beta. Beta APIs can change without a version increment. Changes are announced in advance, and your Technical Account Manager works with you on them. See [Versioning and backwards compatibility](/core-concepts/platform/versioning-and-backwards-compatibility). A core balance is the balance position within a core account. It is where the money actually is: posted funds, holds, sweeps, overdraft, and interest, with a derived spendable figure. Lead creates it with the account. You read it. ## Which figure to use * `spendable` to decide whether a payment can go out. It is the figure Lead's own authorization uses. * `cash_available` for anything customer facing, such as a treasury dashboard, because it shows real cash without borrowed or swept funds. * `posted` to reconcile against the Daily Balance report and against the sum of core transactions. > [!WARNING] > > `spendable` may include overdraft capacity. A balance with `cash_available` of zero can still show a positive `spendable` if the account has an overdraft limit. Do not present `spendable` as cash on hand. [The Core Balance Object](/products/core-balance/core-balance-object) defines each figure and the formulas behind the derived ones. ## How core balances relate to the rest of the model * **Core account.** `core_account_id` names the parent. A balance normally carries the same status as its account. See [Core Balance Statuses](/products/core-balance/statuses). * **Core transactions.** Every core transaction names the `core_balance_id` it affected. * **Account numbers.** On a `direct` account, account numbers attach to this balance, so an incoming payment to one of those numbers lands here. ## What you can do List and retrieve your core balances. Both operations are read only. Each request reads Lead's core directly, so the figures reflect the ledger at the time of the request. ## What you cannot do * Change a balance directly. Money moves only through payments and Lead's own core activity. * Subscribe to webhooks today. Poll the retrieve endpoint at the cadence your use case needs. See [Banking Infrastructure](/products/banking-infrastructure/overview#lead-manages-you-read) for what is planned. ## In this section * [The Core Balance Object](/products/core-balance/core-balance-object) * [Core Balance Statuses](/products/core-balance/statuses) # Core Balance Statuses Source: https://docs.lead.bank/products/core-balance/statuses A core balance shares its account's lifecycle; what an inactive balance means for account numbers; how to observe changes. > [!NOTE] > > The Core Balances API is in beta. Beta APIs can change without a version increment. Changes are announced in advance, and your Technical Account Manager works with you on them. See [Versioning and backwards compatibility](/core-concepts/platform/versioning-and-backwards-compatibility). Lead manages every core balance status. You never call an endpoint to change one. A core balance shares its lifecycle with the core account it belongs to, and the two normally change together. [Core Account Statuses](/products/core-account/statuses) describes that lifecycle in full; this page covers what is specific to the balance. ## Lifecycle ```mermaid theme={null} flowchart LR subgraph live [ ] direction TB active <--> inactive end active --> closed inactive --> closed style live fill:none,stroke:none ``` ## Statuses | **Status** | **Description** | **Notes** | | - | - | - | | `active` | The balance is operating normally. | Funds can move. Account numbers attached to the balance can transact. | | `inactive` | Lead has paused the balance. Funds stay on the ledger. | Account numbers attached to the balance cannot send or receive while it is inactive. | | `closed` | Lead has closed the balance on the core. Terminal. | The balance stays readable so historical core transactions still resolve. | ## What an inactive balance means for account numbers Account numbers keep their own status, so an account number can show `active` and still not transact while its account is inactive. If payments fail unexpectedly, check the core account and core balance status first. If the balance and its account disagree, treat the balance as authoritative for whether money can move, and contact your Technical Account Manager. ## Observing changes Core balances do not emit events today, for status changes or for amount changes. Poll `GET /v2/core_balances/{id}` at the cadence your use case needs. ## Related [The Core Balance Object](/products/core-balance/core-balance-object) · [Core Account Statuses](/products/core-account/statuses) · [Account Number Statuses](/products/account-number/statuses) # The Core Transaction Object Source: https://docs.lead.bank/products/core-transaction/core-transaction-object Field-level reference for the Core Transaction object, the type enum with lookups, the single posted state, and list filters. > [!NOTE] > > The Core Transactions API is in beta. Beta APIs can change without a version increment. Changes are announced in advance, and your Technical Account Manager works with you on them. See [Versioning and backwards compatibility](/core-concepts/platform/versioning-and-backwards-compatibility). A core transaction is a single ledger entry that changed a core balance. Lead creates them. You read them with `GET /v2/core_transactions` and `GET /v2/core_transactions/{id}`. ```json theme={null} { "id": "core_transaction_3JpKd8vN2wQxT5mRz7bYaL4cE9f", "core_balance_id": "core_balance_2xYw9Lp4Kq8RvT3mZ6nBcD1eF7g", "type": "ach", "description": "Incoming ach_3JpCw2kQ9rTb7yLm4XnVdE8oF1g NORTHWIND LLC PAYROLL", "amount": 248250, "currency_code": "USD", "created_at": "2026-09-25T15:02:14Z", "updated_at": "2026-09-25T15:02:14Z" } ``` ## Fields | Field | Type | Description | | :- | :- | :- | | `id` | string | Unique identifier, prefixed `core_transaction_`. | | `core_balance_id` | string | The core balance this entry affected. | | `type` | enum | The rail or mechanism that created the entry. See [The type enum](#the-type-enum). | | `description` | string, max 120 | Human-readable memo. Useful for eyeballing, not for matching. Use `type` and the core transaction ID fields on the payment object to match. | | `amount` | integer | Signed, minor units. Positive is a credit to the balance, negative is a debit. | | `currency_code` | string | ISO 4217. | | `created_at` | timestamp | When the entry posted and affected the balance. UTC. | | `updated_at` | timestamp | Usually equals `created_at`. | A core transaction has a single state, `posted`. It exists only once it has affected the balance. There is no pending state and no status field. Corrections are new, offsetting entries with their own IDs. ## The type enum When a value names a Lead platform object, the core transaction has a matching payment record you can retrieve. The rest are posted by Lead and have no payment object. | Value | Definition | Lead platform object | | :- | :- | :- | | `ach` | An ACH origination, return, or reversal. | [ACH](/products/ach/overview) | | `checks` | A check deposited, paid, or returned. | [Check](/products/checks/overview) | | `domestic_wires` | A domestic wire sent or received, or the return of one. | [Wire](/products/wire/wire-object) | | `international_wires` | An international wire sent or received, or the return of one. | [Wire](/products/wire/wire-object) | | `instant_payments` | An RTP or FedNow payment sent or received, or the return of one. | [Instant Payment](/products/instant-payments/the-instant-payment-object) | | `blockchain_payments` | A blockchain payment or its refund. | [Blockchain Payment](/products/blockchain-payments/overview) | | `internal_transfers` | A book transfer between two Lead accounts. | [Internal Transfer](/products/internal-transfer/internal-transfer-object) | | `fundings` | A loan disbursement. | [Funding](/v2/products/fundings/funding-object) | | `receivable_sales` | The settlement of a receivable sale. | [Receivable Sale](/v2/products/receivable-sales/receivable-sale-object) | | `interest` | Interest accrued, credited, or adjusted on the balance. | None. Posted by Lead. | | `fees` | A fee Lead charged to the balance, or a refund of one. | None. Posted by Lead. | | `sweeps` | Funds moved into or out of a sweep position. | None. Posted by Lead. | | `lead_generated` | An entry Lead creates outside of a program's own activity: transfers Lead initiates to operate a program's funds flow (including digital asset settlement), network settlement entries, charge-offs, withholding, corrections, and manual adjustments. | None. Posted by Lead. | | `legacy_banking` | Activity from Lead's banking systems outside the platform: card, cash, and ATM activity and clearing movements. Does not produce a platform object. Lead is discontinuing these products; this value will be deprecated once they are retired. | None. Posted by Lead. | ## List and retrieve `GET /v2/core_transactions` lists entries for one balance. Filters: * `core_balance_id` (required). The balance to list. * `type`. One of the enum values. An unknown value returns `400 parameters_invalid`. * `created_at[after]`, `created_at[on_or_after]`, `created_at[before]`, `created_at[on_or_before]`. Standard time window. * `limit`, `starting_after`, `ending_before`. Cursor pagination. Cursors are core transaction IDs. `GET /v2/core_transactions/{id}` returns one entry. `404` if not found or not yours. ## Related [Core Transaction Overview](/products/core-transaction/overview) · [The Core Balance Object](/products/core-balance/core-balance-object) · [The ACH Object](/products/ach/ach-object) · [The Wire Object](/products/wire/wire-object) · [Daily Activity report](/file-reference/reports/daily-activity) # Core Transactions: Your Program's Ledger Entries Source: https://docs.lead.bank/products/core-transaction/overview What a core transaction is, how to tie one to the payment that caused it, timing, and how to read them today. > [!NOTE] > > The Core Transactions API is in beta. Beta APIs can change without a version increment. Changes are announced in advance, and your Technical Account Manager works with you on them. See [Versioning and backwards compatibility](/core-concepts/platform/versioning-and-backwards-compatibility). A core transaction is a single ledger entry that changed a core balance. Lead creates them: when a payment posts, when interest or a fee is applied, when funds sweep. You read them. There is nothing to create and nothing to reverse. Corrections are new, offsetting entries with their own IDs. A core transaction has one state, `posted`. It exists only once it has affected the balance. There is no pending state and no status field. ## Types at a glance `type` names the rail or mechanism that created the entry. ACH, checks, wires, instant payments, blockchain payments, internal transfers, fundings, and receivable sales each have a matching payment object on the Lead platform. Interest, fees, sweeps, Lead-generated entries, and legacy banking activity are posted by Lead and have no payment object. [The Core Transaction Object](/products/core-transaction/core-transaction-object#the-type-enum) lists every value. ## From a payment to its ledger entries, and back The join works in both directions. * **Payment to ledger.** Once a payment posts, the payment object carries the IDs of the core transactions it produced, in a shape that fits the rail. * **Ledger to payment.** Read `type`, then call that rail's list endpoint with `core_transaction_id={id}`. One core transaction can map to many payments, for example one settlement entry covering a batch of ACH entries. A core transaction can exist before the object it links to is visible on its own endpoint. This is expected. If your workflow needs both, wait for the payment object's posted webhook rather than polling the core transaction list. ## Reading core transactions List entries for one balance, filtered by `type` and a `created_at` window, or retrieve one by ID. Core transactions do not emit webhooks today, so poll the list with a `created_at` window at whatever cadence your reconciliation runs. A suite of core transaction webhooks is planned; see [Banking Infrastructure](/products/banking-infrastructure/overview#lead-manages-you-read). ## In this section * [The Core Transaction Object](/products/core-transaction/core-transaction-object) # Beneficial Ownership Requirements Source: https://docs.lead.bank/products/entity/beneficial-ownership Which beneficial owners and control persons Lead requires for business entities, the 25% threshold, and the drill-down rule for indirect ownership through holding companies. Business entities must arrive with their ownership structure resolved to **natural persons** — linked via the `beneficial_owners` and `control_persons` objects ([The Entity Object](/products/entity/entity-object#linkage-objects-resolving-ownership-to-people)). This page covers who must be reported, at what threshold, and how to handle ownership through intermediate companies. > [!TIP] > > #### Requirements > > Lead requires Beneficial Ownership information in line with the CIP program reviewed during Due Diligence. At a minimum, this should include **all Beneficial Owners (UBOs) who are natural persons** with **direct or indirect** ownership of 25% or greater. > > * **Control Person:** you must also identify *one* natural person with significant responsibility to control, manage, or direct the business (e.g., CEO, COO, President), required regardless of ownership percentage. > * **Thresholds:** if your KYB process expressly states a lower percentage than 25%, all beneficial owners meeting your stated percentage must be provided. ## The "Drill-Down" Rule A beneficial owner *must* be a natural person. If a business entity (a parent or holding company) owns 25% or more of the customer, you **cannot** list that entity as the owner. Instead, apply the same ownership requirement to *that* entity's owners. Continue up the chain until you have identified all *natural persons* with a 25%-or-greater *indirect* stake in the original customer. > [accordion] Simple Ownership (Bob's Pizza Company) > > * **Customer:** Bob's Pizza Company > * **Owners:** Alan (individual, 60%) · Bob (individual, 40%, also CEO) > * **Other individual:** Charlie (an authorized signer on the account) > * **Action:** > 1. Create individual profiles for Alan, Bob, and Charlie meeting [authorized-signer data requirements](/products/entity/roles#data-requirements). > 2. Create the business profile for Bob's Pizza Company. > 3. Link **Alan** as a **beneficial owner** (owns >25%). > 4. Link **Bob** as a **beneficial owner** (owns >25%) AND as the **control person** (CEO). > 5. Charlie does not need to be linked as an owner or control person. > [accordion] Complex Ownership (SaaS Co) > > * **Customer:** SaaS Co · **Immediate owners:** Parent Corp (entity, 80%) · Jane Smith (individual, 20%) > * Drill down into Parent Corp (an entity owning >25%). **Parent Corp's owners:** Holding LLC (entity, 50%) · Mark Lee (individual, 50%) > * Drill down again into Holding LLC. **Holding LLC's owner:** Susan Kay (individual, 100%) > * **Final UBO calculation for SaaS Co:** > * Jane Smith: 20% direct → **not** a 25% UBO > * Mark Lee: 50% of 80% = 40% indirect → **is** a 25% UBO > * Susan Kay: 100% of 50% of 80% = 40% indirect → **is** a 25% UBO > * **Conclusion:** provide profiles for **Mark Lee** and **Susan Kay** as beneficial owners ([authorized-signer data requirements](/products/entity/roles#data-requirements)); do **not** report Parent Corp or Holding LLC as owners; *also* identify and provide the profile for SaaS Co's **control person** (e.g., its CEO), who may or may not be one of these individuals. # The Entity Object Source: https://docs.lead.bank/products/entity/entity-object Field-level reference for the Entity object across its three shapes — individual, business, and sole proprietorship — including attestation fields, identification rules, linkage objects, and role_details. An Entity is one object with three shapes, discriminated by `type`: `individual`, `business`, and `sole_prop`. All three share the attestation and metadata fields; they differ in their details object and in how they link to other entities. Create with `POST /v0/entities` and a required `Idempotency-Key` header (up to 255 characters). ## Common Fields (All Three Shapes) | **Attribute** | **Type** | **Description** | | :- | :- | :- | | `id` | string | Unique Entity ID, prefixed `entity_`. Server-generated, returned on creation. | | `client_customer_id` | string (≤64) | Your identifier for the entity. **Must be unique — a create with an existing value returns 409.** Retrievable via `GET /v0/entities?client_customer_id=…`. | | `type` | enum | `individual` · `business` · `sole_prop`. Determines which details object is required. | | `intended_roles` | array | Optional synchronous role validation: `account_holder`, `minor_account_holder`, `authorized_signer`, `authorized_user`. **All-or-nothing** — if any listed role fails validation, the request fails. For `business` / `sole_prop`, pass only `account_holder`. See [Roles](/products/entity/roles) and [Troubleshooting](/products/entity/troubleshooting). | | `risk_score` | enum | `low` · `medium` · `high` — your risk score, per the mapping you provided Lead. Required for account-holder eligibility. | | `kyc_details` | object | `{ result, screened_at }` — result ∈ `pending` / `passed` / `failed`; `screened_at` must be a past timestamp. Your attestation of your KYC/KYB outcome. | | `ofac_details` | object | `{ result, screened_at }` — same enum and past-timestamp rule. Your attestation of OFAC screening. | | `rfi_details` | object | `{ result, requested_at }` — result ∈ `requested` / `completed`. Leave blank if no RFI has been sent to the customer. | | `credit_details` | array | Credit-bureau data: `credit_report_source` (`equifax` / `experian` / `transunion`) and `credit_pulled_at` required; then **exactly one of** `credit_score` (≤ 850) **or** `credit_report_non_score_value` (`unestablished` / `frozen` — for credit files without a numeric score). The entity's `credit_details` is a living record you update over time. The `details.credit.report` on an Application or Account is a point-in-time capture of the pull used for that credit decision, so the two can legitimately differ. | | `role_details` | array | **Response-only.** Per role: `name`, `status` (`active` / `inactive`), and `criteria_details[]` of `{ entity_id, failed_checks[] }` naming exactly which checks fail and on which entity — including child entities. The `minor_account_holder` entry appears only where the role is available to the program; when it is not, the entry is omitted rather than returned inactive. How to read it: [Troubleshooting](/products/entity/troubleshooting). | | `metadata` | object | Arbitrary key-value pairs. | ## `individual_details` (Required for `individual`) Required within it: `first_name`, `last_name`, and `identification_details`. First name must be at least 1 alphanumeric character. Last name must be at least 2. The `identification_details` object must always be present, but only its `type` is required — whether it must also carry a tax identification or identification documents depends on the roles the individual will hold ([Identification](#identification-for-us-and-non-us-entities)). Every other field is optional to create the entity and becomes required only for the roles that need it ([Roles](/products/entity/roles#data-requirements)). | **Attribute** | **Notes** | | :- | :- | | `first_name` / `middle_name` / `last_name` / `preferred_first_name` | Legal names; preferred first name optional. | | `date_of_birth` | `YYYY-MM-DD`. Account holders and authorized signers must be 18+; `minor_account_holder` requires 16–17 ([Roles](/products/entity/roles)). | | `occupation` | Optional. | | `contact_methods` | Array of `{ type: email, email }` or `{ type: phone_number, phone_number }`. Emails must be real-world `local-part@domain.tld` forms; phone numbers must follow E.123 (`+` country code with spacing — [Workflow](/products/entity/workflow#create-and-update-validations)). | | `address_details` | `physical_address`, `mailing_address`, `other_addresses[]` — see [Address Rules](#address-rules) below. | | `identification_details` | Always present, discriminated by `type` (`us_entity` / `non_us_entity`). The tax identification or documents inside it are required only for roles that need government-verified identification — see [Identification](#identification-for-us-and-non-us-entities) below. | | `additional_documents` | Optional supporting documents: `bank_statement`, `utility_bills`, `proof_of_address`, `investigation_report`, `financial_statement`, `public_records`, `adverse_media`, `id_selfie`, `other` (with `description` required for `other`). | ## `business_details` (Required for `business` and `sole_prop`) Required within it: `name` (≥2 characters), `identification_details`, and `address_details`. | **Attribute** | **Notes** | | :- | :- | | `type` | `corporation` · `partnership` · `sole_prop` · `llc` · `trust` · `cooperative` · `other`. **A `business` entity cannot use `sole_prop` as its business type; a `sole_prop` entity must.** | | `name` / `doing_business_as` | Legal name; DBA if operating under a different name. | | `industry` | NAICS code(s), 2–6 digits, 2022 reference files. | | `gross_annual_revenue` + `currency_code` | Prior fiscal year revenue; ISO 4217. | | `website` | Must start with `http://` or `https://`. | | `contact_methods` / `address_details` / `identification_details` / `additional_documents` | As for individuals; business identification-document types differ (formation documents, certificates of good standing, etc.). | ## Linkage Objects Resolving Ownership to People Business-family entities link to **individual** entities rather than embedding their data — create the individuals first ([Workflow](/products/entity/workflow)), then reference them: | **Object** | **On** | **Required fields** | **Notes** | | :- | :- | :- | :- | | `beneficial_owners[]` | `business` | `entity_id` | Plus optional `ownership_percentage` (0–100.00 or 0–1.00 decimal) and `relationship_established_at`. Who must be listed, the 25% threshold, and the drill-down rule: [Beneficial Ownership Requirements](/products/entity/beneficial-ownership). An empty array is a valid submission when there are genuinely no qualifying owners. | | `control_persons[]` | `business` | `entity_id`, `title` | At least one is required for account-holder eligibility (`CheckControlPersonExists`). | | `sole_proprietor` | `sole_prop` (required) | `entity_id` | The individual behind the sole proprietorship. | Each referenced individual must meet **authorized-signer data requirements** — a child entity failing its checks makes the parent's role `inactive`, with `criteria_details` pointing at the child's `entity_id` ([Troubleshooting](/products/entity/troubleshooting)). ## Identification for US and Non-US Entities The `identification_details` object is required on every entity and is discriminated by `type` — whether the entity has a US tax identification. Only `type` is required to create the entity; what must accompany it depends on the roles the entity will hold: | **Role or linkage** | **`us_entity`** | **`non_us_entity`** | | :- | :- | :- | | `authorized_user` only | `type` alone; `tax_identification` optional | `type` alone; `identification_documents` optional | | `authorized_signer` · `account_holder` · `minor_account_holder` · referenced as a beneficial owner, control person, or sole proprietor | `tax_identification` required | At least one `identification_documents[]` entry required | Field rules for each shape: * **`us_entity`** — `tax_identification` with `type` (`ssn` / `itin` / `ein`) and a 9-digit `value`. Rules: **SSNs must not start with 9** (ITINs mistakenly reported as SSNs are the most common failure); **EINs begin 00–99; ITINs begin with 9.** Individuals: SSN or ITIN. Businesses: EIN — except single-member LLCs with no EIN, where SSN or ITIN may be used. Sole props: any of the three. `type` is only a discriminator — `us_entity` with no `tax_identification` is accepted. For a US person whose tax identification you do not collect yet, send `us_entity` so the record does not have to switch type when you add it later. * **`non_us_entity`** — at least one government-verified `identification_documents[]` entry for any role other than `authorized_user` (see the table above). Per entry: `type`, `identification_number`, `issuing_country` required (plus `issuing_state` for US-issued, `expiration_date`, `description` when type is `other`). Individual document types: `drivers_license`, `state_or_provincial_id`, `passport`, `permanent_residency_id`, `military_id`, `national_id`, `matriculate_id`, `other`. Business types: `tax_certificate`, `tax_returns`, `partnership_agreement`, `certificate_of_good_standing`, `formation_document`, `proof_of_place_on_stock_exchange`, `other`. When the identification is missing for a role that needs it, the entity is still created (unless you passed that role in `intended_roles`) and `role_details` reports `CheckGovernmentID` against the role ([Troubleshooting](/products/entity/troubleshooting#role-check-failure-codes)). Add the identification later with a `PATCH`. If you have previously submitted `kyc_details` for the entity, that update must also carry `kyc_details` with a later `screened_at` ([Update an Entity](/api-reference/endpoint/entity/update-an-entity)). > [!WARNING] > > **Submit only the entity's own tax identification.** Lead stores whatever SSN or ITIN you send as that individual's own, so never send a parent's, guardian's, or other person's. For a teen `authorized_user` whose SSN you do not collect, omit `tax_identification`. Send the complete object or omit it; `type` without a valid `value` is rejected. > [!NOTE] > > A `us_entity` with no tax identification on file returns `"tax_identification": { "type": "", "value": "" }`. Do not echo that object back on a `PATCH`; omit `tax_identification` instead. ### Example: Authorized User Without a Tax Identification An individual who will only be an `authorized_user` (a teen on a family account, an employee cardholder) needs first name, last name, a contact method, and `identification_details.type`: ```json theme={null} { "client_customer_id": "cust-000483", "type": "individual", "intended_roles": ["authorized_user"], "individual_details": { "first_name": "Jordan", "last_name": "Reyes", "contact_methods": [ { "type": "email", "email": "jordan@example.com" } ], "identification_details": { "type": "us_entity" } } } ``` The response shows `authorized_user` as `active`. The `account_holder` and `authorized_signer` entries are `inactive`, listing the checks the entity has not met, such as `CheckDateOfBirth`, `CheckGovernmentID`, `CheckKYCStatus`, and `CheckPhysicalAddress`. To add the individual's own tax identification later, `PATCH` the entity. `type` and the `Idempotency-Key` header are required on every update. If you have previously submitted `kyc_details` for the entity, include `kyc_details` with a later `screened_at`. ```json theme={null} { "type": "individual", "individual_details": { "identification_details": { "type": "us_entity", "tax_identification": { "type": "ssn", "value": "234567890" } } } } ``` ## Address Rules `line_1` is the full base address — street number and street name together (or the local equivalent). Address rules protect the structure of the address, not its character set. However you collect address components from your users, **combine them into `line_1` before sending**: do not split the primary street address across lines, do not put only the number in line 1, and never pad line 1 to satisfy validation. `line_2` is only for sub-premise information (apartment, unit, suite, floor, building, care-of) — blank otherwise. `city` and `country` (ISO 3166-1 alpha-2) are required; US addresses also require a valid USPS `state` code and a 5-digit `postal_code`, or ZIP+4 written as `12345-6789` or `12345 6789`. Physical addresses must not be P.O. boxes, registered-agent addresses, or in prohibited countries. ## Example Entity Object ```json theme={null} { "id": "entity_7RwQ2mK9pL4xT1vN8jS5bA3cG6d", "client_customer_id": "cust-000482", "created_at": "2026-06-11T14:22:05Z", "updated_at": "2026-06-11T14:22:05Z", "type": "individual", "intended_roles": ["account_holder"], "risk_score": "low", "individual_details": { "first_name": "Amanda", "last_name": "Reyes", "date_of_birth": "1992-02-15", "contact_methods": [ { "type": "email", "email": "amanda@example.com" } ], "address_details": { "physical_address": { "line_1": "123 Main St.", "line_2": "Apt 25", "city": "Denver", "state": "CO", "postal_code": "80014", "country": "US" } }, "identification_details": { "type": "us_entity", "tax_identification": { "type": "ssn", "value": "234567890" } } }, "kyc_details": { "result": "passed", "screened_at": "2026-06-11T14:20:00Z" }, "ofac_details": { "result": "passed", "screened_at": "2026-06-11T14:20:00Z" }, "role_details": [ { "name": "account_holder", "status": "active", "criteria_details": [ { "entity_id": "entity_7RwQ2mK9pL4xT1vN8jS5bA3cG6d", "failed_checks": [] } ] }, { "name": "authorized_signer", "status": "active", "criteria_details": [ { "entity_id": "entity_7RwQ2mK9pL4xT1vN8jS5bA3cG6d", "failed_checks": [] } ] }, { "name": "authorized_user", "status": "active", "criteria_details": [ { "entity_id": "entity_7RwQ2mK9pL4xT1vN8jS5bA3cG6d", "failed_checks": [] } ] }, { "name": "minor_account_holder", "status": "inactive", "criteria_details": [ { "entity_id": "entity_7RwQ2mK9pL4xT1vN8jS5bA3cG6d", "failed_checks": ["CheckDateOfBirthAboveMaximum"] } ] } ], "metadata": {} } ``` Full request/response schemas: [Create an Entity](/api-reference/endpoint/entity/create-an-entity) · [Update an Entity](/api-reference/endpoint/entity/update-an-entity). # Entities: Representing Your Customers Source: https://docs.lead.bank/products/entity/overview Legal persons or organizations related to Lead products — entity types, roles, KYC attestation, and where the Entity sits in every integration. An **Entity** represents a legal person or organization with specific rights and roles related to Lead products. You create an Entity for each of your end customers. One is required to use credit, depository, and card products, or to be assigned an Account Number. The Entity is where Lead anchors KYC/KYB attestation, OFAC screening, RFI handling, and your risk score. It is the first object in every integration sequence: **Entity → (Application) → Account → everything else**. ## Entity Types * **Individual** — a natural person. Create individual entities for anyone acting as an `account_holder`, `minor_account_holder`, `authorized_signer`, or `authorized_user`. Typically the individual is the account holder. Use the signer/user roles when a person needs access to an account they do not legally hold. * **Business** — any business except a sole proprietorship. Requires linked individual entities for its beneficial owners and control person(s) — see [Beneficial Ownership Requirements](/products/entity/beneficial-ownership). * **Sole Proprietorship** — a sole proprietorship, exempt from beneficial-ownership requirements but requiring a linked `sole_proprietor` individual. These types are shapes of one object — same endpoints, discriminated by `type` — and business-family entities link to individual entities rather than embedding their data ([The Entity Object](/products/entity/entity-object)). Data requirements vary by the **role** the entity will play — the full matrix is on [Roles](/products/entity/roles). ### Worked Example: Pete's Pizza Pete's Pizza is an LLC owned by Pete (a control person) and his wife Amanda (a beneficial owner). Pete's sister Sam is an authorized signer on the business checking account, and Daisy, an employee, is an authorized debit-card user with restricted access. * **Pete** → individual entity, full KYC (control person) * **Amanda** → individual entity, full KYC (beneficial owner) * **Pete's Pizza** → business entity, full KYB + your risk assessment, linking Pete and Amanda as control person and beneficial owner * **Sam** → individual entity, full KYC, later associated with the account as `authorized_signer` * **Daisy** → individual entity, partial KYC (name and contact information), associated as `authorized_user` ## The Entity at a Glance * **Identifier:** `entity_`, returned on creation. You can also address an entity by your own `client_customer_id` — which must be unique: creating a second entity with the same one returns a **409**. * **Attestation model:** you perform KYC/KYB and OFAC screening and attest the results on the entity (`kyc_details.result` + `screened_at`, `ofac_details.result` + `screened_at`) alongside your `risk_score`. Lead validates the attestations; certain updates re-trigger KYC ([Workflow](/products/entity/workflow)). * **Lead computes role eligibility from the entity's data.** The entity's `role_details` array states which roles the entity currently qualifies for and — check by check — why not. Pass `intended_roles` on create/update to validate synchronously instead of discovering gaps downstream. How to read it: [Troubleshooting](/products/entity/troubleshooting). * **Lifecycle:** created, then updated over time. Entities stay attached to their accounts for the life of the relationship and cannot be deleted — which is why the Entity has no statuses page; the statuses that matter are per-role, inside `role_details`. ## Endpoints | Method | Path | Purpose | | :- | :- | :- | | `POST` | `/v0/entities` | Create an individual, business, or sole-prop entity. | | `GET` | `/v0/entities/{id}` | Retrieve by Entity ID. | | `GET` | `/v0/entities?client_customer_id=…` | Retrieve by your client customer ID. | | `PATCH` | `/v0/entities/{id}` | Update; some updates re-trigger KYC. | > [!NOTE] > > Full field-level reference: [The Entity Object](/products/entity/entity-object) and the [API Reference](/api-reference/endpoint/entity/create-an-entity). ## In This Section * [The Entity Object](/products/entity/entity-object) — every field across the three entity shapes, with an example payload * [Roles](/products/entity/roles) — the data requirements each role carries * [Beneficial Ownership Requirements](/products/entity/beneficial-ownership) — UBOs, control persons, and the drill-down rule * [Workflow](/products/entity/workflow) — creating and updating entities, and the point-of-entry validations * [Troubleshooting](/products/entity/troubleshooting) — the most common Entity API errors and how to read `role_details` # Entity Roles Source: https://docs.lead.bank/products/entity/roles The four entity roles, what each unlocks, the role hierarchy, and the data-requirements matrix per entity type — plus how intended_roles and role_details fit together. Roles govern which financial products an entity can use. Lead computes each entity's role eligibility from its data: the `role_details` array on every entity response states, per role, whether the entity qualifies (`active`) or not (`inactive`) and — check by check — why not. To validate eligibility synchronously at create/update time instead, pass `intended_roles` ([how the two fit together](#validating-eligibility)). ## The Four Roles | **Role** | **Who** | **What it means** | | :- | :- | :- | | `account_holder` | Any entity type | Full control and legal responsibility for the account. | | `minor_account_holder` | Individuals aged 16–17 only | Full control of the account; same requirements as Account Holder except the age window. | | `authorized_signer` | Individuals only | Authorized to sign on behalf of the account holder, without legal responsibility. Common for business accounts. | | `authorized_user` | Individuals only | Restricted account access, without legal responsibility. | **The hierarchy:** Account Holders qualify for all Authorized Signer and Authorized User use cases. Authorized Signers qualify for all Authorized User use cases. Minor Account Holders qualify for all Authorized User use cases but are **not** eligible for the Authorized Signer role. ## What Each Role Unlocks **Account Holder** * Provisioning and using [Account Numbers](/products/account-number/overview). * Designating the entity as an `account_holder` on an [Account](/products/accounts/overview) (API) or in the [Account file](/file-reference/account/schema). * Provisioning [Cards](/products/cards/overview) to the entity — if it is also an Account Holder on the account the card is issued under. **Minor Account Holder** * Provisioning and using Account Numbers for individuals aged 16–17. * When the entity turns 18, Lead recomputes eligibility from the date of birth. The entity stops qualifying for `minor_account_holder` and qualifies for `account_holder` with no entity update required. To complete the transition, designate the entity as an `account_holder` on the account; existing account numbers carry over. * For an existing Account Number, update its controls first. Lead validates that request against the entity's recalculated roles. * An account whose only holders are Minor Account Holders cannot use the `credit_with_underwriting` capability ([Accounts API validation rules](/products/accounts/validations)). * **API only** — not supported in file integrations. > [!NOTE] > > **Program availability.** The `minor_account_holder` role is available only to programs approved for minor account holder support — subject to Lead review of the program's intended audience, monitoring, and product controls for minors. Contact your Technical Account Manager to request enablement. > [!WARNING] > > Minor Account Holders can receive funds on all rails and originate ACH and instant payments, but **cannot send wires or blockchain transfers**. Programs are responsible for enforcing these restrictions in their product experience as a condition of enablement. **Authorized Signer** * Required for listing an entity as a beneficial owner or control person of a business entity ([Beneficial Ownership Requirements](/products/entity/beneficial-ownership)). * Designating the entity as an `authorized_signer` on an Account (API or file). **Authorized User** * Designating the entity as an `authorized_user` on an Account (API or file). * Provisioning Cards to the entity — if it is also an Authorized User on the account the card is issued under. ## Data Requirements | | **Individual** | **Business** | **Sole Proprietorship** | | :- | :- | :- | :- | | **Authorized User** | First name · Last name · Contact method (email or phone) · `identification_details.type`5 | N/A | N/A | | **Authorized Signer** | First name · Last name · Contact method · Physical address1 · Date of birth (18+) · Government-verified identification2 · OFAC passed & valid · KYC passed & valid | N/A | N/A | | **Account Holder** | Authorized-signer set, plus risk score | Business name · Business type · Business industry · Contact method · Government-verified identification2 · Physical address1 · KYC passed & valid · OFAC passed & valid · Risk score · One or more control persons3 with titles · One or more applicable beneficial owners3 | Business name · Business type · Business industry · Contact method · Government-verified identification2 · Physical address1 · KYC passed & valid · OFAC passed & valid · Risk score · One or more sole proprietors4 | | **Minor Account Holder** | Account-holder set, with date of birth 16 or 17 | N/A | N/A | > [!NOTE] > > Minor Account Holder requirements are identical to Account Holder except the date-of-birth window. Individuals 18+ use `account_holder`; individuals under 16 are not eligible for any account holder role. 1. Address must not be a registered-agent address, P.O. box, or in a prohibited country.\ 2. For US entities (those with a US tax identification number), a US tax ID is required; non-US entities require other government-verified identification. Only the roles marked with this footnote require it. Field rules: [The Entity Object](/products/entity/entity-object#identification-for-us-and-non-us-entities).\ 3. Beneficial owner / control person data requirements match the `authorized_signer` set. Capture and submit accurate beneficial ownership data; where there are genuinely no qualifying owners, an empty array is a valid submission.\ 4. Sole proprietor data requirements match the `authorized_signer` set.\ 5. Only `type` (`us_entity` or `non_us_entity`) is required; no tax identification or identification documents. > [!WARNING] > > Send only the individual's own tax identification, or omit it. Never submit a parent's SSN for a teen `authorized_user` — see [Identification](/products/entity/entity-object#identification-for-us-and-non-us-entities). ## Validating Eligibility Two complementary mechanisms, same vocabulary: * **`intended_roles` (synchronous):** pass it on `POST`/`PATCH` when you believe the data satisfies a role's requirements. Validation is **all-or-nothing across the listed roles**; a failure returns a 422 naming the failing check. For `business`/`sole_prop`, pass only `account_holder`. * **`role_details` (always on):** every entity response carries the per-role eligibility computed from current data — the source of truth for downstream use. If you omit `intended_roles` and the data happens to meet a role's requirements, the entity is still eligible downstream. Reading failures — including indirect failures through child entities — is covered step-by-step on [Troubleshooting](/products/entity/troubleshooting). # Entity Troubleshooting Source: https://docs.lead.bank/products/entity/troubleshooting The most common errors when calling the Entity API. ## Common Errors Four request patterns account for most errors when calling the Entity API. > [accordion] Open API Spec Validation > > Lead's [Entity API documentation](/api-reference/endpoint/entity/create-an-entity) covers our API interface specification and Lead's [raw Open API](https://docs.lead.bank/openapi.json). Any request that violates this specification returns a `422`, for example a `POST` entity request that omits a required field. > > A common case: `individual_details.identification_details` is required, but only its `type` is. For an `authorized_user` with no SSN collected, send `identification_details: { "type": "us_entity" }` rather than omitting the object ([Identification](/products/entity/entity-object#identification-for-us-and-non-us-entities)). > [accordion] Failure of Synchronous Business Validation > > Lead runs a [synchronous set of business validations](/products/entity/workflow#create-and-update-validations) over Entity `POST` / `PATCH` requests. If the request violates any of those checks, the API will return a 422. > [accordion] Intended Role Failure > > You can pass `intended_roles` in a `POST` / `PATCH` request. Lead then evaluates synchronously whether the data you provided satisfies the data requirements for each listed role. > > If any listed role fails evaluation, the request returns a 422 that names the role check that failed. Omitting `intended_roles` removes the error from the create or update response, but the same gap surfaces later when you use the `entity_id` downstream. > > The checks behind these synchronous errors are identical to the checks reported in `role_details` on the `GET` entity response. > [accordion] 409 on Create: Duplicate client\_customer\_id > > Each `client_customer_id` must be unique within your program. A `POST` entity request whose `client_customer_id` is already in use returns a `409` rather than creating a duplicate entity. Retrieve the existing entity with `GET /v0/entities?client_customer_id=…` and `PATCH` it instead of re-creating it. ## **Troubleshooting Role Eligibility** Role eligibility checks return a `422` only when you pass `intended_roles` in the `POST` or `PATCH` request. Without it, the same checks still run, and the response tells you which data requirements the entity has not yet met for each [role](/products/entity/roles). To find out why an entity is not eligible for a role, inspect the `role_details` array on the entity. It names exactly which checks fail and on which entity. The following steps show how to read a role eligibility failure and resolve it. **1. Find the Role and Check its Status** In the `role_details` array, find the object where the `name` matches the role you're checking (e.g., `account_holder`, `minor_account_holder`, `authorized_signer`, or `authorized_user`). Once you've found the correct role object, check its `status` field: * `active`: The entity has passed all checks and is eligible for this role. * `inactive`: The entity is not eligible. Proceed to the next step to diagnose the failure. **2. Diagnose the Failure** If the status is `inactive`, look inside that role's `criteria_details` array. This array explains what went wrong. Each object in `criteria_details` contains: * `entity_id`: The ID of the entity that has the problem and **must be updated**. * `failed_checks`: A list of one or more error codes. > [!NOTE] > > Refer to the Role Check Failure table below to understand what each code in the `failed_checks` list means and how to resolve it. ## **Understand Indirect Failures (Child Entities)** Sometimes, an entity's role is `inactive` because a **related child entity** (like a control person or beneficial owner) has failed its own required checks. The `criteria_details` array is designed to point you directly to that failing child entity. **Example** Let's say a `business` is `inactive` for the `account_holder` role. 1. **The Requirement:** For a `business` to be an `account_holder`, it must list at least one control person in `control_persons`. That control person's entity must, in turn, be eligible for the `authorized_signer` role. 2. **The Dependency:** To be an `authorized_signer`, the control person's entity must have a `passed` KYC status. 3. **The Failure:** In this case, the control person's entity failed its KYC check. 4. **The Result:** Because the control person is not a valid `authorized_signer`, the parent `business` cannot become an `account_holder`. The `criteria_details` for the `business` contains an object pointing to the control person's `entity_id` with a `failed_checks` list containing `CheckKYCStatus`. This tells you to update the control person's entity to resolve the issue for the `business` entity. > [!TIP] > > `business` and `sole_prop` entities will always have an `inactive` status for the `authorized_signer` and `authorized_user` roles. > > This is expected behavior and does not indicate an error. ## Role Check Failure Codes | **Code** | **Description** | **Entity Type** | **Possible Roles** | **How to Resolve** | | - | - | - | - | - | | `CheckFirstName` | Requires first name that is at least 1 alphanumeric character | individual | Account Holder, Minor Account Holder, Authorized Signer, Authorized User | Update entity to include `individual_details.first_name`. | | `CheckLastName` | Requires last name that is at least 2 alphanumeric characters | individual | Account Holder, Minor Account Holder, Authorized Signer, Authorized User | Update entity to include `individual_details.last_name`. | | `CheckPhoneOrEmail` | Requires valid phone number or email address | individual, business, sole\_prop | Account Holder, Minor Account Holder, Authorized Signer, Authorized User | For entities of type `individual`, update `individual_details.contact_methods` to include at least one email or phone number. For `business` or `sole_prop`, update `business_details.contact_methods`. | | `CheckPhysicalAddress` | Requires physical address | individual, business, sole\_prop | Account Holder, Minor Account Holder, Authorized Signer | For `individual`, update `individual_details.address_details.physical_address`. For `business` or `sole_prop`, update `business_details.address_details.physical_address`. A physical address must include `line_1`, `city`, and `country`. If `country` is `US`, `state` and a valid `postal_code`: 5 digits, or ZIP+4 written as `12345-6789` or `12345 6789` are also required. | | `CheckDateOfBirth` | Must be 18 years or older | individual | Account Holder, Authorized Signer | Update `individual_details.date_of_birth` with the correctly formatted (YYYY-MM-DD) date, indicating the entity is over 18. | | `CheckDateOfBirthBelowMinimum` | `minor_account_holder` requires age 16–17; this entity is under 16 | individual | Minor Account Holder | The entity is not eligible for any account holder role until age 16. | | `CheckDateOfBirthAboveMaximum` | `minor_account_holder` requires age 16–17; this entity is 18 or older | individual | Minor Account Holder | The entity meets the age requirement for `account_holder`. Check that role in `role_details` — it is active if all other criteria pass — and use `account_holder` instead. | | `CheckDateOfBirthMissing` | `minor_account_holder` requires a date of birth in `YYYY-MM-DD` format | individual | Minor Account Holder | Update `individual_details.date_of_birth` with a correctly formatted (YYYY-MM-DD) date. | | `CheckGovernmentID` | For US entity, requires US tax ID. For non-US, requires other government ID. Not required for Authorized User. | individual, business, sole\_prop | Account Holder, Minor Account Holder, Authorized Signer | For a US `individual`, populate `individual_details.identification_details` with a valid SSN or ITIN. For a US `business` or `sole_prop`, populate `business_details.identification_details` with a valid EIN, SSN, or ITIN. For a non-US entity, provide documents under `identification_documents`. | | `CheckOFAC` | OFAC must have passed and `ofac_details.screened_at` must be present | individual, business, sole\_prop | Account Holder, Minor Account Holder, Authorized Signer | `ofac_details.result` must be `passed` and `ofac_details.screened_at` must be a valid past timestamp. | | `CheckKYCStatus` | KYC must have passed and `kyc_details.screened_at` must be present | individual, business, sole\_prop | Account Holder, Minor Account Holder, Authorized Signer | `kyc_details.result` must be `passed` and `kyc_details.screened_at` must be a valid past timestamp. | | `CheckRiskScore` | Requires risk score | individual, business, sole\_prop | Account Holder, Minor Account Holder | `risk_score` must be populated with a value of `low`, `medium`, or `high`. | | `CheckBusinessName` | Requires business name that is at least 2 alphanumeric characters | business, sole\_prop | Account Holder | `business_details.name` must be populated with a value of at least 2 alphanumeric characters. | | `CheckBusinessType` | Requires business type | business, sole\_prop | Account Holder | `business_details.type` must be populated. | | `CheckBusinessIndustry` | Requires NAICS code(s) for business industry | business, sole\_prop | Account Holder | `business_details.industry` must be populated with a valid 2-6 digit 2022 NAICS code. A reference file is available at the [Census Bureau](https://www.census.gov/naics/). | | `CheckChildEntityNotFound` | Business/sole prop must have a corresponding individual entity for owners/control persons. | business, sole\_prop | Account Holder | The `entity_id` in `beneficial_owners`, `control_persons`, or `sole_proprietor` must reference a valid `individual` entity who meets `authorized_signer` data requirements. | | `CheckManualReviewStatus` | Manual review is pending for at least one validation check | individual, business, sole\_prop | Account Holder, Minor Account Holder, Authorized Signer, Authorized User | Contact your Lead Technical Account Manager. | | `CheckControlPersonExists` | Requires at least one control person for business entities | business | Account Holder | For `business` entities, the `control_persons` list must include at least one valid item referencing an `individual` entity who meets `authorized_signer` data requirements. A `title` is also required. | > [!NOTE] > > `minor_account_holder` runs the full Account Holder check set, including `CheckGovernmentID`, so a minor account holder must have an SSN or ITIN. `CheckDateOfBirth` is replaced by the three `CheckDateOfBirth*` codes above. Only `authorized_user` is exempt from the government-ID, address, KYC, and risk-score checks. ## Intended Role Parameter > [!NOTE] > > **Notes for using the intended roles parameter in POST and PATCH requests or Customer File Uploads** `intended_roles` is an optional parameter on entity `POST` and `PATCH` requests and on Customer file records. Pass it when you believe you have captured every data point a [role](/products/entity/roles) requires. It asks Lead to validate **synchronously** that the entity meets the [data requirements](/products/entity/roles#data-requirements) for each listed role. This catches gaps before they cause downstream failures. Suppose the entity data you are about to send does not yet meet the Account Holder requirements: > [!CAUTION] > > If the request includes `intended_roles: ["account_holder"]`, Lead rejects it with a 422 that names the failing check. Nothing is created or updated. Fix the named field and resubmit. A Customer file record that includes `intended_roles` fails validation the same way. If you omit `intended_roles`, Lead creates the entity as long as it meets the schema requirements, even though it does not yet qualify as an `account_holder`. The `role_details` array in the response shows which roles it qualifies for, and you can update the entity later to close the gap. When a synchronous `intended_roles` validation fails, the 422 body carries `invalid_parameters` naming the role and the failing checks, using the same vocabulary as `role_details`. For example, an entity under 16 submitted with an intended role of `minor_account_holder` returns: ```json theme={null} { "invalid_parameters": [ { "parameter": "intended_roles", "reason": "role: minor_account_holder, CheckDateOfBirthBelowMinimum" } ] } ``` > [!NOTE] > > `intended_roles` is optional. If the entity meets a role's data requirements and you do not pass `intended_roles`, Lead still treats the entity as eligible for that role in downstream use cases such as [Account Number creation](/products/account-number/overview). > [!TIP] > > Instead of passing `intended_roles`, you can read `role_details` in the entity response as the source of truth for role eligibility. ## File-Integrated Programs: Error Handling and Retry If your program reports customers via the [Customer files](/file-reference/customer/overview) rather than the API, validation failures surface through the file cycle instead: 1. Lead posts a [success message in Slack](/file-reference/delivery/slack-alerts) when the batch processes, listing the files it included. 2. If a file fails validation, the error messages appear in your Slack alert channel. 3. Fix the file and upload a new version. Lead re-runs validation on the latest version of each file in the batch. # Entity Workflow Source: https://docs.lead.bank/products/entity/workflow How to create and update entities — the children-first sequencing for business entities, the point-of-entry validations Lead runs, and what happens on update. ## Create: Children First Individuals stand alone; business-family entities reference individuals. So the creation order for anything but a lone individual is: **1. Create the individual entities** Every beneficial owner, control person, or sole proprietor is an `individual` entity created first, meeting [authorized-signer data requirements](/products/entity/roles#data-requirements). Capture each `entity_id`. **2. Create the business or sole-prop entity** Reference the individuals in `beneficial_owners` / `control_persons` (business) or `sole_proprietor` (sole prop). Who must be listed and the drill-down rule for indirect ownership: [Beneficial Ownership Requirements](/products/entity/beneficial-ownership). **3. Validate eligibility as you go** Pass `intended_roles` to validate role readiness synchronously, or read `role_details` on the response ([Roles](/products/entity/roles#validating-eligibility)). A parent's eligibility depends on its children passing their checks — failures point at the failing child's `entity_id` ([Troubleshooting](/products/entity/troubleshooting)). ![Entity Creation Workflow](https://mintcdn.com/lead/0UJlPqWdLCOMqs06/images/entity-creation-workflow.png?fit=max\&auto=format\&n=0UJlPqWdLCOMqs06\&q=85\&s=1002467eb073153e6c12f029b4cbe359) Requests are idempotent via the required `Idempotency-Key` header, and `client_customer_id` must be unique — a create with an existing value returns **409** rather than a duplicate entity. ## Create and Update Validations An entity records who your customer is, and many downstream consumers with different format constraints read from it. Send customer data as your customer presented it, including non-Latin characters in names and addresses. The validations below reject structurally bad data. In addition to standard required-vs-optional and data-type validations, Lead runs the following at the point of entry. > [!NOTE] > > This list is not exhaustive. Lead adds validations as needed to keep entity data accurate for oversight. * Phone numbers follow E.123 format — a `+` sign, country code, and required spacing. The validation regex: ```text theme={null} "^\\+\\d{1,3}\\s\\d{2,3}\\s\\d{2,3}\\s\\d{4}|^\\+\\d{1,3}\\s\\d{1,14}(\\s\\d{1,13})?|^\\(\\d{3}\\)\\s\\d{3}\\s\\d{4}?" ``` * Addresses and customer information must consist solely of valid UTF-8 characters. * The business name must be longer than one character. * P.O. Box addresses may not be used as physical addresses — neither in line 1 nor line 2. * Registered-agent addresses and addresses in prohibited countries may not be used as physical addresses. * Address line 1 may not have leading whitespace and must be at least 4 characters. (Line-1 vs. line-2 semantics: [The Entity Object](/products/entity/entity-object#address-rules).) * For US addresses, `state` must be a valid USPS state code. * SSNs may not start with the number 9 — ITINs mistakenly reported as SSNs are the most common trigger of this failure. * Postal codes for US addresses must be 5 digits, or ZIP+4 written as `12345-6789` or `12345 6789`. * OFAC and KYC dates must be dated prior to the time of the request. Violations return a 422 with the offending field named in `invalid_parameters` ([Troubleshooting](/products/entity/troubleshooting)). ## Update `PATCH /v0/entities/{id}` updates an existing entity. **Certain updates require a fresh KYC attestation**: if you have previously submitted `kyc_details` for the entity, the update must carry an updated `kyc_details.result` and a later `kyc_details.screened_at` ([Update an Entity](/api-reference/endpoint/entity/update-an-entity)). Updates are also how you cure role-eligibility failures: fix the field named in `failed_checks`, and Lead recomputes `role_details` — including for any parent entities whose eligibility depends on this one. Entities cannot be deleted; an entity stays attached to its accounts for the life of the relationship. # Lending at Lead: Credit Lead Originates, Products Your Customers Hold Source: https://docs.lead.bank/products/funding-and-receivables/overview How lending works on Lead: origination through Entity, Application, Account, and Balance; funding through the Funding API; daily servicing reporting; and the receivable cycle that moves loans from Lead's balance sheet to yours. Lead is the **lender of record** for every credit product on the platform: when your customer borrows, Lead originates the loan. That one fact shapes the whole integration — it's why underwriting decisions are reported to Lead ([Applications](/products/applications/overview)), why the loan's terms live on an object in Lead's system ([the Balance](/products/lending/balance-object)), why drawing principal is an execution call that moves real money ([the Funding](/products/lending/funding-object)), and why the loans Lead originates become yours through a daily **receivable sale** — unless your program keeps them on Lead's balance sheet ([balance-sheet models](/products/lending/balance-sheet-models)). ## The Four Moving Parts **1. Origination.** The compliance chain is Entity → Application → Account → Balance. The [Account](/products/accounts/overview) carries a `credit_with_underwriting` capability (requiring an approved [Application](/products/applications/overview)) or `credit_without_underwriting` for non-underwritten products such as courtesy overdraft. The **Balance** carries the loan's terms; creating it moves no money — at creation it represents an unfunded loan. See [The Balance Object](/products/lending/balance-object). **2. Funding.** The one **execution** API in the lending family ([Executing vs. Reporting](/core-concepts/platform/executing-vs-reporting)): a [Funding](/products/lending/funding-object) draws principal from a Lead GL into your **funding FBO**, and you disburse onward over any [payment rail](/core-concepts/platform/money-movement) — instant payments for real-time disbursement, ACH for batch, wires for large-dollar. **3. Servicing.** You are the servicer and ledger of record. Repayments, interest, and fees are reported to Lead through the daily [Balance and Transaction reporting](/products/balances-and-transactions/overview). For revolving products this reporting is operationally load-bearing: available credit — which gates the next draw — is computed from what you report. **4. Receivable Cycle.** Because Lead is the lender of record, every origination creates a **receivable**: Lead's claim on the loan. Under the Originate-to-Sell model, receivables past your program's hold period are grouped into a single daily **sale** you purchase; under On-Sheet Lending, Lead holds them to terminal status. See [Receivables & the Daily Sale](/products/lending/receivables-and-the-daily-sale) and [Balance-Sheet Models](/products/lending/balance-sheet-models). ## What You Can Build Closed-end term loans (including BNPL), open-end lines of credit, card-based revolving and charge credit ([card programs](/guides/issue/credit-and-charge-card-program)), and overdraft products. The object model is identical across all of them; the differences live in the Balance's `structure` ([non-revolving vs. revolving](/products/lending/balance-object#two-structures)) and your program configuration. ## Integration Surface Today Origination and funding are fully API-based. Servicing runs on the daily Balance and Transaction files, and the receivables sale runs on the Sales Request/Response file exchange — each with an API successor in flight. Current state per workflow: [Integration Surfaces by Product](/core-concepts/platform/integration-surfaces-by-product); the forward story: [Platform Evolution](/core-concepts/platform/platform-evolution). > [!NOTE] > > **Legacy: the Disbursement API.** Programs onboarded before the Funding API disburse through the rail-limited [Disbursement API](/api-reference/endpoint/lending/create-a-disbursement). It is not part of new integrations. If your program uses it, its reference documentation remains available and your Lead team can discuss migration. ## In This Section [The Balance Object](/products/lending/balance-object) — the loan or line itself: creation, the two structures, terms, and Lead's view of the live position · [The Funding Object](/products/lending/funding-object) — your instruction to Lead to originate principal: the principal decomposition, lifecycle, and sandbox testing · [Receivables & the Daily Sale](/products/lending/receivables-and-the-daily-sale) — how loans move from Lead's balance sheet to yours · [Balance-Sheet Models](/products/lending/balance-sheet-models) — Originate-to-Sell vs. On-Sheet Lending · [Sales Settlement Amount](/products/funding-and-receivables/sales-settlement-amount) — how each day's purchase is priced. *End-to-end walkthroughs:* [Instant Loan Origination and Disbursement](/guides/lend/instant-loan-origination-and-disbursement) · [Run a Credit or Charge Card Program](/guides/issue/credit-and-charge-card-program) · [Originate Your First Loan](/get-started/quickstart/originate-your-first-loan) (quickstart with full payloads). # Sales Settlement Amount Source: https://docs.lead.bank/products/funding-and-receivables/sales-settlement-amount > [!WARNING] > > This settlement amount calculation is being deprecated by end of year. If your new program is onboarding after August 1, 2026, the settlement amount will always equal the original loan principal plus the imputed interest charged on that original loan principal. For existing programs, please look out for a breaking change notification in August 2026, which will provide adequate notice. ## Overview The settlement amount is the total amount a partner must send to Lead on the loan sale date. Lead expects this amount to be transferred to the Operating Account before the partner sends a Sales Response. > [!NOTE] > > settlement\_amount = outstanding\_principal + settled\_transactions\_amount + imputed\_interest\_accrued ## Rounding Lead calculates `imputed_interest_accrued` and `settlement_amount` for each loan to **6 decimal places** and reports them that way in the Sales Request. Lead does not round each loan to the cent. The amount Lead collects for a sale is the **sum of every loan's `settlement_amount` in that sale, rounded once to the cent**. > [!TIP] > > To reconcile to Lead's amount, add up the per-loan `settlement_amount` values at full precision and round the total once. Rounding each loan to the cent first and then adding them up can produce a different total. > > If your ledger needs a whole-cent amount for each loan, round each loan down to the cent, then add one cent at a time to the loans with the largest remaining fractions until the per-loan amounts add up to Lead's amount. ### Example A sale contains three loans, each with a `settlement_amount` of \$100.004. | **Method** | **Calculation** | **Total** | | - | - | - | | Lead (round once per sale) | \$100.004 + \$100.004 + \$100.004 = \$300.012, rounded to \$300.01 | \$300.01 | | Round each loan first | \$100.00 + \$100.00 + \$100.00 | \$300.00 | > [!NOTE] > > There are other invoicing items besides imputed interest to which you are subject, per your Program Management Agreement. \ > \ > Reach out to your technical account manager for more details.\ > \ > Note: receivables sold and purchased do not include any fees or interest charged to your end customer. Since those funds are not originated by Lead, they will not need to be sold. ## Components of Settlement Amount > [accordion] Outstanding Principal > > The total amount of disbursed transactions (type = `disbursement`) for each `balance_id` based on the receivables origination date. Receivables are created at Lead at the balance level when Lead receives a `Transactions` file with `type` = `disbursement`. Lead sells these back to the partner after the hold period. > > ### Example > > If the hold period is 3 business days, and the sale date is Thursday, then the outstanding principal will reflect receivables from disbursements with a settlement date of the prior Monday. > [accordion] Settled Transactions Amount > > Lead uses gross settlement, meaning all payments that reduce outstanding principal during the hold period will still be collected from the partner. > > > [!TIP] > > > > **Card refunds are the only exception and use net settlement:** > > > > * During hold: Lead receives refunds directly from the network and nets them out of the settlement. > > * After hold: Refund amounts are returned to your operating account. > [accordion] Imputed Interest Accrued > > Daily interest accrued on outstanding principal of receivables created during the hold period. > > * **If interest-based:** Lead charges the same effective APR as the partner charges its customer. > * **If fee-based:** For fee-based products (with no end customer interest), the Program Management Agreement outlines the applicable imputed interest rate. > > When applicable, the SOFR (Secured Overnight Financing Rate) rate is set based on the rate published on the last business day of the month prior to the loan’s origination date. This rate remains fixed for the entire hold period, even if the hold period spans multiple months. > > ### Example > > A loan originates on March 31 with a three day hold period. The applicable SOFR (Secured Overnight Financing Rate) rate is taken from 2/28 (the last business day of the prior month), which was 4.39%. That 4.39% rate applies for all three days of the hold period. > > > [!TIP] > > > > Payments are applied on a first-in, first-out (FIFO) basis to non-Lead receivables before being applied to Lead receivables.\ > > \ > > Payment reversals are applied in a last-in, first-out (LIFO) order to Lead-held receivables up to the originated amount. \ > > \ > > Refunds and disputes affect specific transactions if the `original_transaction_id` is included. ## Origination & Sale Date Assuming a three business day hold period (refer to your contract for your program's hold period), here is how origination and sale dates align: | **Origination Date** settlement\_date of type = disbursement | **Sale Date** | | - | - | | Monday | Thursday | | Tuesday | Friday | | Wednesday | Monday | | Thursday | Tuesday | | Friday | Wednesday | | Saturday | Thursday | | Sunday | Thursday | > [!WARNING] > > Weekend settlements do not occur because payment rails only operate on business days. > > \ > Note: Federal holidays are not business days. For example, on MLK day of January 20th (Monday), any receivables created on Friday (January 17th) will sell on Thursday (January 23rd). ## Examples | **Field** | **Receivables Created** | **Outstanding Principal** | **Settled Transactions** | **Imputed Interest Accrued** | **Settlement Amount** | | - | - | - | - | - | - | | Weekday Loan Hold | \$20.00 | \$20.00 | \$0.00 | \$0.023655 | \$20.023655 | | Weekend Loan Hold | \$20.00 | \$20.00 | \$0.00 | \$0.039425 | \$20.039425 | | Payment During Hold Period (no prior outstanding principal) | \$20.00 | \$5.00 | \$15.00 | \$0.017741 | \$20.017741 | | Payment During Hold Period (prior outstanding principal) | \$20.00 | \$15.00 | \$5.00 | \$0.021684 | \$20.021684 | | Refund During Hold Period | \$20.00 | \$0.00 | \$0.00 | \$0.007885 | \$0.007885 | | Full Cancellation During Hold Period | \$100.00 | \$0.00 | \$100.00 | \$0.00 | \$100.00 | | Partial Cancellation During Hold Period | \$100.00 | \$70.00 | \$30.00 | \$0.073972 | \$100.073972 | Each example is a single loan, shown at the 6 decimal places reported in the Sales Request. Lead rounds the sale total, not each loan (see [Rounding](#rounding)). > [!TIP] > > Refunds are credited to the Network Settlement Account, so you are not responsible for repaying them if they occur during the hold period. If refunds occur outside of the hold period, Lead provides funds back to your Operating Account. ### Details > [accordion] Weekday Loan Hold > > Example assumes origination date of Monday (March 31st, 2025), three business-day hold period, imputed interest rate of SOFR (Secured Overnight Financing Rate) +10%. > > * (T = Loan Origination Date) A \$20 card transaction occurs on John's Balance. > * `type` = `disbursement` > * `transfer_type` = `card` > * `settlement_date` = `2025-03-31` > * (Hold Period) Lead holds receivables for 3 business days. Example assumes 3-business-day hold. > * (T+Business Day 3 = Thursday) Lead sends Sales Request with following settlement summary: > > | **Field** | **Value** | > | - | - | > | outstanding\_principal | \$20.00 | > | settled\_transactions\_amount | \$0.00 | > | imputed\_interest\_accrued | \$0.023655 | > | settlement\_amount | \$20.023655 | > > * Imputed interest calculation is as follows: > > | **Daily Imputed Interest** | **Calculation** | > | - | - | > | Imputed interest on 3/31 (Monday) | \$20 of receivables created on 3/31 x (4.39% as of 2/28 + 10%) / 365 days = \$0.007885 | > | Imputed interest on 4/1 (Tuesday) | \$20 of receivables created on 3/31 x (4.39% as of 2/28 + 10%) / 365 days = \$0.007885 | > | Imputed interest on 4/2 (Wednesday) | \$20 of receivables created on 3/31 x (4.39% as of 2/28 + 10%) / 365 days = \$0.007885 | > | Total | \$0.023655, reported at 6 decimal places (see [Rounding](#rounding)) | > [accordion] Weekend Loan Hold > > Example assumes origination date of Thursday (March 27th, 2025), three business-day hold period, imputed interest rate of SOFR (Secured Overnight Financing Rate)+10%. > > * (T = Loan Origination Date) A \$20 card transaction occurs on John's Balance. > * `type` = `disbursement` > * `transfer_type` = `card` > * `settlement_date` = `2025-03-27` > * (Hold Period) Lead holds receivables for 3 business days. Example assumes 3-business-day hold. > * (T+Business Day 3 = Tuesday) Lead sends Sales Request with following settlement summary: > > | **Field** | **Value** | > | - | - | > | outstanding\_principal | \$20.00 | > | settled\_transactions\_amount | \$0.00 | > | imputed\_interest\_accrued | \$0.039425 | > | settlement\_amount | \$20.039425 | > > * Imputed interest calculation is as follows: > > | **Daily Imputed Interest** | **Calculation** | > | - | - | > | Imputed interest on 3/27 (Thursday) | \$20 of receivables created on 3/27 x (4.39% as of 2/28 + 10%) / 365 days = \$0.007885 | > | Imputed interest on 3/28 (Friday) | \$20 of receivables created on 3/27 x (4.39% as of 2/28 + 10%) / 365 days = \$0.007885 | > | Imputed interest on 3/29 (Saturday) | \$20 of receivables created on 3/27 x (4.39% as of 2/28 + 10%) / 365 days = \$0.007885 | > | Imputed interest on 3/30 (Sunday) | \$20 of receivables created on 3/27 x (4.39% as of 2/28 + 10%) / 365 days = \$0.007885 | > | Imputed interest on 3/31 (Monday) | \$20 of receivables created on 3/27 x (4.39% as of 2/28 + 10%) / 365 days = \$0.007885 | > | Total | \$0.039425, reported at 6 decimal places (see [Rounding](#rounding)) | > [accordion] Payment During Hold Period (no prior outstanding principal) > > Example assumes origination date of Monday (March 31st, 2025), three business-day hold period, imputed interest rate of SOFR (Secured Overnight Financing Rate)+10%. There was a payment of \$15 towards the credit balance on Wednesday (April 2nd, 2025). > > * (Prior to T) There were no outstanding principal on John's account (`outstanding_principal` = \$0) > * (T = Loan Origination Date) A \$20 card transaction occurs on John's Balance. > * `type` = `disbursement` > * `transfer_type` = `card` > * `settlement_date` = `2025-03-31` > * (Hold Period) Lead holds receivables for 3 business days. Example assumes 3-business-day hold. > * (T+Business Day 2 = Wednesday) The partner sends \$15 card payment on John's Balance > * `type` = `payment` > * `transfer_type` = `card` > * `settlement_date` = `2025-04-02` > * (T+Business Day 3 = Thursday) Lead sends Sales Request with following settlement summary. > | **Field** | **Value** | > | - | - | > | outstanding\_principal | \$5.00 *(\$20 - \$15 card payment) The entire \$15 is applied to the newly disbursed amount using FIFO logic (first-in, first-out)* | > | settled\_transactions\_amount | \$15.00 | > | imputed\_interest\_accrued | \$0.017741 | > | settlement\_amount | \$20.017741 | > * Imputed interest calculation is as follows. > > | **Daily Imputed Interest** | **Calculation** | > | - | - | > | Imputed interest on 3/31 (Monday) | \$20 of receivables created on 3/31 x (4.39% as of 2/28 + 10%) / 365 days = \$0.007885 | > | Imputed interest on 4/1 (Tuesday) | \$20 of receivables created on 3/31 x (4.39% as of 2/28 + 10%) / 365 days = \$0.007885 | > | Imputed interest on 4/2 (Wednesday) | **\$5** remaining of \$20 receivables created x (4.39% as of 2/28 + 10%) / 365 days = \$0.001971 | > | Total | \$0.017741, reported at 6 decimal places (see [Rounding](#rounding)) | > [accordion] Payment During Hold Period (prior outstanding principal) > > Example assumes origination date of Monday (March 31st, 2025), three business-day hold period, imputed interest rate of SOFR (Secured Overnight Financing Rate)+10%. There was a payment of \$15 towards the credit balance on Wednesday (April 2nd, 2025). > > * (Prior to T) There was outstanding principal on John's account of \$10 (`outstanding_principal` = \$10). > * (T = Loan Origination Date) A \$20 card transaction occurs on John's Balance. > * `type` = `disbursement` > * `transfer_type` = `card` > * `settlement_date` = `2025-03-31` > * (Hold Period) Lead holds receivables for 3 business days. Example assumes 3-business-day hold. > * (T+Business Day 2 = Wednesday) The partner sends \$15 card payment on John's Balance > * `type` = `payment` > * `transfer_type` = `card` > * `settlement_date` = `2025-04-02` > * (T+Business Day 3 = Thursday) Lead sends Sales Request with following settlement summary: > > | **Field** | **Value** | > | - | - | > | outstanding\_principal | \$15.00 *The \$15 payment is applied as follows using the FIFO method: \$10 reduces the pre-existing balance, \$5 reduces the newly disbursed \$20, and the remaining \$15 of the new loan is still outstanding* | > | settled\_transactions\_amount | \$5.00 | > | imputed\_interest\_accrued | \$0.021684 | > | settlement\_amount | \$20.021684 | > > * Imputed interest calculation is as follows: > > | Daily Imputed Interest | Calculation | > | - | - | > | Imputed interest on 3/31 (Monday) | \$20 of receivables created on 3/31 x (4.39% as of 2/28 + 10%) / 365 days = \$0.007885 | > | Imputed interest on 4/1 (Tuesday) | \$20 of receivables created on 3/31 x (4.39% as of 2/28 + 10%) / 365 days = \$0.007885 | > | Imputed interest on 4/2 (Wednesday) | \$15 remaining of \$20 receivables created x (4.39% as of 2/28 + 10%) / 365 days = \$0.005914 | > | Total | \$0.021684, reported at 6 decimal places (see [Rounding](#rounding)) | > [accordion] Refund During Hold Period > > This example shows how a refund during the hold period affects the settlement amount. If the refund is traceable to the original transaction using `original_transaction_id`, the associated receivable is reversed, and the partner is not required to repay the amount. > > * (Prior to T) There was outstanding principal on John's account (`outstanding_principal` = \$10) > * (T = Loan Origination Date) A \$20 card transaction occurs on John's Balance > * `client_transaction_id` = `txn_1` > * `type` = `disbursement` > * `transfer_type` = `card` > * `settlement_date` = `2025-03-31` > * (Hold Period) Lead holds receivables for 3 business days. Example assumes 3-business-day hold. > * (T+Business Day 1 = Tuesday) The partner refunds the \$20 transaction. > * `client_transaction_id` = `txn_2` > * `type` = `refund` > * `transfer_type` = `card` > * `settlement_date` = `2025-04-01` > * `original_transaction_id` = `txn_1` > * (T+Business Day 3 = Thursday) Lead sends Sales Request with following settlement summary. > > | **Field** | **Value** | > | - | - | > | outstanding\_principal | \$0.00 *Given `original_transaction_id` of `txn_1` was provided, Lead is able to attribute this and bring down the receivables created to \$0. If you do not provide an `original_transaction_id`, Lead cannot attribute the refund accordingly.* | > | settled\_transactions\_amount | \$0.00 *Refund is the only transaction type that will be net settled with Lead.* | > | imputed\_interest\_accrued | \$0.007885 | > | settlement\_amount | \$0.007885 | > > * Imputed interest calculation is as follows: > > | **Daily Imputed Interest** | **Calculation** | > | - | - | > | Imputed interest on 3/31 (Monday) | \$20 of receivables created on 3/31 x (4.39% as of 2/28 + 10%) / 365 days = \$0.007885 | > | Imputed interest on 4/1 (Tuesday) | \$0 remaining of \$20 receivables created x (4.39% as of 2/28 + 10%) / 365 days = \$0.000000 | > | Imputed interest on 4/2 (Wednesday) | \$0 remaining of \$20 receivables created x (4.39% as of 2/28 + 10%) / 365 days = \$0.000000 | > | Total | \$0.007885, reported at 6 decimal places (see [Rounding](#rounding)) | > > > [!NOTE] > > > > **Notes On Refunds** > > > > * If a refund occurs during the hold period and is matched to a disbursement, the refunded amount is netted out of the settlement. > > * If a refund occurs after the hold period, Lead will return the refund to the partner’s Operating Account instead. > > * Refunds must include `original_transaction_id` to ensure proper matching and netting. If there are no `original_transaction_id` referenced for refunds that occur during the hold period, then it will not be reflected in settlement\_amount calculation. > [accordion] Full Cancellation During Hold Period > > Example assumes origination date of Monday (March 31st, 2025), three business-day hold period, interest rate of 10%. There was a full cancellation of the loan on Wednesday (April 2nd, 2025). > > > [!NOTE] > > > > For this scenario, we use a different example with a term loan, as cancellations do not apply to cards. > > * (Prior to T) There is no outstanding principal on Sarah's account (`outstanding_principal` = \$0) > * (T = Loan Origination Date) Sarah originates a \$100 loan for 10% interest rate, increasing the balance by an equivalent amount. > * `client_transaction_id` = `txn_1` > * `type` = `disbursement` > * `transfer_type` = `internal_transfer` > * `settlement_date` = `2025-03-31` > * (Hold Period) Lead holds receivables for 3 business days. Example assumes 3-business-day hold. > * (T+Business Day 2 = Wednesday) The partner sends a cancellation of the \$100 transaction. > * `client_transaction_id` = `txn_2` > * `type` = `cancellation` > * `transfer_type` = `no_money_movement` > * `settlement_date` = `2025-04-02` > * `original_transaction_id` = `txn_1` > * (T+Business Day 3 = Thursday) Lead sends Sales Request with following settlement summary. > > | **Field** | **Value** | > | - | - | > | outstanding\_principal | \$0.00 *Given `original_transaction_id` of `txn_1` was provided, Lead is able to attribute this and bring down the receivables created to \$0. If no `original_transaction_id` is created, we will not be able to attribute the cancellation accordingly.* | > | settled\_transactions\_amount | \$100.00 | > | imputed\_interest\_accrued | \$0.00 | > | settlement\_amount | \$100.00 | > > > [!NOTE] > > > > **Notes On Full Cancellations** > > > > * The imputed interest calculation is unique in the case of a full cancellation. If a Disbursement Transaction is fully cancelled via a Cancellation Transaction with `original_transaction_id` provided during the hold period of the receivable created, Lead zeros out imputed interest accrued. > > * Cancellations must include `original_transaction_id` to ensure proper matching. If there are no `original_transaction_id` referenced for refunds that occur during the hold period, then it will not be reflected in settlement\_amount calculation. > [accordion] Partial Cancellation During Hold Period > > Example assumes origination date of Monday (March 31st, 2025), three business-day hold period, interest rate of 10%. There was a partial cancellation of \$30 on the loan on Wednesday (April 2nd, 2025). > > > [!NOTE] > > > > For this scenario, we use a different example with a term loan, as cancellations do not apply to cards. > > * (Prior to T) There is no outstanding principal on Sarah's account (`outstanding_principal` = \$0) > * (T = Loan Origination Date) Sarah originates a \$100 loan for 10% interest rate, increasing the balance by an equivalent amount. > * `client_transaction_id` = `txn_1` > * `type` = `disbursement` > * `transfer_type` = `internal_transfer` > * `settlement_date` = `2025-03-31` > * (Hold Period) Lead holds receivables for 3 business days. Example assumes 3-business-day hold. > * (T+Business Day 2 = Wednesday) The partner sends a partial cancellation of \$30 of the \$100 transaction. > * `client_transaction_id` = `txn_2` > * `type` = `cancellation` > * `transfer_type` = `no_money_movement` > * `settlement_date` = `2025-04-02` > * `original_transaction_id` = `txn_1` > * (T+Business Day 3 = Thursday) Lead sends Sales Request with following settlement summary. > > | **Field** | **Value** | > | - | - | > | outstanding\_principal | \$70.00 *Given `original_transaction_id` of `txn_1` was provided, Lead is able to attribute this and decrease the receivables created to \$70. If no `original_transaction_id` is created, we will not be able to attribute the cancellation accordingly.* | > | settled\_transactions\_amount | \$30.00 | > | imputed\_interest\_accrued | \$0.073972 | > | settlement\_amount | \$100.073972 | > > * Imputed interest calculation is as follows: > > | **Daily Imputed Interest** | **Calculation** | > | - | - | > | Imputed interest on 3/31 (Monday) | \$100 of receivables created on 3/31 x 10% / 365 days = \$0.027397 | > | Imputed interest on 4/1 (Tuesday) | \$100 of receivables created on 3/31 x 10% / 365 days = \$0.027397 | > | Imputed interest on 4/2 (Wednesday) | \$70 remaining of \$100 receivable x 10% / 365 days = \$0.019178 | > | Total | \$0.073972, reported at 6 decimal places (see [Rounding](#rounding)) | > > > [!NOTE] > > > > **Notes On Partial Cancellations** > > > > * Cancellations must include `original_transaction_id` to ensure proper matching. If there are no `original_transaction_id` referenced for refunds that occur during the hold period, then it will not be reflected in settlement\_amount calculation. # Instant Payments at Lead Source: https://docs.lead.bank/products/instant-payments/overview Send and receive Instant Payments via FedNow and RTP > [!WARNING] > > RTP support is coming to the Instant Payments API in November 2026. Existing integrations will send and receive over both FedNow and RTP with no code changes. Lead will select the rail for each payment behind the scenes and expose it in a new `payment_rail` field. Lead offers Instant Payments as a single interface over two underlying rails: FedNow and RTP. FedNow and RTP (Real-Time Payments) are operated by the Federal Reserve and The Clearing House, respectively. Both are U.S. domestic, credit-push, 24/7/365 networks that support payments up to \$10 million per transaction that settle in seconds. Receivers on both networks must make funds available to the creditor immediately. Neither network supports payment reversals. Instead, return requests are used to attempt recovery of payments sent erroneously. # Payment Identifiers Source: https://docs.lead.bank/products/instant-payments/payment-identifiers Reference end_to_end_id, transaction_id, and uetr identifiers used to track FedNow and RTP instant payments and returns across the Lead network. The `instant_payment` object has an `id` of the form `instant_payment_xyz123` that references it internally within the Lead network. Additionally, Lead exposes three identifiers that identify a payment message within its payment network. None of these identifiers are configurable through the `instant_payments` API. Instead, Lead sets them automatically for outgoing payments and the counterparty sets them for incoming payments. 1. `end_to_end_id` is the mandatory "trace id" for instant payments that must pass through from debtor to creditor unchanged. Use it to reference a payment with the end customer or a counterparty. `end_to_end_id` is a max of 35 characters and is expected to be unique. 2. `transaction_id` is an optional identifier assigned by the debtor or initiating party that may also be used to reference a specific payment on the network. `transaction_id` is a max of 35 characters and is expected to be unique. 3. `uetr` is an optional identifier assigned by the debtor or initiating party that may also be used to reference a specific payment on the network. `uetr` is a UUIDv4 that is expected to be globally unique. ## Payments Payments will include two or three payment identifiers which depend on the underlying rail and the party initiating the payment. Outgoing payments from Lead will always have all three identifiers populated. FedNow and RTP require usage of `end_to_end_id` because it is the primary identifier to track a payment with a counterparty or an end customer. FedNow also mandates use of either `transaction_id` or `uetr`, but RTP mandates `transaction_id` and leaves `uetr` as optional. | Instant Payment ID | Required by FedNow? | Required by RTP? | Network Message ID | Validation | | - | - | - | - | - | | `end_to_end_id` | Yes | Yes | `EndToEndId` | Max 35 characters | | `transaction_id` | Yes if `uetr` is null | Yes | `TxId` | Max 35 characters | | `uetr` | Yes if `transaction_id` is null | No | `UETR` | UUID V4 | ## Returns Payments and returns both utilize their own `instant_payment` object. Returns are identified with a non-null `instant_payment.related_objects.original_payment_id`. FedNow returns do not have any of their own `instant_payment.payment_identifiers`. To reference a FedNow return, use the `end_to_end_id` of the original payment. RTP returns, however, support the same set of identifiers that the original payment supports. To reference an RTP return, simply look at the `end_to_end_id` of the return itself. | Instant Payment ID | Required by FedNow? | Required by RTP? | | :- | :- | :- | | `end_to_end_id` | Unsupported | Yes | | `transaction_id` | Unsupported | Yes | | `uetr` | Unsupported | No | # Receiving Instant Payments Source: https://docs.lead.bank/products/instant-payments/receiving-instant-payments Receive Instant Payments and Return Requests There are two requirements for receiving instant payments. All users of instant payments must implement the first requirement. However, we recommend implementing both because receiving return requests, particularly in cases of fraud, promote network health and safety. 1. **Receiving Payments:** Handle the receipt of incoming instant payments. 2. **Receiving Return Requests:** Handle the receipt of incoming return requests related to instant payments previously received. ## Receiving Payments Receiving an incoming instant payment creates a new `instant_payment` object with an incoming direction. ### Statuses Incoming `instant_payment` objects have three potential statuses during their lifecycle, all of which trigger a webhook. | **Instant Payment Status** | **Description** | **Webhook** | | - | - | - | | `under_review` | Lead is manually reviewing the incoming instant payment. | Yes | | `posted` | Lead posted the incoming instant payment to your account. | Yes | | `rejected` | Lead rejected the incoming instant payment. | Yes | ```mermaid theme={null} graph TD subgraph Incoming instant_payment F(["START"]) H(["rejected"]) I(["under_review"]) J(["posted"]) F --> J F -- "Lead manual review"--> I I -- "Manual review failure" --> H I -- "Manual review success" --> J F -- "Lead validation failure" --> H end subgraph State Key direction LR X([Start]) Y([Pending]) Z([Terminal]) end linkStyle 0 stroke:#155724,stroke-width:2px; classDef startStyle fill:#d4edda,stroke:#155724,stroke-width:3px; classDef progressStyle fill:#e1f5fe,stroke:#03a9f4,stroke-width:3px; classDef terminalStyle fill:#eceff1,stroke:#455a64,stroke-width:3px; class F,A,X startStyle; class I,Y progressStyle; class C,D,H,J,Z terminalStyle; ``` ### Events For incoming instant payments, the only event you must handle is `posted`. Upon this event, you are required to notify your customers that the transferred funds are now available. You have the option to also act on the `under_review` and `rejected` events if you choose. | **Event** | **Description** | **Your Action** | | :- | :- | :- | | `.under_review` | Lead is manually reviewing the incoming instant payment. | (Optional) Inform your customer that incoming funds are pending. | | `.posted` | Lead posted the incoming instant payment to your account. | (Mandatory) Inform your customer of available funds. | | `.rejected` | Lead rejected the incoming instant payment. | (Optional) Look at the rejection hash to investigate why rejection occurred. | ### Endpoints Incoming instant payments require no further action on your part. However, if the original incoming payment was defective (e.g., fraud, duplicate, or technical error), a return may be requested. ## Receiving Return Requests The counterparty financial institution will send a `return_request` if they want a payment they previously sent to be returned. The `return_request` is structured as a sub-object of the original `instant_payment`.  > [!TIP] > > A single `instant_payment` may eventually have multiple `return_request` sub-objects. However, only one incoming `return_request` will require a response at any given time. ### Statuses The lifecycle of a `return_request` sub-object begins after the original `instant_payment` reaches posted status. The only incoming `return_request` status that triggers an event is `response_needed`. | Return Request Status | Description | Webhook | | :- | :- | :- | | `response_needed` | You received an incoming return request that requires a response from you. | Yes | | `accepted` | You accepted the incoming return request by initiating an outgoing return. | No | | `rejected` | You rejected the incoming return request and provided a reason why. | No | ```mermaid theme={null} graph TD subgraph 2: Incoming return_request A(["response_needed"]) C(["accepted"]) D(["rejected"]) A -- "You return" --> C A -- "You reject" --> D end subgraph 1: Incoming instant_payment F(["START"]) H(["rejected"]) I(["under_review"]) J(["posted"]) F --> J F -- "Lead manual review"--> I I -- "Manual review failure" --> H I -- "Manual review success" --> J F -- "Lead validation failure" --> H end subgraph State Key direction LR X([Start]) Y([Pending]) Z([Terminal]) end linkStyle 2 stroke:#155724,stroke-width:2px; classDef startStyle fill:#d4edda,stroke:#155724,stroke-width:3px; classDef progressStyle fill:#e1f5fe,stroke:#03a9f4,stroke-width:3px; classDef terminalStyle fill:#eceff1,stroke:#455a64,stroke-width:3px; class F,A,X startStyle; class I,Y progressStyle; class C,D,H,J,Z terminalStyle; ``` ### Events The `return_request_response_needed` event indicates that a new return request has been received which requires your response and a potential return of funds as soon as possible. Listening to this event and taking action is required. | **Event** | **Description** | **Your Action** | | :- | :- | :- | | return\_request\_response\_needed | You received an incoming return request that requires a response from you. | (Mandatory) Begin your review process and respond as soon as possible, or, at the latest, by the 10th business day. | ### Endpoints The rejection endpoint is below. Accepting a return request is combined with the return endpoint itself which is covered in the [returns and rejections](/products/instant-payments/rejections-and-returns) section. > [!WARNING] > > For incoming return requests, you are required to investigate and respond by accepting or rejecting the request as soon as possible or, at the latest, by the 10th business day. If this deadline is not met, Lead will automatically reject the return request on your behalf to maintain our compliance with network requirements. | **Endpoint** | **Description** | | :- | :- | | `POST /instant_payments/{id}/reject_return_request` | Reject the active return request associated with an instant payment. | # Returns & Rejections Source: https://docs.lead.bank/products/instant-payments/rejections-and-returns Return Instant Payments and handle common exceptions # Returns Returning payments is important because instant payments are push-only from debtor to creditor and irrevocable. Returning an instant payment creates a new `instant_payment` object with an `outgoing` direction. Additionally, the active `return_request` sub-object of the original payment, if one exists, moves into `accepted` status automatically. This section includes the subset of statuses and events that relate to returns only. > [!NOTE] > > Returns are a type of outgoing instant payments, which are covered extensively on the [Sending](/products/instant-payments/sending-instant-payments) page. ### Endpoints You can initiate returns regardless of whether or not an active return request exists. > [!WARNING] > > For incoming return requests, you are required to investigate and respond by accepting or rejecting the request as soon as possible or, at the latest, by the 10th business day. If this deadline is not met, Lead will automatically reject the return request on your behalf to maintain our compliance with network requirements. | **Endpoint** | **Description** | | :- | :- | | `POST /instant_payments/{id}/return` | Return an instant payment that was previously received. If there is an outstanding return request, calling this endpoint will also accept the return request. | ### Statuses Outgoing returns, once initiated, will transition through four possible statuses. If an active return request is present, it will move to the `accepted` status after Lead validates the outgoing return. > [!WARNING] > > The status of a return request is not the authoritative source of payment success. Accepting a return request represents an intention to send a return but is not a guarantee of it. | **Instant Payment Status** | **Description** | **Webhook** | | :- | :- | :- | | `created` | Lead created the outgoing return. | No | | `under_review` | Lead is manually reviewing the outgoing return before sending it to the network. | Yes | | `posted` | Lead posted the outgoing return to your account. | Yes | | `rejected` | Lead, the counterparty, or the network rejected the outgoing return. | Yes | | **Return Request Status** | **Description** | **Webhook** | | :- | :- | :- | | `accepted` | You accepted the incoming return request by initiating an outgoing return. | No | ```mermaid theme={null} graph TD subgraph 2: Outgoing instant_payment return A(["created"]) B(["under_review"]) C(["rejected"]) E(["posted"]) A --> E A -- "Lead manual review" --> B A -- "Lead validation failure or network or counterparty rejection" --> C B -- "Manual review success" --> E B -- "Manual review failure" --> C end subgraph 1: Incoming return_request D(["response_needed"]) F(["accepted"]) G(["rejected"]) D -- "You accept" --> F D -- "You reject" --> G end subgraph State Key direction LR T([Start]) U([Pending]) V([Terminal]) end linkStyle 2 stroke:#155724,stroke-width:2px; classDef startStyle fill:#d4edda,stroke:#155724,stroke-width:3px; classDef progressStyle fill:#e1f5fe,stroke:#03a9f4,stroke-width:3px; classDef terminalStyle fill:#eceff1,stroke:#455a64,stroke-width:3px; classDef invisible fill:none,stroke:none class A,D,T startStyle; class B,U progressStyle; class C,E,F,G,V terminalStyle; class Z invisible; ``` ### Events Tracking the outgoing return requires listening to a broad set of events. These events cover exceptions and notifications when the funds returned are now available to the receiving party. | **Event** | **Description** | **Your Action** | | :- | :- | :- | | `.under_review` | The outgoing return is pending manual review from Lead before it will be sent to the network. | (Optional) Notify your customer that the return has not yet been submitted to the network. | | `.rejected` | The outgoing return has been rejected by Lead, the counterparty, or the network. | (Optional) Notify your customer that the return has been rejected. | | `.posted` | The outgoing return has been posted to the Lead account. | (Optional) Notify your customer that the funds for the return have left their account. | | `.counterparty_status_updated` | The counterparty status of the outgoing return has been updated. | (Optional) If the counterparty\_status is posted, notify your end customer that the return was successfully received by the recipient. | # Rejections Rejections surface on the `instant_payment` object's `rejection` hash, which carries `rejected_by`, `reason`, and `details`. Unless a case says otherwise, handle the `.rejected` webhook and read those fields. ## Outgoing payment rejected by Lead or the network The payment never reached the counterparty. `rejected_by` is `lead` or `network`. Follow up with Lead if the reason is unclear. ## Outgoing payment rejected by the counterparty Lead submitted the payment to the network and the counterparty rejected it. `rejected_by` is `counterparty`. Retry if appropriate. ## Outgoing payment posted but subsequently rejected by counterparty The outgoing payment reached `posted` status and completed its lifecycle, but `counterparty_status` changed to `rejected` afterward. Listen for `.counterparty_status_updated` rather than `.rejected` to inspect the rejection reason. Expect the counterparty to send the funds back as a separate return, which arrives as its own incoming `instant_payment` with a `.posted` webhook. Reconcile it against the original through `related_objects.original_payment_id`. ## Incoming payment rejected by account number controls Lead rejected an incoming payment, most often because of your configured [account number controls](/api-integrations/account-number/controls), which govern who may send to an account number. If the rejections are unexpected, update the controls. ## Incoming payment accepted but subsequently rejected Account number controls are the only way to refuse an incoming payment before it posts. If you want to implement other rejection criteria, simply return the payment after it posts with `POST /instant_payments/{id}/return`, which creates a new outgoing return payment. # Sandbox Testing Source: https://docs.lead.bank/products/instant-payments/sandbox-testing Test your Instant Payments integration Instant payments in sandbox use the same endpoints as production. Unlike ACH and wire transfers, instant payment statuses advance automatically in sandbox — you do not need to call a simulation endpoint to move an outgoing payment from `created` to `posted`. A few practical notes when testing: * **Routing numbers.** Lead does not publish a fixed list of designated sandbox routing numbers for instant payments. Any well-formed routing number can be used in the `creditor_agent.routing_number` (outgoing) or `debtor_agent.routing_number` (simulated incoming) field. The values shown in code examples (such as `987654321`) are illustrative, not reserved test values. * **Availability checks.** Call `POST /instant_payments/check_availability` first to confirm the routing number is reachable on the network before sending. * **Simulating an inbound payment.** Use `POST /v1/simulate/instant_payments/incoming` and supply your own `debtor_agent.routing_number`. The value is not validated against a real network. * **Simulating a return.** Use `POST /v1/simulate/instant_payments/{instant_payment_id}/incoming_return` against an existing posted outgoing payment. If you need a specific routing number to exercise a particular code path in sandbox, contact your Technical Account Manager. # Sending Instant Payments Source: https://docs.lead.bank/products/instant-payments/sending-instant-payments Send Instant Payments and Return Requests There are two requirements for sending instant payments. We recommend implementing both of these functions because instant payments, once sent, cannot be reversed. 1. **Sending Payments:** Send outgoing instant payments.  2. **Sending Return Requests:** Send outgoing return requests to recover funds sent erroneously in previous outgoing instant payments. > [!WARNING] > > If your customers are victims of fraud or send payments erroneously, return requests are the only recourse to recover their funds. ## Sending Payments Sending an instant payment creates a new `instant_payment` object with an outgoing direction. ### Endpoints You can check if the recipient's financial institution is available on the instant payment network and, if available, send instant payments to them. Once sent, outgoing instant payments can also be canceled. However, the cancellation window is very short and only possible if Lead has not yet submitted the payment to the network. This limited opportunity may occur during normal system processing or periods of manual review. | **Endpoint** | **Description** | | :- | :- | | `POST /instant_payments/check_availability` | Check the availability of a financial institution to accept instant payments. | | `POST /instant_payments` | Send an outgoing instant payment. | | `POST /instant_payments/{id}/cancel` | Attempt to cancel an outgoing instant payment. | ### Statuses Outgoing instant payments can transition through five potential statuses. Unlike returns, outgoing instant payments can terminate in the `canceled` status. The `counterparty_status` lifecycle only begins after the `instant_payment` object has reached a `posted` status. The purpose of this lifecycle is to precisely describe if/when the outgoing payment reaches the creditor. | **Instant Payment Status** | **Description** | **Webhook** | | :- | :- | :- | | `created` | Lead created the outgoing instant payment. | No | | `under_review` | Lead is manually reviewing the outgoing instant payment before sending it to the network. | Yes | | `canceled` | You canceled the outgoing instant payment. | No | | `posted` | Lead posted the outgoing instant payment to your account. | Yes | | `rejected` | Lead, the counterparty, or the network rejected the outgoing instant payment. | Yes | | **Counterparty Status** | **Description** | **Webhook** | | :- | :- | :- | | `under_review` | The counterparty is manually reviewing your payment before posting it to the creditor's account. | Yes | | `posted` | The outgoing instant payment posted to the creditor's account. | Yes | | `rejected` | The counterparty rejected your payment before it reached the creditor's account. | Yes | ```mermaid theme={null} graph TD subgraph Outgoing instant_payment A(["created"]) B(["under_review"]) C(["rejected"]) J(["canceled"]) E(["posted"]) A --> E A -- "Lead manual review" --> B A -- "Lead validation failure or network or counterparty rejection" --> C B -- "Manual review success" --> E B -- "Manual review failure" --> C A -- "You canceled" --> J B -- "You canceled" --> J end subgraph State Key direction LR T([Start]) U([Pending]) V([Terminal]) end linkStyle 0 stroke:#155724,stroke-width:2px; classDef startStyle fill:#d4edda,stroke:#155724,stroke-width:3px; classDef progressStyle fill:#e1f5fe,stroke:#03a9f4,stroke-width:3px; classDef terminalStyle fill:#eceff1,stroke:#455a64,stroke-width:3px; classDef invisible fill:none,stroke:none class A,D,W,T startStyle; class B,X,U progressStyle; class C,E,F,G,J,Y,Z,V terminalStyle; ``` ### Events You can follow the status of an outgoing payment event throughout its entire lifecycle - from initiation at Lead to subsequent events at the counterparty financial institution. | **Event** | **Description** | **Partner Action** | | :- | :- | :- | | `.under_review` | The outgoing instant payment is pending manual review from Lead before it will be sent to the network. | (Optional) Notify your customer that the instant payment has not yet been submitted to the network. | | `.rejected` | The outgoing instant payment has been rejected by Lead, the counterparty, or the network. | (Optional) Notify your customer that the instant payment has been rejected. | | `.posted` | The outgoing instant payment has been posted to the Lead account. | (Optional) Notify your customer that the funds for the instant payment have left their account. | | `.counterparty_status_updated` | The counterparty status of the outgoing instant payment has been updated. | (Optional) If the counterparty\_status is posted, notify your end customer that the instant payment was successfully posted to the creditor. | ## Sending Return Requests Sending a return request creates a new `return_request` sub-object within the existing outgoing `instant_payment`. ### Endpoints You can create a return request if you previously sent an instant payment and need to recover it. | **Endpoint** | **Description** | | :- | :- | | `POST /instant_payments/id/request_return` | Send an outgoing return request to the counterparty for a previously posted outgoing instant payment. | ### Statuses Outgoing return requests transition through three possible statuses from when the counterparty receives them through when they are ultimately resolved. | **Outgoing Status** | **Description** | **Webhook** | | :- | :- | :- | | `pending` | The outgoing return request is pending a response from the counterparty. | No | | `accepted` | The outgoing return request was accepted by the counterparty. | Yes | | `rejected` | The outgoing return request was rejected by the counterparty. | Yes | ```mermaid theme={null} graph TD subgraph 2: Outgoing return_request D(["pending"]) F(["accepted"]) G(["rejected"]) D -- "Counterparty accepted" --> F D -- "Counterparty rejected" --> G end subgraph 1: Outgoing instant_payment A(["created"]) B(["under_review"]) C(["rejected"]) J(["canceled"]) E(["posted"]) A --> E A -- "Lead manual review" --> B A -- "Lead validation failure or network or counterparty rejection" --> C B -- "Manual review success" --> E B -- "Manual review failure" --> C A -- "You canceled" --> J B -- "You canceled" --> J end subgraph State Key direction LR T([Start]) U([Pending]) V([Terminal]) end linkStyle 0 stroke:#155724,stroke-width:2px; classDef startStyle fill:#d4edda,stroke:#155724,stroke-width:3px; classDef progressStyle fill:#e1f5fe,stroke:#03a9f4,stroke-width:3px; classDef terminalStyle fill:#eceff1,stroke:#455a64,stroke-width:3px; classDef brownStyle fill:#efebe9,stroke:#5d4037,stroke-width:2px; classDef invisible fill:none,stroke:none class A,D,W,T startStyle; class B,X,U progressStyle; class C,E,F,G,J,Y,Z,V terminalStyle; class H,I brownStyle; ``` ### Events Tracking an outgoing return request involves listening to a single event that is triggered upon each status change. | **Event** | **Description** | **Your Action** | | :- | :- | :- | | `.return_request_status_updated` | The status of the outgoing return request has been updated. | (Optional) Notify your customer that the outgoing return request has been accepted or rejected. | # Statuses Source: https://docs.lead.bank/products/instant-payments/statuses View the status, counterparty status, and return request status for incoming and outgoing Instant Payments Use `status` to understand the Lead-side lifecycle of an instant payment, `counterparty_status` to understand the counterparty-side lifecycle for outgoing payments after the payment reaches `posted`, and the return\_request status to understand the lifecycle of a return request that references the given instant payment. ## Status | **Status** | **Description** | Direction | | :- | :- | - | | `created` | Lead created the outgoing instant payment. | Outgoing only | | `under_review` | Lead is manually reviewing the instant payment. | Incoming and outgoing | | `canceled` | You canceled the outgoing instant payment. | Outgoing only | | `posted` | Lead posted the instant payment to your account. | Incoming and outgoing | | `rejected` | Lead, the counterparty, or the network rejected the instant payment. | Incoming and outgoing | ## Counterparty Status | **Counterparty Status** | **Description** | **Direction** | | :- | :- | :- | | `under_review` | The counterparty is manually reviewing your outgoing payment before posting it to the creditor's account. | Outgoing only | | `posted` | The instant payment posted to the creditor's account. | Incoming and outgoing | | `rejected` | The counterparty rejected your outgoing payment before it reached the creditor's account. | Outgoing only | ## Return Request Status | Return Request Status | Description | Direction | | :- | :- | :- | | `response_needed` | The incoming return request requires a response from you. | Incoming only | | `pending` | The outgoing return request is pending a response from the counterparty. | Outgoing only | | `accepted` | The return request was accepted and a return is expected. | Incoming and outgoing | | `rejected` | The return request was rejected. | Incoming and outgoing | # Incoming Payments ```mermaid theme={null} graph TD subgraph 2: Incoming return_request status A(["response_needed"]) C(["accepted"]) D(["rejected"]) A -- "You return" --> C A -- "You reject" --> D end subgraph 1: Incoming status F(["START"]) H(["rejected"]) I(["under_review"]) J(["posted"]) F --> J F -- "Lead manual review"--> I I -- "Manual review failure" --> H I -- "Manual review success" --> J F -- "Lead validation failure" --> H end subgraph State Key direction LR X([Start]) Y([Pending]) Z([Terminal]) end linkStyle 3 stroke:#155724,stroke-width:2px; classDef startStyle fill:#d4edda,stroke:#155724,stroke-width:3px; classDef progressStyle fill:#e1f5fe,stroke:#03a9f4,stroke-width:3px; classDef terminalStyle fill:#eceff1,stroke:#455a64,stroke-width:3px; class F,A,X startStyle; class I,Y progressStyle; class C,D,H,J,Z,O terminalStyle; ``` # Outgoing Payments ```mermaid theme={null} graph LR subgraph 1: Outgoing status A(["created"]) B(["under_review"]) C(["rejected"]) J(["canceled"]) E(["posted"]) A --> E A -- "Lead manual review" --> B A -- "Lead validation failure or network or counterparty rejection" --> C B -- "Manual review success" --> E B -- "Manual review failure" --> C A -- "You canceled" --> J B -- "You canceled" --> J end E -.- D E -.- L subgraph 3: Outgoing return_request status D(["pending"]) F(["accepted"]) G(["rejected"]) D -- "Counterparty accepted" --> F D -- "Counterparty rejected" --> G end subgraph 2: Outgoing counterparty_status L(["START"]) M(["under_review"]) N(["rejected"]) O(["posted"]) L -- "Counterparty manual review" --> M M -- "Manual review failure" --> N M -- "Manual review success" --> O L -- "Counterparty rejected" --> N L -- "Counterparty accepted" --> O end subgraph State Key direction LR T([Start]) U([Pending]) V([Terminal]) end linkStyle 0 stroke:#155724,stroke-width:2px; classDef startStyle fill:#d4edda,stroke:#155724,stroke-width:3px; classDef progressStyle fill:#e1f5fe,stroke:#03a9f4,stroke-width:3px; classDef terminalStyle fill:#eceff1,stroke:#455a64,stroke-width:3px; classDef brownStyle fill:#efebe9,stroke:#5d4037,stroke-width:2px; classDef invisible fill:none,stroke:none class A,D,W,T,L startStyle; class B,X,U,M progressStyle; class C,E,F,G,J,Y,Z,V,N,O terminalStyle; class H,I brownStyle; ``` # The Instant Payment Object Source: https://docs.lead.bank/products/instant-payments/the-instant-payment-object Send and receive Instant Payments via FedNow and RTP The `instant_payment` object describes both incoming and outgoing payments and is organized into three sections: payment details, related messages, and return requests. ## Payment Details ```json theme={null} { "id": "instant_payment_xyz123", "account_id": "account_xyz123", "account_number_id": "account_number_xyz123", "created_at": "ISO-8601", "updated_at": "ISO-8601", "direction": "enum(incoming|outgoing)", "payment_rail": "enum(fednow|rtp)", "status": "enum(created|under_review|canceled|rejected|posted)", "counterparty_status": "enum(under_review|rejected|posted)", "amount": 5000, "currency_code": "USD", "description": "Payment for invoice 12345", "ultimate_debtor": { "name": "Alex Smith", "account number": "1234567890" }, "debtor": { "name": "Alex Smith", "account number": "1234567890" }, "initiating_party": { "name": "Alex Smith", "account number": "1234567890" }, "debtor_agent": { "routing_number": "987654321" }, "instructing_agent": { "routing_number": "987654321" }, "instructed_agent": { "routing_number": "987654321" }, "creditor_agent": { "routing_number": "987654321" }, "creditor": { "name": "Alex Smith", "account_number": "0987654321" }, "ultimate_creditor": { "name": "Alex Smith", "account_number": "0987654321" }, "payment_identifiers": { "end_to_end_id": "string", "uetr": "string", "transaction_id": "string" }, "return": { "reason": "enum", "details": "string" }, "rejection": { "rejected_by": "enum(lead|network|counterparty)", "reason": "enum", "details": "string" }, ``` ## Related Objects ```json theme={null} "related_objects": { "original_payment_id": "instant_payment_xyz123", "return_payment_ids": ["instant_payment_xyz123"] }, ``` ## Return Requests ```json theme={null} "return_requests": [{ "created_at": "ISO-8601", "deadline": "ISO-8601", "status": "enum(response_needed|pending|rejected|accepted)", "reason": "enum", "details": "string", "resolution": { "resolved_at": "ISO-8601", "resolved_by": "enum(client|lead|network|counterparty)", "rejection_reason": "enum", "rejection_details": "string" } }] ``` # Timing & Availability Source: https://docs.lead.bank/products/instant-payments/timing-and-availability Sending and receiving payments Instant payments are fast and always available. They settle in seconds 24/7/365 and are not subject to business-day or cutoff constraints. # Validations & Best Practices Source: https://docs.lead.bank/products/instant-payments/validations Best practices to reduce instant payment validation exceptions. Lead does not queue instant payments. Instead, synchronous validation failures result in no creation of an `instant_payment` object and an HTTP error response, and asynchronous validation failures result in a `.rejected` webhook and a populated `rejection` hash with additional details. The table below contains a list of validations that Lead performs. We run validations synchronously and asynchronously. | Lead Validation | Best Practice | Direction | | - | - | - | | `parameters_invalid` | Ensure all request parameters are provided and adhere to Lead's rules. | Outgoing | | `non_sufficient_funds` | Check if there are sufficient funds before requesting an outgoing payment. | Outgoing | | `account_number_incorrect` | Check if the sender's account is active before attempting to send an outgoing payment. | Outgoing | | `limit_exceeded` | Request outgoing daily and 30-day payment limits that are consistent with the payment demand you expect. As your business grows, request that Lead increases your limits. | Outgoing | | `routing_number_format_incorrect` | Check if the creditor's routing number is accurate before submitting an instant payment. | Outgoing | | `restricted_by_account_number_controls` | Use account number controls to constraint payment activity within known bounds. Ensure valid payments are not blocked by these restrictions. | Outgoing and incoming | | `participant_not_on_network` | Call the `/check_availability` endpoint to verify that a creditor is enabled for instant payments before creating an outgoing instant payment. | Outgoing | | `participant_signed_off` | This may occur if a counterparty is offline during maintenance or downtime. There is nothing you can do to avoid this error. | Outgoing | | `creditor_name_mismatch` | Ensure your customers and the parties they transact with are aware that creditor names must be accurate. | Incoming | | `regulatory` | Business-to-business payments of \$3,000 or greater must include a debtor address. Ensure your customers' partner banks include it when sending instant payments. | Incoming | # Internal Transfer Failures Source: https://docs.lead.bank/products/internal-transfer/exceptions How internal transfers fail, what the failure reasons mean, and how to recover. Build your integration to treat `processing` as pending — do not assume success from the 200 alone. Act on the webhooks: | **Event** | **Description** | | :- | :- | | `internal_transfer.posted` | Money has successfully moved from the `sender_account_number_id` to the `receiver_account_number_id`. | | `internal_transfer.rejected` | The transfer was not completed and will not be retried. See `rejection.reason` and `rejection.details`. | Rejection reasons: | **Reason** | **Description** | | :- | :- | | `account_number_not_active` | A referenced Account Number is not in `active` status. Example detail: "Account number account\_123 is inactive." | | `beneficiary_account_number_unrecognized` | The receiver Account Number was not recognized. | | `non_sufficient_funds` | The originating account did not have sufficient balance. Balance: \[BALANCE] | | `internal_error` | An internal error occurred. | # The Internal Transfer Object Source: https://docs.lead.bank/products/internal-transfer/internal-transfer-object Field-level reference for the Internal Transfer object. ```json theme={null} { "id": "internal_transfer_xyz123", "amount": 5000, "currency_code": "USD", "sender_account_id": "account_xyz123", "sender_account_number_id": "account_number_xyz123", "receiver_account_id": "account_xyz123", "receiver_account_number_id": "account_number_xyz123", "status": "processing", "description": "string", "metadata": { "additionalProp": "string" }, "created_at": "2022-06-27T11:22:33Z", "updated_at": "2022-06-27T11:22:33Z" } ``` # Internal Transfers at Lead Source: https://docs.lead.bank/products/internal-transfer/overview Move money between your own accounts held at Lead. Internal Transfers move money between accounts held at Lead. When you submit a request to create an Internal Transfer, you will receive a 200 response and the status of the transfer will be set to `processing`. Most of the time, these requests are completed successfully within seconds, but there are some instances where additional processing is required. If an issue is encountered in processing the request, Lead will continue to retry until we inform you of a terminal status (`posted` or `rejected`). When all processing is completed successfully, Lead will notify you via an `internal_transfer.posted` webhook. If processing the request is unsuccessful and all retries have been exhausted, we will notify you of the failure via an `internal_transfer.rejected` webhook. ## Internal Transfer Events | **Event** | **Description** | | - | - | | internal\_transfer.posted | The internal transfer was completed and money has successfully moved from the `sender_account_number_id` to the `receiver_account_number_id` | | internal\_transfer.rejected | The internal transfer was not completed and will not be retried. Please see `rejection.reason` and `rejection.details` for more information. | ## Rejection Reasons | **Reason** | **Description** | | - | - | | non\_sufficient\_funds | The originating account did not have sufficient balance. Balance: \[BALANCE] | # Internal Transfer Sandbox Testing Source: https://docs.lead.bank/products/internal-transfer/sandbox Test internal transfers in Lead's sandbox environment. Internal transfers need no simulation endpoints and no setup. Create a transfer with `POST /v1/internal_transfer` and it processes automatically: within seconds it moves from `processing` to `posted` and fires the `internal_transfer.posted` webhook, the same sequence you'll see in production. ## What's Different From Production The sandbox is not connected to a ledger for this rail, which has two consequences: * **Every transfer succeeds.** No balance checks run, so you don't need to fund the sender before testing, and you can't trigger a rejection like `non_sufficient_funds`. Build your rejection handling from the webhook and rejection reasons documented in [Handling Failures](/products/internal-transfer/exceptions); the `internal_transfer.rejected` event can't be produced in sandbox. * **Balances don't move.** A posted transfer doesn't change the sender or receiver balance, so don't reconcile balances against internal transfers in sandbox. Synchronous request validation still applies: an invalid request, such as a transfer between two Account Numbers under the same Account, returns a `400` the same way it does in production (see [Sending an Internal Transfer](/products/internal-transfer/sending)). ## Test the Happy Path 1. Create the transfer with `POST /v1/internal_transfer`. The 200 response returns the transfer in `processing`. 2. Within seconds, the transfer moves to `posted` and fires the `internal_transfer.posted` webhook. No advancement call is needed. # Sending an Internal Transfer Source: https://docs.lead.bank/products/internal-transfer/sending Send an internal transfer between your Lead accounts: request requirements, statuses, and webhooks. Create an Internal Transfer with `POST /v1/internal_transfer`. You will receive a 200 response and the transfer's status will be processing. You cannot use an Internal Transfer to move funds between Account Numbers belonging to the **same Account** — such requests are rejected with `400 operation_not_allowed`. To move money between two of your accounts, the sender and receiver Account Numbers must belong to different Accounts. # Internal Transfer Statuses Source: https://docs.lead.bank/products/internal-transfer/statuses Statuses and lifecycle transitions for internal transfers. | **Status** | **Description** | **Terminal** | **Webhook** | | :- | :- | :- | :- | | `processing` | Lead received the request and is executing it. Most transfers complete within seconds; if an issue is encountered, Lead retries until reaching a terminal status. | No | No | | `posted` | The transfer completed; money moved from the sender to the receiver Account Number. | Yes | `internal_transfer.posted` | | `rejected` | The transfer was not completed and will not be retried. See `rejection.reason` and `rejection.details`. | Yes | `internal_transfer.rejected` | # Internal Transfer Timing & Availability Source: https://docs.lead.bank/products/internal-transfer/timing Internal transfers settle immediately and are available 24/7/365. Immediate settlement, 24/7/365. No processing windows apply to this rail. # The Balance Object Source: https://docs.lead.bank/products/lending/balance-object Field-level reference for the Subledger Balance — the loan or line of credit itself: creation requirements, non-revolving vs. revolving structures, rate fields, and the live position Lead maintains. A Balance is the loan or line of credit itself — one Balance per term loan, line of credit, or overdraft product, with `type: credit`, created through the [Subledger Balance API](/api-reference/endpoint/subledger-balance/create-a-subledger-balance) before any money moves. It carries the product's terms at creation and, once live, Lead's view of the current position. [Fundings](/products/lending/funding-object) draw against it; your daily [Balance file reporting](/products/balances-and-transactions/overview) keeps its position current. > [!NOTE] > > **Naming.** The API object is the **Subledger Balance** (`subledger_balance_*` IDs); in concept pages we say Balance. Future versions will standardize the name to Balance. Use the `subledger_balance_*` ID as the `balance_id` when reporting on this object in the daily Balance file. ## Creating a Balance `POST /v0/subledger_balances` with a required `Idempotency-Key` header (5–255 characters). The newly created Balance is `active` with `status_reason: active`. | **Field** | **Type** | **Required** | **Description** | | :- | :- | :- | :- | | `account_id` | string | Yes | The parent [Account](/products/accounts/overview). Must be in `active` or `inactive` status, and if the account declares `capabilities`, they must support the requested balance type. | | `client_subledger_balance_name` | string (≤64) | Yes | The product name offered to the end user (e.g., "Personal Loan — Home Improvement", "BNPL loan"). | | `currency_code` | string | Yes | ISO 4217. `USD` only today. | | `type` | enum | Yes | `credit` is the only value on create. (The response enum also includes `deposit`, reserved for future use.) | | `details` | object | Yes | The structure and terms — see below. `details.structure` is required. | | `client_settlement_bank_account_id` | string | No | The underlying settlement bank account where funds for this Balance are held. Only applicable for certain use cases. | | `metadata` | object | No | Arbitrary key-value pairs. | ## Two Structures `details.structure` declares how the credit behaves, and it changes what's required: | | **`non_revolving`** (term loan, BNPL) | **`revolving`** (line of credit, credit card) | | :- | :- | :- | | Behavior | Fixed principal; repayments do not restore available credit | Subject to a limit; repayments restore available credit | | Lifecycle | A new Balance per loan, closed at terminal status | One Balance stays open across many draws and repayments | | **Required on create** | `expected_maturity_date` · `repayment_details` · `max_funding_amount` · `term` · **`expected_finance_charge_amount`** | `repayment_details` only | > [!WARNING] > > All five non-revolving fields are required — including `expected_finance_charge_amount` (minor units), which is easy to miss. Omitting any returns a 422 with the offending parameter named in `invalid_parameters`. **Structure-specific fields:** | **Field** | **Type** | **Description** | | :- | :- | :- | | `expected_maturity_date` | date | Expected maturity. Must not be in the past when a [Funding](/products/lending/funding-object) is created against this Balance. | | `max_funding_amount` | integer | Maximum cumulative funding, minor units — for a term loan, the total loan amount. Cumulative principal across Fundings in `posted` or `processing` status cannot exceed it. | | `term` | object | `{ value, unit }` where `unit` ∈ `days` / `weeks` / `months` / `years` — the contractual term from origination to expected maturity. | | `expected_finance_charge_amount` | integer | The expected finance charge, minor units. | | `repayment_details` | array | The expected repayment schedule — see the [reference](api-reference/endpoint/subledger-balance/create-a-subledger-balance#body-details-one-of-0-repayment-details) for more. | ## Rate and Servicing Fields (both structures) | **Field** | **Type** | **Description** | | :- | :- | :- | | `autopay_method` | enum | `ach`, `debit_card`, `wire`, `virtual_wallet`, `credit_card`, or `none`. Required for `credit`. | | `is_interest_based` | boolean | Whether the Balance accrues interest. Required for `credit`. | | `interest_rate` | string | The contractual (nominal) annual rate on outstanding principal, ignoring compounding and fees. **Required when `is_interest_based` is `true`.** Exactly 6 decimals (e.g., `9.990000`). | | `effective_apr` | string | The APR as disclosed to the borrower. Required for `credit`. Exactly 3 decimals (e.g., `10.250`). | | `effective_interest_rate` | string | The true annualized cost of borrowing including compounding. Required for `credit`. Exactly 6 decimals (e.g., `9.500000`). | | `balances.rewards.unit` | enum | `usd` or `points`, if the product carries rewards. | ## The Live Position The Balance response carries a `balances` object — Lead's current view of the position, maintained from your daily reporting: | **Sub-object** | **Fields** | | :- | :- | | `core` | `amount` (+ `amount_in_usd`), decomposed into `outstanding_principal`, `outstanding_interest`, `outstanding_fees` | | `rewards` | `amount`, `unit` (`usd`/`points`) | | `dispute` | `amount` + `principal`/`interest`/`fees` under dispute | | `charge_off` | `amount` + charged-off `principal`/`interest`/`fees` | | `past_due` | `amount`, `past_due_days`, + past-due `principal`/`interest`/`fees` | These are the same components your daily files must reconcile — `core.amount` must equal the sum of its three components, and each day's position must equal yesterday's plus the day's transactions ([Balance Reconciliation](/products/balances-and-transactions/balance-reconciliation)). ## Statuses | **Status** | **Meaning** | | :- | :- | | `active` | Live; Fundings may be created against it (default on creation). | | `inactive` | Temporarily deactivated. | | `closed` | Terminal. | Statuses are yours to report and maintain — see [Balance Statuses](/products/balances-and-transactions/balance-statuses) for the full lifecycle. A Balance cannot be reported into a terminal status while any Funding against it is still `processing` (`balance_cannot_be_terminal_with_processing_funding`). ## Example Balance Object ```json theme={null} { "id": "subledger_balance_k8L2n9QpW3xR5vT7mZ4jS1bA6cG", "account_id": "account_v9K4p2M7nL1wQ8xR5zB6tY3jH0gA", "client_subledger_balance_name": "Personal Loan - Home Improvement", "currency_code": "USD", "created_at": "2025-09-02T11:01:36Z", "updated_at": "2025-09-02T11:05:00Z", "status": "active", "status_reason": "active", "type": "credit", "details": { "structure": "non_revolving", "expected_maturity_date": "2027-09-01", "max_funding_amount": 10000000, "term": { "value": 24, "unit": "months" }, "expected_finance_charge_amount": 100000, "repayment_details": [ { "expected_payment_frequency": "monthly", "expected_number_of_payments": 24, "expected_first_payment_date": "2025-10-01", "expected_payment_amount": 4167, "expected_last_payment_date": "2027-09-01", "expected_last_payment_amount": 4167 } ], "autopay_method": "ach", "is_interest_based": true, "interest_rate": "9.990000", "effective_apr": "10.250", "effective_interest_rate": "9.500000", "balances": { "core": { "amount": 8944, "amount_in_usd": 8944, "outstanding_principal": 5000, "outstanding_interest": 2522, "outstanding_fees": 1422 }, "past_due": { "amount": 15, "past_due_days": 15, "principal": 15, "interest": 0, "fees": 0 } } }, "metadata": {} } ``` # Balance-Sheet Models: Originate-to-Sell & On-Sheet Lending Source: https://docs.lead.bank/products/lending/balance-sheet-models The two answers to whose balance sheet holds the loan: Originate-to-Sell, where you purchase receivables daily after a hold period, and On-Sheet Lending, where Lead holds them to terminal status. Lead supports two answers to *whose balance sheet holds the loan*, agreed between Lead and your organization at contract signing. | | **Originate-to-Sell (OTS)** | **On-Sheet Lending (OSL)** | | :- | :- | :- | | **Receivable ownership** | Lead holds the receivable from origination through the hold period, then transfers ownership to you via the daily sale. You hold it through its terminal status (paid in full, charged off). | Lead holds the receivable from origination through its terminal status. | | **The daily sale** | Contains the day's receivables for you to purchase. | Still runs on the same daily schedule, but contains no on-sheet receivables — the exchange confirms Lead is holding them rather than transferring ownership. | | **Everything else** | Identical: the same origination objects, the same Funding flow, the same daily servicing reporting. | Identical. | > [!NOTE] > > **On-Sheet Lending availability:** OSL is Preview. Talk to your Lead team about the offering and when your program can enable it. ## Why the Model Matters to Your Integration Mechanically, almost nothing changes — the daily exchange runs either way, and every other API and file interface is identical under both models. What changes is what the exchange *means* and where accuracy is load-bearing: * **Under OTS**, the daily sale is a real asset transfer with a real cash movement, so a funded operating account and same-day confirmation are the daily obligations. * **Under OSL**, Lead's held position is maintained from what you report, so your daily [Balance and Transaction reporting](/products/balances-and-transactions/overview) is what keeps Lead's balance sheet accurate — reporting accuracy becomes critical, not only compliance-relevant. # The Funding Object Source: https://docs.lead.bank/products/lending/funding-object Field-level reference for the Funding object — your instruction to Lead to originate loan principal: the principal decomposition, fee fields, the three-state lifecycle, and sandbox testing. A Funding is your instruction to Lead to **originate principal** — Lead moves the funds from a Lead GL to your program's funding FBO account, and the drawn amount becomes a [receivable on Lead's books](/products/lending/receivables-and-the-daily-sale). This is an **executing** object ([Executing vs. Reporting](/core-concepts/platform/executing-vs-reporting)): the call moves money. A non-revolving Balance typically has one Funding; a revolving Balance takes a Funding per draw. ## Creating a Funding `POST /v0/fundings` with a required `Idempotency-Key` header (5–255 characters). Prerequisites, enforced at creation: * The referenced [Balance](/products/lending/balance-object) must be **`active`**, and if it has an `expected_maturity_date`, that date must not be in the past. * `currency_code` must match the Balance's currency. * For `non_revolving` Balances: the sum of all `principal.*` fields on this request **plus** the `principal.*` sums of every prior Funding in `posted` *or `processing`* status against the same Balance must not exceed the Balance's `max_funding_amount` — in-flight draws count against the ceiling. | **Field** | **Type** | **Required** | **Description** | | :- | :- | :- | :- | | `subledger_balance_id` | string | Yes | The Balance being drawn against. | | `currency_code` | enum | Yes | `USD` only today; must match the Balance. | | `principal` | object | Yes | The funded principal, decomposed — see below. | | `other_fees` | object | No | Fees Lead needs for bookkeeping only — see below. | | `metadata` | object | No | Arbitrary key-value pairs (e.g., your draw ID). | ### `principal` (object) The total of these fields is the loan principal. **Upon funding, this amount is considered disbursed, and Lead begins applying imputed interest** ([Sales Settlement Amount](/products/funding-and-receivables/sales-settlement-amount)). | **Field** | **Type** | **Description** | | :- | :- | :- | | `external_disbursement_amount` | integer | The portion made available for external disbursement at funding time (minor units). | | `withheld_amount` | integer | The portion withheld and not disbursed externally at funding time (minor units). **Invariant: at least one of `external_disbursement_amount` or `withheld_amount` must be > 0.** | | `merchant_origination_fee_amount` | integer | Origination fees charged to the merchant, **included in** the principal (minor units). Must be **less than** `external_disbursement_amount + withheld_amount`. | ### `other_fees` (object) | **Field** | **Type** | **Description** | | :- | :- | :- | | `borrower_origination_fee_amount` | integer | **Non-capitalized** origination fee charged to the borrower at funding (minor units) — not part of principal; Lead needs it for bookkeeping only. When you later report the disbursement transaction, its `fee_amount` must equal this value or the file fails `funding_fee_amount_mismatch` ([troubleshooting](/file-reference/balances-and-transactions/troubleshooting)). | ### Worked example: a \$1,000 BNPL purchase A customer finances a 100 origination fee, half the purchase disburses to the merchant now and half is withheld pending delivery, and the borrower pays a separate \$2 processing fee: ```json theme={null} { "subledger_balance_id": "subledger_balance_1HCpXwx2EK9oYluWbacgeCnFcLf", "currency_code": "USD", "principal": { "external_disbursement_amount": 45000, "withheld_amount": 45000, "merchant_origination_fee_amount": 10000 }, "other_fees": { "borrower_origination_fee_amount": 200 }, "metadata": { "client_draw_id": "X67BU" } } ``` Principal = $450 \+ $450 + $100 \= $1,000 — the merchant fee is *inside* principal (the borrower owes it); the borrower's \$2 fee rides outside as `other_fees`. ## **Lifecycle** | Status | Meaning | | - | - | | `processing` | Created; Lead is moving the funds. Counts against `max_funding_amount`. | | `posted` | Funds have moved to your funding FBO; the receivable exists on Lead's books. Terminal. | | `rejected` | The Funding will not complete — see the `rejection` object. Terminal. | The `rejection` object is always present on the Funding (empty strings when not rejected), with `reason` (currently the single enum `internal_error` — the spec notes Lead may add values as non-breaking changes, so handle unknown reasons gracefully) and `details` (reserved for future use). Status changes are delivered by webhook (`funding.posted` **\[VERIFY event name against the webhooks reference]**); a Balance cannot be reported into a terminal status while a Funding against it is still `processing`. ## **Sandbox** In sandbox, Fundings stay `processing` until you advance them: call [Simulate Advance Funding](/api-reference/endpoint/funding/advance-a-funding) to transition to `posted` and exercise your downstream flows end to end ([Originate Your First Loan](/get-started/quickstart/originate-your-first-loan)). ## **Example Funding Object** ```json theme={null} { "id": "funding_0o5Fs0EELR0fUjHjbCnEtdUwQe3", "subledger_balance_id": "subledger_balance_1HCpXwx2EK9oYluWbacgeCnFcLf", "currency_code": "USD", "principal": { "external_disbursement_amount": 100000, "withheld_amount": 1000, "merchant_origination_fee_amount": 100 }, "other_fees": { "borrower_origination_fee_amount": 200 }, "metadata": { "client_draw_id": "X67BU" }, "status": "processing", "rejection": { "reason": "", "details": "" }, "created_at": "2025-09-02T11:01:36Z", "updated_at": "2025-09-02T11:05:00Z" } ``` Full schemas: [Create a Funding](/api-reference/endpoint/funding/create-a-funding) · [Retrieve a Funding](/api-reference/endpoint/funding/retrieve-a-funding). # Receivables & the Daily Sale Source: https://docs.lead.bank/products/lending/receivables-and-the-daily-sale Why every Lead-originated loan or card spend creates a receivable, how the hold period works, and how each day's receivables are grouped into a single sale you purchase — today via the Sales Request/Response files, with a Sale API in flight. > [!NOTE] > > **Integration surface today:** the daily sale runs as the **Sales Request/Response file exchange** over SFTP — schemas: [Sales Request](/file-reference/sales/request-schema) · [Sales Response](/file-reference/sales/response-schema). **A Sale API is in flight** that replaces the exchange with a daily sale object and webhooks; it will be announced in [Upcoming Changes](/upcoming-changes) when sandbox access opens. The cycle described on this page is identical across both transports. ## Why Receivables Exist Lead is the lender of record, so every origination — a [Funding](/api-reference/endpoint/subledger-balance/create-a-subledger-balance) you request, or card spend arriving through [network settlement](/products/network-settlement/overview) — creates a **receivable**: Lead's claim on that loan, held on Lead's balance sheet. What happens next depends on your program's [balance-sheet model](/products/lending/balance-sheet-models). Most programs run **Originate-to-Sell**, where receivables are sold to you daily; this page describes that cycle. ## The Cycle 1. **Origination.** The receivable is created and its **hold period** — a program-level number of business days — begins. 2. **The hold period.** While Lead holds the receivable, **imputed interest** accrues daily at your program's configured rate. This is the interest component of the eventual settlement amount — see [Sales Settlement Amount](/products/funding-and-receivables/sales-settlement-amount) for exactly how the day's purchase is priced. 3. **The daily sale.** Each business day, every receivable past its hold period is grouped into **one sale for the day**. The day's purchase settles **whole**: a single cash movement from your operating account for the day's settlement amount, with all of the day's receivables transferring together. There is no partial settlement — the day succeeds or fails as a unit. 4. **Empty days are explicit.** A day with no receivables to sell still produces the day's exchange, so a quiet day is always distinguishable from a broken pipeline. ## Operating the Cycle Treat the sale as a **daily operational rhythm**, not an event to react to: * **Reconcile against the day's sale as a unit** — the day's total, then its member receivables. This is the shape guaranteed stable across the file→API transition, so reconciliation built this way carries over unchanged. * **Fund the operating account as a daily pre-check.** Because settlement is all-or-nothing, an insufficient-funds failure fails the entire day's sale. On a failure, fund the account and coordinate with your Lead team on the retry. * **Handle the empty-day case from day one** — your pipeline should treat "explicitly nothing to buy" as a success state. ## What Changes with the Sale API *Preview — full details at announcement in [Upcoming Changes](/upcoming-changes).* The day's sale becomes a queryable **sale object** carrying the day's rollup totals and a breakdown into member **receivable** objects, with webhooks when the day's sale is created and when it settles — replacing file parsing with object reads and giving you a forecast surface for what you'll purchase and when. The daily grain, whole-day settlement, and pricing do not change. # Products Source: https://docs.lead.bank/products/overview Lead's products grouped by ownership and function: customers & accounts, banking infrastructure, payment rails, and lending & settlement. Everything you can build on runs through the same small set of objects — **Entity** (who) → **Account** (the product relationship) → **Balance** (tracked value) → **Account Numbers** (routable addresses) and **Transactions** (records of activity) — connected as the [Object Model](/core-concepts/platform/object-model) describes and composed differently per program. This section groups the platform by ownership and function: **Customers & Accounts** — the objects representing your end customers and their products. You are the ledger of record here: these are **reporting** APIs and files ([Executing vs. Reporting](/core-concepts/platform/executing-vs-reporting)) — the *user surface* on the [Object Model](/core-concepts/platform/object-model) page. Start with [Entity](/products/entity/overview); [Accounts](/products/accounts/overview) and [Balances & Transactions](/products/balances-and-transactions/overview) carry the financial picture; [Applications](/products/applications/overview) and [Cards](/products/cards/overview) serve credit and card programs. [**Banking Infrastructure**](/products/banking-infrastructure/overview) — the real bank accounts behind your program (FBOs, operating and settlement accounts — the *core surface*, Lead-managed) and the [Account Numbers](/products/account-number/overview) that make balances routable. **Payment Rails** — six **execution** APIs that move money: [ACH](/products/ach/overview) · [Wires](/products/wire/overview) · [Instant Payments](/products/instant-payments/overview) · [Internal Transfer](/products/internal-transfer/overview) · [Blockchain Payments](/products/blockchain-payments/overview) · [Checks](/products/checks/overview). Choosing between them: [Money Movement](/core-concepts/platform/money-movement) in Core Concepts. **Funding & Settlement** — funds flows between your program and Lead's balance sheet or the card networks: [Funding & Receivables](/products/funding-and-receivables/overview) (extending credit; selling receivables) and [Network Settlement](/products/network-settlement/overview). Each product page links its endpoint documentation in the [API Reference](/api-reference) and, where a file transport exists, its schemas in the [File Reference](/file-reference/overview). Which surface each product uses today: [Integration Surfaces by Product](/core-concepts/platform/integration-surfaces-by-product). # USD International Wires Source: https://docs.lead.bank/products/wire/international-wires Send and receive USD international wires. ## Overview An international wire is a wire transfer where either the sending or receiving financial institution is located outside the United States. Lead facilitates outgoing USD international wires by initiating a Fedwire to a U.S. intermediary, which routes the payment to the foreign creditor agent. > [!TIP] > > USD international wires use the same wire object and [POST /v1/wires endpoint](/api-reference/endpoint/wire/create-a-wire-v1) as domestic wires. ### How International Wires Work International wire transfers are typically processed through correspondent banking relationships.  When a bank needs to send funds to a foreign bank that it does not have a direct relationship with, the payment is routed through an intermediary bank that can settle the payment on its behalf. This intermediary is known as a correspondent bank. Multiple banks may be involved in the payment chain before the funds reach the receiving bank (referred to as the creditor agent in ISO terminology). Banks often exchange international payment instructions through the SWIFT messaging network, which allows financial institutions to share routing and payment details. However, SWIFT does not move money itself. It is a messaging system used to coordinate payments between banks. Settlement of USD payments typically occurs through U.S. banks capable of receiving Fedwire transfers. At Lead, outgoing USD international wires are processed by sending a Fedwire payment to a U.S. intermediary bank. This intermediary then routes the payment through its correspondent network to the foreign creditor agent. > [!NOTE] > > Interested in enabling international wires? Contact your Technical Account Manager for more details. ### Before You Begin It's important to know that international wire reach depends on correspondent relationships. A payment can be delivered only if the creditor agent (or a bank in its correspondent chain) maintains a USD correspondent path that includes a U.S. bank capable of receiving a Fedwire and settling USD. > [!WARNING] > > If no valid U.S. correspondent path exists, the wire will be rejected. ## Sending International Wires Sending an international wire uses the same [POST v1/wires API](/api-reference/endpoint/wire/create-a-wire-v1) as domestic wires. To send a USD international wire: **1. Provide Business Identifier Code** Use `creditor_agent.business_identifier_code` (must be a foreign bank BIC) > [!WARNING] > > **Do not use** `creditor_agent.routing_number` > > If you provide both the **business identifier code** and **routing number**, we will return with code 422. **Sample Request** ```json theme={null} { "account_number_id": "account_number_xyz123", "amount": 5000, "currency_code": "USD", "creditor_agent": { "business_identifier_code": "ROYCCAT2" }, "creditor": { "name": "Allan Scott", "account_identifier": { "type": "account_number", "value": "1032345678" }, "address": { "line_one": "123 Main St", "line_two": "Suite 100", "line_three": "Kansas City, MO 64105" } }, "remittance_details": { "transfer_purpose": { "type": "invoice_payment", } } } ``` Outgoing international wires return `corridor_type: international` on the wire object. Lead sets this field; it is not part of the request. ### Use Your Own Intermediary Because Fedwire is a domestic U.S. rail, a U.S. correspondent capable of settling USD must exist in the creditor agent’s correspondent chain. By default, Lead attempts to identify an appropriate intermediary automatically. If you prefer to use a specific intermediary, provide either: * `instructed_agent.business_identifier_code` (must be a U.S. bank BIC) * `instructed_agent.routing_number` Lead will route the wire as specified. ### Fees and Deductions * Lead fees apply per your agreement. * Intermediary banks and/or the creditor agent may deduct additional fees. * These deductions may reduce the final credited amount and are outside of Lead’s control. Lead does not guarantee full principal delivery due to intermediary fee practices. ### Prohibited Countries International wires remain subject to Lead’s [prohibited countries](https://partners.lead.bank/prohibited-countries) and compliance policies. Certain corridors may be restricted regardless of the correspondent reach. ### Status Visibility International wires use the same [lifecycle](/products/wire/statuses) as domestic wires. However, **posted** indicates that the Fedwire leg has been released to the instructed agent (U.S. correspondent). It does not confirm final credit to the creditor’s account as Lead does not receive confirmation of final credit from the creditor agent. ## Receiving International Wires You can receive USD international wires as long as the debtor agent (or its correspondent chain) can deliver a Fedwire to Lead. Provide senders with the following settlement details: | **ABA Routing Number** | **BIC** | | - | - | | 101019644 | LEADUS49 | > [!TIP] > > Whenever possible, provide **both the ABA routing number and BIC**, as this is the most reliable way to ensure the wire is correctly routed to Lead. > [!WARNING] > > If you operate under a different routing number, contact your Technical Account Manager. Delays, returns, or rejections may occur if a wire is sent using a different BIC. Incoming international wires return `corridor_type: international` on the wire object. To return only international wires, use `corridor_type=international` when calling List Wires. # Wires at Lead: Transfers Over Fedwire Source: https://docs.lead.bank/products/wire/overview Receive or send wire transfers through the Fedwire network. > [!WARNING] > > **Upcoming Change** > > To support additional Fedwire ISO 20022 mandates, we're introducing Wires API V2 with structured address requirements and additional wire enhancements. > > The Fedwire release originally planned for November 2026 has been delayed, and migration to V2 is not required in Q4 2026. > > The Wires API V2 specification is in preview and can change before sandbox and production release. API release dates will be announced in the Wires API V2 Migration Guide. > > 👉 [View V2 Migration Guide](/products/wire/v2-migration) Wire transfers move funds between financial institutions through wire payment networks such as Fedwire. Lead has a direct connection to Fedwire and supports both domestic and international wires through the same API endpoints. Domestic wires sent before Lead’s cutoff generally settle the same business day. International wires may take longer depending on the destination and correspondent banking path. **Use wires when** you need to send large-dollar, time-sensitive, or international payments. Wires are generally irrevocable once sent. If funds are sent in error, you can request their return, but the receiving financial institution is not obligated to return them. **What you can do:** * Send and receive wires * Cancel eligible outgoing wires before they are sent * Return incoming wires * Send and respond to return requests for posted wires **On this rail:** * [The wire object](/products/wire/wire-object) — all fields and identifiers available on a wire, including agents, identifiers, amounts, and remittance details * [Wire statuses](/products/wire/statuses) — how a wire moves through each stage of processing * [Return requests](/products/wire/return-requests) and [Return codes](/products/wire/rejection-and-return-codes) — requesting the return of funds and handling counterparty requests * [USD international wires](/products/wire/international-wires) — how Lead supports international USD payments * [Processing windows](/products/wire/processing-windows) — cutoff times for sending wires * [Sandbox](/products/wire/sandbox-testing) — simulating incoming monetary wires, advancing them through the wire lifecycle, and simulating return requests # Wire Timing & Availability Source: https://docs.lead.bank/products/wire/processing-windows Understand when wires can be processed. ## Operating Hours The [Fedwire Funds Service](https://app.frbservices.org/resources/financial-services/wires/operating-hours.html) operates on business days, opening at 8:00 p.m. CT on the preceding calendar day and closing at 6:00 p.m. CT, Monday through Friday, excluding designated holidays. For example, the Monday business day opens at 8:00 p.m. CT on Sunday evening. You can submit outgoing wire transfers through the Lead API twenty-four hours a day, seven days a week. If a submission occurs outside of the Fedwire Funds Service operating hours, Lead will wait until Fedwire opens before submitting those transfers for processing. ### **Outgoing Wires** Lead’s wire submission cutoff time is **4:00 p.m. CT**, Monday through Friday. Outgoing wire transactions submitted after this cutoff will be processed on the next business day. For example, an outgoing wire created at **4:05 p.m. CT on Monday** will be processed on Tuesday. | Submission window | Description | Processing | | - | - | - | | 8:00 PM CT (prior evening) – 4:00 PM CT on a business day | Fedwire is open. Wires are submitted as soon as processing is complete. | Same business day | | 4:00 PM CT – 8:00 PM CT on a business day | Past Lead's submission cutoff. Wires are accepted and queued until the Fedwire window reopens at 8:00 PM CT. | Next business day | | Friday 8:00 PM CT – Sunday 8:00 PM CT | Fedwire is closed for the weekend. Wires are accepted and queued until the window reopens Sunday at 8:00 PM CT. | Next business day | | 8:00 PM CT (evening before a Federal Reserve holiday) – 8:00 PM CT (day of holiday) | Fedwire is closed for the holiday. Wires are accepted and queued until the window reopens. | Next business day | ### Incoming Wires Lead receives and posts incoming wires automatically. No action is required. Wires arrive any time the Fedwire window is open. | Receipt window | Description | Processing | | - | - | - | | 8:00 PM CT (prior evening) – 6:00 PM CT on a business day | Fedwire is open. Incoming wires are received and posted automatically. | Same business day | | 6:00 PM CT – 8:00 PM CT on a business day | Fedwire is closed. No wires are received during this window. | — | | Friday 6:00 PM CT – Sunday 8:00 PM CT | Fedwire is closed for the weekend. No wires are received until the window reopens. | — | | Federal Reserve holiday | Fedwire is closed. No wires are received until the window reopens at 8:00 PM CT. | — | # Receiving & Returning Wires Source: https://docs.lead.bank/products/wire/receiving-and-returning-wires Configure your system to receive incoming wires and initiate returns against them. Receive incoming wire transfers and return them when necessary: statuses, webhooks, and creditor name match enforcement. ## Receiving Wires Receiving an incoming wire creates a new `wire` object with an incoming direction. Incoming wires are received and posted automatically. No action is required to receive a wire. ### Statuses Incoming `wire` objects have two potential statuses during their lifecycle, both of which trigger a webhook. | Status | Description | Webhook | | - | - | - | | `posted` | Funds have been credited to the account. | Yes | | `rejected` | Incoming wire was rejected. See the `rejection` object for details. | Yes | ### Webhook Events | Event | What happened | Recommended action | | - | - | - | | `wire.posted` | Funds have been credited to the account. | Notify your customer that their funds are available. | | `wire.rejected` | Incoming wire was rejected. | See the `rejection` object for details and notify your customer. | ## Creditor Name Match Lead validates all incoming wires against the receiving account's legal name. If the creditor name on the wire does not closely match the account's legal entity name, the wire is rejected with a `creditor_name_mismatch` rejection reason. ### How Matching Works Matching is approximate to account for minor variations in formatting and spelling: * **Individuals:** approximate match on first and last name * **Businesses:** approximate match on legal name or DBA ### Examples **Approved** | Name on wire | Account name | | - | - | | thomas thompson | THOMAS THOMPSON RABINE | | triangle lab | TRIANGLE LABORATORIES INC | | Justin hurwanti | JUSTIN NURWANTI | **Rejected** | Name on wire | Account name | | - | - | | adl febriana | Adi Daniel | | james har | Mohamed Haruna | | John Smith | ABC Global Logistics Commodities | To avoid rejections, instruct your counterparties to use the receiving entity's name as the creditor name when sending wires. ## Sending Returns You can return a posted incoming wire using `POST /v1/wires/{wire_id}/return`. A return creates a new `wire` object with `type: return` and follows the same outgoing status lifecycle. Additionally, the active `return_request` sub-object of the original payment, if exists, moves into `accepted` status automatically. ### Endpoints | Endpoint | Description | | - | - | | `POST /v1/wires/{wire_id}/return` | Return a posted incoming wire | ### Request Requirements | Field | Requirement | | - | - | | `return_code` | Return reason code for the return. See [Rejection and Return Codes]() for available values. | | `return_additional_information` | Required when `return_code` is `NARR`. Free-form explanation, up to 105 characters. | ```json theme={null} { "return_code": "MS02" } ``` When using `NARR`, include a free-form explanation: ```json theme={null} { "return_code": "NARR", "return_additional_information": "Wire received in error, please return funds to originator." } ``` ### Webhook Events | Event | What happened | Recommended action | | - | - | - | | `wire.under_review` | Return wire flagged for manual review. | Notify the counterparty of the delay. The return wire will proceed or be rejected following review. | | `wire.posted` | Return wire has been sent. | Notify your customer and the counterparty that the funds have been returned. | | `wire.rejected` | Return wire was rejected. | Inspect the `rejection` object and contact Lead if needed. | | `wire.canceled` | Return wire was successfully canceled. | Notify your customer and the counterparty that the return has been canceled. | # Return & Rejection Codes Source: https://docs.lead.bank/products/wire/rejection-and-return-codes Details about processing or receiving wire returns. > [!NOTE] > > This page includes the full list of supported return and rejection reason codes along with their corresponding enum values and descriptions. ## Wire Returns Wire return and rejection codes indicate why a wire was returned or rejected by the receiving bank, or why Lead rejected an outbound. These ISO 20022 codes can help you understand why a wire failed and determine what follow-up actions may be needed. ## Return Codes ### For /RETURN Endpoint The following codes can be used to initiate **outgoing** wire return through `/RETURN` endpoint. | **ISO Code** | **Enum** | **Description** | | - | - | - | | `AC06` | `account_blocked` | Account specified is blocked, prohibiting posting of transactions against it. | | `AM09` | `wrong_amount` | Amount received is not the amount agreed or expected. | | `BE01` | `creditor_name_mismatch` | Identification of end customer is not consistent with associated account number, organization ID or private ID. | | `FOCR` | `honor_return_request` | Return following a cancellation request. | | `FR01` | `fraud_suspected` | Returned as a result of fraud. | | `MS02` | `creditor_request` | Reason has not been specified by end customer. | | `NARR` | `narrative` | Reason is provided as narrative information in the additional reason information. | | `RR02` | `missing_debtor_data` | Specification of the debtor’s name and/or address needed for regulatory requirements is insufficient or missing. | | `RR03` | `missing_creditor_data` | Specification of the creditor’s name and/or address needed for regulatory requirements is insufficient or missing. | ### All ISO Return Codes All possible wire return request codes you may see according to the ISO 20022 spec. | **ISO Code** | **Enum** | **Description** | | :- | :- | :- | | `AC04` | `account_closed` | Account number specified has been closed on the bank of account’s books. | | `AC06` | `account_blocked` | Account specified is blocked, prohibiting posting of transactions against it. | | `AC13` | `debtor_account_type_invalid` | Debtor account type is missing or invalid. | | `AC14` | `agent_invalid` | An agent in the payment chain is invalid. | | `AC15` | `account_details_changed` | Account details have changed. | | `AC16` | `account_sequestered` | Account is in sequestration. | | `AC17` | `account_liquidated` | Account is in liquidation. | | `AG01` | `transaction_forbidden` | Transaction forbidden on this type of account. (formerly NoAgreement) | | `AG02` | `bank_operation_code_invalid` | Bank Operation code specified in the message is not valid for receiver. | | `AM01` | `zero_amount` | Specified message amount is equal to zero. | | `AM02` | `amount_too_high` | Specific transaction/message amount is greater than allowed maximum. | | `AM03` | `currency_not_allowed` | Specified message amount is a non-processable currency outside of existing agreement. | | `AM04` | `non_sufficient_funds` | Amount of funds available to cover specified message amount is insufficient. | | `AM05` | `duplication` | Duplication | | `AM06` | `amount_too_low` | Specified transaction amount is less than agreed minimum. | | `AM07` | `amount_blocked` | Amount specified in message has been blocked by regulatory authorities. | | `AM09` | `wrong_amount` | Amount received is not the amount agreed or expected. | | `AM10` | `control_sum_invalid` | Sum of instructed amounts does not equal the control sum. | | `ARDT` | `returned_previously` | Already returned original transaction. | | `BE01` | `creditor_name_mismatch` | Identification of end customer is not consistent with associated account number, organization ID or private ID. | | `BE04` | `creditor_address_incorrect` | Specification of creditor's address, which is required for payment, is missing, invalid, or not complete. | | `BE05` | `initiating_party_unrecognized` | Party who initiated the message is not recognized by the end customer. | | `BE06` | `unknown_customer` | End customer specified is not known at associated Sort/National Bank Code or does no longer exist in the books. | | `BE07` | `debtor_address_invalid` | Specification of debtor's address, which is required for payment, is missing, invalid, or not complete. | | `BE08` | `bank_error` | Returned as a result of a bank error. | | `CN01` | `authorization_canceled` | Authorization is cancelled. | | `CNOR` | `creditor_bank_not_registered` | Creditor bank is not registered in the network. | | `CURR` | `currency_incorrect` | Currency of the payment incorrect. | | `CUST` | `customer_requested` | Cancellation requested by the Debtor. | | `DNOR` | `debtor_bank_not_registered` | Debtor bank is not registered in the network. | | `DS28` | `return_for_technical_reason` | Return following technical problems resulting in erroneous transaction. | | `DT01` | `settlement_date_invalid` | Invalid or missing settlement date. | | `ED01` | `correspondent_bank_unattainable` | Correspondent bank not possible. | | `ED03` | `balance_information_requested` | Balance of payments complementary info is requested. | | `ED05` | `settlement_failed` | Settlement of the transaction has failed. | | `EMVL` | `emv_liability_shifted` | The card payment is fraudulent and was not processed with EMV technology for an EMV card. | | `ERIN` | `eri_option_unsupported` | The Extended Remittance Information (ERI) option is not supported. | | `FF05` | `local_instrument_code_invalid` | Local instrument code is missing or invalid. | | `FOCR` | `honor_return_request` | Return following a cancellation request. | | `FR01` | `fraud_suspected` | Returned as a result of fraud. | | `FRTR` | `final_response_mandate_canceled` | Final response or tracking recalled as mandate canceled. | | `MD01` | `no_mandate` | No mandate. | | `MD02` | `missing_mandate_information` | Mandate related information data required by the scheme is missing. | | `MD06` | `end_customer_requested` | Requested by the end customer. | | `MD07` | `end_customer_deceased` | End customer is deceased. | | `MS02` | `creditor_request` | Reason has not been specified by end customer. | | `MS03` | `per_agent_request` | Reason has not been specified by agent. | | `NARR` | `narrative` | Reason is provided as narrative information in the additional reason information. | | `NOAS` | `customer_no_response` | No answer from customer. | | `NOCM` | `non_compliant` | Customer account is not compliant with regulatory requirements. | | `NOOR` | `transaction_not_found` | Original transaction never received. | | `PINL` | `pin_liability_shifted` | The card payment is fraudulent (lost and stolen fraud) and was processed as EMV transaction without PIN verification. | | `RC01` | `routing_number_format_incorrect` | Bank Identifier code specified in the message has an incorrect format. (formerly IncorrectFormatForRoutingCode) | | `RC07` | `creditor_bic_incorrect` | Incorrect routing number of the beneficiary bank. | | `RF01` | `transaction_reference_not_unique` | Transaction reference is not unique within the message. | | `RR01` | `missing_debtor_account_number` | Specification of the debtor’s account or unique identification needed for reasons of regulatory requirements is insufficient or missing. | | `RR02` | `missing_debtor_data` | Specification of the debtor’s name and/or address needed for regulatory requirements is insufficient or missing. | | `RR03` | `missing_creditor_data` | Specification of the creditor’s name and/or address needed for regulatory requirements is insufficient or missing. | | `RR04` | `regulatory_reason` | Regulatory reason. | | `RUTA` | `returned_unable_to_apply` | Return following investigation request and no remediation possible. | | `SL01` | `debtor_agent_specific_service` | Due to specific service offered by the Debtor Agent. | | `SL02` | `creditor_agent_specific_service` | Due to specific service offered by the Creditor Agent. | | `SL11` | `creditor_not_whitelisted_by_debtor` | Whitelisting service offered by the Debtor Agent; Debtor has not included the Creditor on its “Whitelist.” | | `SL12` | `creditor_blacklisted_by_debtor` | Blacklisting service offered by the Debtor Agent; Debtor included the Creditor on his “Blacklist.” | | `SL13` | `direct_debit_count_exceeded` | Due to Maximum allowed Direct Debit Transactions per period service offered by the Debtor Agent. | | `SL14` | `direct_debit_limit_exceeded` | Due to Maximum allowed Direct Debit Transaction amount service offered by the Debtor Agent. | | `SP01` | `payment_stopped` | Payment is stopped by account holder. | | `SP02` | `payment_stopped_previously` | Previously stopped by means of a stop payment advise. | | `SVNR` | `service_not_rendered` | Service not rendered. | | `TM01` | `untimely_transaction` | Associated message was received after agreed processing cut-off time. | | `TRAC` | `removed_from_tracking` | Return following direct debit being removed from tracking process. | | `UPAY` | `undue_payment` | Undue payment. | ## Rejection Codes ### Incoming Wires Possible rejection codes Lead may use to reject an incoming wire. | **ISO Code** | **Enum** | **Description** | | - | - | - | | - | `creditor_name_mismatch` | The creditor name on the incoming wire does not closely match the account's legal entity name. | | `AC01` | `account_number_incorrect` | Format of the account number specified is not correct. | | `AC03` | `creditor_account_number_invalid` | Creditor account number invalid / missing OR Wrong IBAN in SCT. | | `AC04` | `account_closed` | Account number specified has been closed on the bank of account’s books. | | `AC06` | `account_blocked` | Account specified is blocked, prohibiting posting of transactions against it. | | `AM07` | `amount_blocked` | Amount specified in message has been blocked by regulatory authorities. | | `BE01` | `creditor_name_mismatch` | Identification of end customer is not consistent with associated account number, organization ID or private ID. | | `BE04` | `creditor_address_incorrect` | Specification of creditor's address, which is required for payment, is missing, invalid, or not complete. | | `BE07` | `debtor_address_invalid` | Specification of debtor's address, which is required for payment, is missing, invalid, or not complete. | | `FOCR` | `honor_return_request` | Return following a cancellation request. | | `MS02` | `creditor_request` | Reason has not been specified by end customer. | | `MS03` | `per_agent_request` | Possible reasons including, but not limited to: - wire transactions related to prohibited countries or prohibited parties - invalid formatting Contact Lead's wire team if you have further questions. | | `NARR` | `narrative` | Reason is provided as narrative information in the additional reason information. | | `RC01` | `routing_number_format_incorrect` | Bank Identifier code specified in the message has an incorrect format. (formerly IncorrectFormatForRoutingCode) | ### Outgoing Wires Possible rejection codes Lead may use to reject an outgoing wire. | **ISO Code** | **Enum** | **Description** | | - | - | - | | `AM04` | `non_sufficient_funds` | Amount of funds available to cover specified message amount is insufficient. | | `AM07` | `amount_blocked` | Amount specified in message has been blocked by regulatory authorities. | | `BE04` | `creditor_address_incorrect` | Specification of creditor's address, which is required for payment, is missing, invalid, or not complete. Outgoing wires must have a full physical address for the creditor. | | `BE07` | `debtor_address_invalid` | Specification of debtor's address, which is required for payment, is missing, invalid, or not complete. | | `MS03` | `per_agent_request` | Possible reasons including, but not limited to: - wire transactions related to prohibited countries or prohibited parties - invalid formatting Contact Lead's wire team if you have further questions. | | `NARR` | `narrative` | Reason is provided as narrative information in the additional reason information. | | - | `aggregate_limit_exceeded` | The wire transaction exceeds your set aggregate daily or monthly limits. | # Return Requests Source: https://docs.lead.bank/products/wire/return-requests Configure your system to receive and send wire return requests. ## Overview Wire return requests allow you to request the return of funds for a previously sent wire. Return requests are always associated with a previous wire. There are two distinct flows: * Receiving a return request for an incoming wire * Sending a return request for an outgoing wire > [!TIP] > > A return request does not move funds and its status does not guarantee that a return will happen. Funds are only moved when an actual return wire is initiated by you or the counterparty. ## Return Request Object Return requests are represented as sub-objects within the wire resource. ```json theme={null} "return_requests": [{ "created_at": "ISO-8601", "deadline": "ISO-8601", "status": "enum(response_needed|pending|accepted|rejected)", "reason": "enum", "details": "string", "resolution": { "resolved_at": "ISO-8601", "resolved_by": "enum(client|lead|counterparty)", "rejection_reason": "enum", "rejection_details": "string" } }] ``` ## Receiving Return Requests The counterparty financial institution may send a return request if they want a previously sent wire to be returned. Return requests are included as sub-objects within the wire object. * A wire may have multiple return requests over time. * Only one incoming return request may be active and can be responded to at a time. Additional incoming return requests received while one is in `response_needed` will be automatically rejected. * You are responsible for reviewing and responding to each request. ### Incoming Return Request Statuses The lifecycle of an incoming `return_request` sub-object begins after the original wire reaches `posted` status. The only incoming `return_request` status that triggers an event is `response_needed`. | **Status** | **Description** | **Webhook** | | :- | :- | :- | | `response_needed` | You received an incoming return request that requires a response from you. | Yes | | `accepted` | You accepted the incoming return request by initiating an outgoing return | No | | `rejected` | You rejected the incoming return request and provided a reason why. | No | ### Key Behavior Accepting a Return Request * Use the [return a wire](https://docs.lead.bank/api-reference/endpoint/wire/return-a-wire-v1) endpoint to accept the return request. You may return the full or partial amount. * The return request is considered accepted once the return wire is submitted Rejecting a Return Request * Done via a dedicated [endpoint](https://docs.lead.bank/api-reference/endpoint/wire/return-a-wire-v1) * No funds are moved Response Deadline * If no response is provided within 10 business days, the return request is automatically rejected ### Events The `return_request_response_needed` event indicates that a new return request has been received which requires your response and a potential return of funds as soon as possible. Listening to this event and taking action is required. | **Event** | **Description** | **Your Action** | Webhook | | :- | :- | :- | - | | `wire.return_request_response_needed` | You received an incoming return request that requires a response from you. | Begin review and respond before the deadline. | Yes | ### Endpoints | **Endpoint** | **Description** | | :- | :- | | `POST /wires/{wire_id}/return` | Accept the return request by initiating a return wire (full or partial). | | `POST /wires/{wire_id}/reject_return_request` | Reject the active return request associated with the wire. | ## Sending Return Requests You can send a return request when you previously sent a wire and need to recover the funds. Sending a return request: * creates a new return request sub-object in the pending state within the wire. * sends the return request to the counterparty financial institution. * does not guarantee that funds will be returned. You may send additional return requests to follow up or provide more context before the original request reaches a terminal state. As a result, a wire may have multiple active outgoing return requests at the same time. ### Statuses | **Status** | **Description** | **Webhook** | | :- | :- | :- | | `pending` | The return request has been sent and is awaiting a response. | No | | `accepted` | The counterparty accepted the request. | Yes | | `rejected` | The counterparty rejected the request. | Yes | ### Key Behavior * Return requests are non-binding * The counterparty is not obligated to return funds. * Return requests and returns are not strictly coupled * The counterparty may return funds without accepting the return request. * The counterparty may accept the return request without actually returning funds. * If accepted: * The counterparty may initiate a return wire. * The returned amount may be full or partial. * If rejected: * The counterparty rejects the return request, indicating they do not intend to return funds. * If no response is received: * The return request may remain pending indefinitely. ### Events | **Event** | **Description** | **Your Action** | Webhook | | :- | :- | :- | - | | `wire.return_request_pending` | The outgoing return request is created and is pending a response from the counterparty. | No actions required. | No | | `wire.return_request_status_updated` | The status of an outgoing return request has changed. | (Optional) Notify your customer of the outcome. | Yes | ### Endpoints | **Endpoint** | **Description** | | :- | :- | | `POST /wires/{wire_id}/request_return` | Send a return request for a previously posted outgoing wire. | ## Integration Best Practices * Track returns based on actual return wires * Do not rely on return request status to determine if funds have been returned as they are not coupled. * Always monitor incoming wires to confirm settlement. * Respond within the required timeframe * Incoming return requests must be resolved by the 10th business day. * If no response is provided, the request is automatically rejected. * Handle non-deterministic outcomes * Accepted requests may not result in a return. * Rejected requests may still result in a return. * Pending requests may remain unresolved. * Design for partial returns * Returned funds may be full or partial. * Account for multiple requests * Outgoing: multiple return requests may be active at once. * Incoming: only one request can be actively responded to at a time. # Sandbox Testing Source: https://docs.lead.bank/products/wire/sandbox-testing Test Wire Transactions In Sandbox, wires do not connect to Fedwire and no real funds move. Statuses, webhooks, and validations behave the same as production. Use the simulation endpoints below to control wire lifecycle events and test your integration end to end. ## Simulation Endpoints | Endpoint | Description | | - | - | | `POST /v1/simulate/wires/incoming` | Simulate an incoming wire landing on one of your account numbers | | `POST /v1/simulate/wires/{wire_id}/advance` | Advance an outgoing wire to its next status | | `POST /v1/simulate/wires/{wire_id}/incoming_return` | Simulate the counterparty returning a wire you sent | | `POST /v1/simulate/wires/{wire_id}/incoming_return_request` | Simulate a return request arriving from the counterparty | | `POST /v1/simulate/wires/{wire_id}/incoming_return_request_acceptance` | Simulate the counterparty accepting a return request you sent | | `POST /v1/simulate/wires/{wire_id}/incoming_return_request_rejection` | Simulate the counterparty rejecting a return request you sent | ## Test an Outgoing Wire Create an outgoing wire using `POST /v1/wires`. The wire starts in `created` status. Each call to the advance endpoint moves the wire forward one status, triggering the corresponding webhook. | Call | Status transition | | - | - | | 1 | `created` → `scheduled` | | 2 | `scheduled` → `processing` | | 3 | `processing` → `posted` | The advance endpoint also applies to cancellations. If a wire is in `cancel_pending`, one advance call moves it to `canceled`. Manual review is not simulated in Sandbox. ## Test an Incoming Wire Use `POST /v1/simulate/wires/incoming` to simulate a wire arriving on one of your account numbers. Specify the receiving account number, amount, and debtor details. ```json theme={null} { "amount": 500000, "creditor_account_number_id": "account_number_id", "debtor": { "name": "Alex Smith", "account_identifier": { "type": "account_number", "value": "9900000001" } }, "debtor_agent": { "routing_number": "021000021" } } ``` The simulated wire is created in `posted` status. A `wire.posted` webhook fires on receipt. ## Test Returns ### Returning an Incoming Wire To test returning a wire you received: 1. Simulate an incoming wire using `POST /v1/simulate/wires/incoming`. 2. Initiate a return using `POST /v1/wires/{wire_id}/return`. This creates a new outgoing wire. 3. Advance the return wire to `posted` using the advance endpoint. ### Simulating a Return on a Wire You Sent Use `POST /v1/simulate/wires/{wire_id}/incoming_return` to simulate the counterparty returning a wire you sent. Provide a `return_code` and, if using `NARR`, a `return_additional_information` value. ## Test Return Requests ### Simulating an Incoming Return Request Use `POST /v1/simulate/wires/{wire_id}/incoming_return_request` to simulate the counterparty requesting the return of a wire you received. Respond through the API by either returning the funds (`POST /v1/wires/{wire_id}/return`) or rejecting the request (`POST /v1/wires/{wire_id}/reject_return_request`). ### Simulating a Response to a Return Request You Sent After sending a return request with `POST /v1/wires/{wire_id}/request_return`, simulate how the counterparty responds: * **Accepted:** `POST /v1/simulate/wires/{wire_id}/incoming_return_request_acceptance` - the counterparty accepts and returns the funds. * **Rejected:** `POST /v1/simulate/wires/{wire_id}/incoming_return_request_rejection` - the counterparty declines the request. # Sending Wires Source: https://docs.lead.bank/products/wire/sending-wires Send outgoing domestic and USD international wires: request requirements, statuses, and webhooks. Send outgoing wire transfers: request requirements, statuses, and webhooks. Wires sent over Fedwire are same-day and irrevocable. Once a wire is posted, the only way to recover funds is by submitting a return request. ## Prerequisites * Your token requires the `wire/read_write` scope. * The sending account number must be active, and its outgoing wire controls must permit the counterparty. By default, all counterparties are permitted. * Account-level wire limits must be configured with Lead before going live. Contact your Technical Account Manager to set these up. ## Endpoints | Endpoint | Description | | - | - | | `POST /v1/wires` | Create an outgoing wire. Requires `Idempotency-Key` header. | | `POST /v1/wires/{wire_id}/cancel` | Cancel a wire | ## Request Requirements | Field | Requirement | | - | - | | `account_number_id` | The account number from which the wire will be debited. | | `amount` | Amount in cents. | | `currency_code` | ISO 4217 currency code (e.g. `USD`). | | `creditor_agent` | The receiving financial institution. Provide `routing_number` for domestic wires or `business_identifier_code` for international wires. | | `creditor` | The beneficiary. Requires `name`, `account_identifier`, and `address`. | | `remittance_details` | Remittance information. `transfer_purpose` is required. | See Create a Wire for the full schema and The Wire Object for every response field. ```json theme={null} { "account_number_id": "account_number_xyz", "amount": 100000, "currency_code": "USD", "creditor_agent": { "routing_number": "021000021" }, "creditor": { "name": "Alex Smith", "account_identifier": { "type": "account_number", "value": "9900000001" }, "address": { "line_one": "123 Main St", "line_two": "New York, NY 10001" } }, "remittance_details": { "transfer_purpose": { "type": "invoice_payment" } } } ``` A successful response returns the wire object in `created` status. ## Statuses | Status | Description | Cancellable | Webhook | | - | - | - | - | | `created` | Wire object has been created and is pending processing. | Yes | No | | `under_review` | Wire has been flagged for manual review by Lead. | Yes | Yes | | `scheduled` | Wire is scheduled to be sent. | Yes | Yes | | `processing` | Wire is being submitted to Fedwire. | No | Yes | | `posted` | Wire has been sent over Fedwire. | No | Yes | | `rejected` | Wire was rejected. See the `rejection` object for details. | No | Yes | | `cancel_pending` | A cancellation has been requested and is pending confirmation. | No | No | | `canceled` | Wire was successfully canceled. | No | Yes | ## Webhook Events | Event | What happened | Recommended action | | - | - | - | | `wire.under_review` | Wire flagged for manual review. | Notify your customer of the delay. The wire will proceed or be rejected following review. | | `wire.posted` | Wire debited from the account and sent. | Notify your customer the payment has been sent. | | `wire.rejected` | Wire was rejected. | Inspect the `rejection` object for the reason and resubmit if appropriate. | | `wire.canceled` | Wire was successfully canceled. | Notify your customer the payment was not sent. | # Wire Statuses Source: https://docs.lead.bank/products/wire/statuses Description of wire statuses and transitions. ## Incoming Wire ![Incoming Wire Status](https://mintcdn.com/lead/0UJlPqWdLCOMqs06/images/incoming-wire-status.png?fit=max\&auto=format\&n=0UJlPqWdLCOMqs06\&q=85\&s=9face3acb4e3fb265c1300e6c4c0553e) ## Outgoing Wire ![Outgoing Wire Status](https://mintcdn.com/lead/0UJlPqWdLCOMqs06/images/outgoing-wire-status.png?fit=max\&auto=format\&n=0UJlPqWdLCOMqs06\&q=85\&s=76a28721f39ba0477187bd0c448aebbe) # Wires API V2 Migration Guide Source: https://docs.lead.bank/products/wire/v2-migration Understand what changed in Wires API V2, how to update your integration, and what you need to complete before the migration deadline. Lead is migrating the Wire API from V1 to V2. All partners must migrate to V2 before Lead's migration deadline. V1 will be deprecated after the migration window closes. This guide describes what changed, what you need to update, and the timeline for completing your migration. This page is updated when additional changes occur, with those changes recorded in the Changelog at the top of the page. > [!WARNING] > > **This guide will be updated as decisions are finalized.** > [accordion] Changelog > > | Date | Change | > | - | - | > | July 9, 2026 | Initial version published. | > | July 15, 2026 | Added summary of breaking changes | > | September 2, 2026 | Updated launch and migration timeline following the Federal Reserve’s decision to reschedule its November 2026 Fedwire release | > | October 7, 2026 | Removed the Q4 2026 migration deadline. Migration is not required in Q4 2026; a new timeline will be published. | ## Why We're Moving to Wires V2 Wires V2 prepares our API for upcoming Fedwire ISO 20022 requirements while also introducing several improvements to the wires experience. The primary breaking change is a new hybrid address format. V2 replaces the fully unstructured V1 address with an ISO-compatible address object that requires `country` and `town_name`, while still allowing up to two free-form address lines. V2 also introduces stricter validation for rail-bound text fields. Since these changes require a new API version, we are also including several related improvements in the same migration, including corridor classification, consolidated routing identifiers, and enum-based return and rejection reasons. Although the Fedwire release has been rescheduled from November 2026 to November 2027, Lead is still moving forward with Wires V2 so partners can adopt these improvements now and be prepared for the future Fedwire requirements. ## Timeline | Date | Milestone | Required Action | | :- | :- | :- | | To be announced | Wire V2 available in Sandbox | Begin testing against V2 Sandbox APIs and webhooks. Start planning your integration now. | | To be announced | Wire V2 available in Production | Partners may begin migrating from V1 to V2 in production. We recommend migrating as soon as V2 is available in production to avoid disrupting wire processing. | | To be announced | Migration deadline | Complete your migration from V1 to V2 by this date. Migration is not required in Q4 2026. | | November 16, 2027 | Fedwire ISO 20022 v2.0 takes effect | Fedwire removes fully unstructured address support. All wires must be V2-compatible by this point. | > [!NOTE] > > The detailed migration runbook including the per-program cutover sequence, V1 deprecation timing, and maintenance windows will be shared as the migration plan is finalized. Contact your TAM with questions about your specific timeline. # Summary of Breaking Changes | **Area** | **v1** | **v2** | | :- | :- | :- | | Create wire | No `corridor_type` | `corridor_type` **required** | | Routing number | `creditor_agent.routing_number` | Removed — use `creditor_agent.local_routing_identifier.value` | | BIC field | Optional for any wire | Required for international, rejected for domestic | | Creditor address | 3 unstructured lines; `line_one` required | `town_name` + `country` required; `line_three` removed | | Wire return | Field `return_code` with ISO 20022 codes | Field `reason` with human-readable values | ## **1. Update Wire Creation (**`POST /v2/wires`**)** Several fields in the request body have changed. The top-level diff: ```text theme={null} { "account_number_id": "acn_123", "amount": 100000, "currency_code": "USD", + "corridor_type": "domestic", // [!code ++] "creditor_agent": { ... }, "creditor": { ... }, "remittance_details": { ... } } ``` #### **1a.** `corridor_type `**Is Now Required** Set to `"domestic"` or `"international"`. This value drives the validation rules for several other fields below. ```text theme={null} { "corridor_type": "international" } ``` #### **1b. Routing Number Moved To** `local_routing_identifier.value` `creditor_agent.routing_number` no longer exists in v2. Pass the 9-digit ABA routing number through `creditor_agent.local_routing_identifier.value` instead. This field is **required** when `corridor_type` is `"domestic"`. ```text highlight={2} theme={null} "creditor_agent": { - "routing_number": "021000021" // [!code --] + "local_routing_identifier": { // [!code ++] + "value": "021000021" // [!code ++] + } // [!code ++] } ``` The same applies to `instructed_agent` if you use it. #### **1c.** `business_identifier_code `**(BIC) Is Now Corridor-type Conditional** In v1, BIC was informally required for international wires. In v2 this is enforced: * `corridor_type: "international"` → `business_identifier_code` **required** * `corridor_type: "domestic"` → `business_identifier_code` **not accepted** ```text theme={null} // domestic — use local_routing_identifier, no BIC creditor_agent: { local_routing_identifier: { value: '021000021' } } // international — use BIC, no routing number creditor_agent: { business_identifier_code: 'CHASUS33' } ``` #### **1d.** `creditor.address `**Is Restructured** v2 adopts an ISO 20022 hybrid address format. `line_three` is removed and two new **required** fields are added: `town_name` and `country`. | **Field** | **v1** | **v2** | | :- | :- | :- | | `line_one` | Required, max 35 chars | Optional, max 70 chars | | `line_two` | Optional, max 35 chars | Optional, max 70 chars | | `line_three` | Optional, max 35 chars | **Removed** | | `town_name` | — | **Required**, max 35 chars | | `country_sub_division` | — | Optional, max 35 chars | | `post_code` | — | Optional, max 16 chars | | `country` | — | **Required**, ISO 3166-1 alpha-2 (e.g. `"US"`) | ```text theme={null} "address": { + "line_one": "123 Main St", + "line_two": "Suite 400", "line_three": "IL, USA", // [!code --] + "town_name": "Springfield", // [!code ++] + "country_sub_division": "IL", // [!code ++] + "post_code": "62701", // [!code ++] + "country": "US" } ``` > If you were putting city/state/country into `line_two` or `line_three`, split those values into the new structured fields. ### **1e. Read-only Fields Removed From Request Schemas** In v1, `payment_identifiers` and `remittance_details` included several `readOnly` fields that were silently ignored in requests. In v2 these are absent from the request schema entirely — sending them will cause an error. If your code serializes a full wire object back into a create request, strip these fields first. `payment_identifiers `**— only** `end_to_end_identification `**is accepted; remove:** * `message_identification`, `uetr`, `instruction_identification`, `return_identification` `remittance_details `**— only** `message_to_creditor `**and** `transfer_purpose `**are accepted; remove:** * `payment_notification`, `message_to_receiving_fi`, `fi_to_fi_message` ## **2. Update Wire Return Reasons** `POST /v2/wires/{id}/return` renames `return_code` to `reason` and replaces ISO 20022 codes with human-readable strings. **v1 request:** ```text theme={null} { "return_code": "AC06" // [!code --] } ``` **v2 request:** ```text theme={null} { "reason": "account_blocked" // [!code ++] } ``` ### **Full Mapping** | **v1** `return_code` | **v2** `reason` | | :- | :- | | `AC06` | `account_blocked` | | `AM09` | `wrong_amount` | | `BE01` | `creditor_name_mismatch` | | `FOCR` | `honor_return_request` | | `FR01` | `fraud_suspected` | | `MS02` | `missing_debtor_data` | | `RR02` | `creditor_request` | | `NARR` | `narrative` | | `RR03` | `missing_creditor_data` | ```text theme={null} // v1 await client.post(`/v1/wires/${wireId}/return`, { return_code: 'AC06', return_additional_information: 'Account is frozen', }); // v2 await client.post(`/v2/wires/${wireId}/return`, { reason: 'account_blocked', return_additional_information: 'Account is frozen', }); ``` ## **3. Handle New Response Fields** v2 wire responses include new fields. You don't have to use them, but you should not break if they appear. ```text theme={null} const wire = await getWire(wireId); // New in v2 — safe to use, ignore if not needed wire.corridor_type // "domestic" | "international" wire.core_transaction_ids // ["ctx_abc", "ctx_def"] wire.initiating_party // object — the party that initiated the wire ``` # Detailed Changes ## Wire V2 Object The V2 wire object keeps the overall V1 shape and field names, with a focused set of ISO-driven additions and changes. The most significant differences from V1 are the hybrid address model, the consolidation of routing numbers into `local_routing_identifier`, the new `corridor_type` and `initiating_party` fields, and the move from raw ISO codes to normalized enums on return reasons. ### Key Changes vs. V1 | Field | V1 | V2 | | :- | :- | :- | | `corridor_type` | Not present | New -`domestic` or `international`. For outgoing wires, set from the `POST /v1/wires` request; for incoming wires, derived from the payload and agent chain. | | `status` | Full status set | No change for now. See [Statuses](#statuses) for planned 2027 deprecations. | | `*_agent.local_routing_identifier` | Not present | New - `{ scheme, value }`, replaces `routing_number`. For domestic wires, `scheme` is `USABA` and `value` is the 9-digit ABA. Applies to `debtor_agent`, `creditor_agent`, `instructing_agent`, `instructed_agent`, and charging agents. | | `*_agent.routing_number` | Present on all agents | Removed; replaced by `local_routing_identifier`. | | `initiating_party` | Not present | New - standard wire-party object. On outgoing wires, `initiating_party.name` is auto-populated with the partner's name. On incoming wires, populated from the ISO payload when available. | | `ultimate_debtor` | Response only | No change. Not settable on create; populated on incoming wires when present. | | `*.address` (response) | Unstructured (`line_one`–`line_three`) | No change. Response keeps the existing shape, including `line_three`, to support legacy V1 wire data. | | `remittance_details.transfer_purpose.type` | Outgoing purpose values only | Enum expanded to add incoming transfer-purpose values previously omitted to avoid a breaking change. | | `return.code` | Raw ISO code | Removed. Use `return.reason` instead. | | `return.reason` | Enum (mapped ISO reasons) | Full ISO reason set, plus a new `other` value for unmapped incoming codes. When `other`, the raw ISO code is placed in `return.additional_information` as `"ISO Code: ;
"`. | | `rejection.reason` | Enum | Reason set revised for incoming and outgoing rejections. | | `return_requests` | Not present in V1 today; being added to V1 before the V2 rollout | No V2-specific change. | ## Statuses Wire statuses are unchanged from V1 for this migration. The full status set (`created`, `scheduled`, `processing`, `posted`, `under_review`, `rejected`, `canceled`, `cancel_pending`) continues to be returned as it is today. > [!TIP] > > **Planned for 2027** > > The wire status lifecycle changes are deferred until after the V2 rollout. Partners will receive at least three months' notice before any status is removed. No action is required for the V2 migration itself. The planned changes differ by direction: * **Outgoing wires:** `scheduled`, `processing`, and `cancel_pending` will be deprecated, leaving the lifecycle `created` → `under_review` → `posted` / `rejected` / `canceled`. * **Incoming wires:** `under_review` will become an active status (and the `wire.under_review` webhook will begin firing for incoming wires), leaving the lifecycle `under_review` → `posted` / `rejected`. ## Example `Wire V2` Object ```json theme={null} { "id": "wire_xyz123", "account_number_id": "account_number_xyz123", "created_at": "2026-05-25T10:00:00Z", "updated_at": "2026-05-25T10:05:00Z", "settlement_date": "2026-05-25", "direction": "outgoing", "type": "transfer", "corridor_type": "domestic", "status": "posted", "amounts": { "settlement_amount": 10000, "settlement_currency_code": "USD", "instructed_amount": 10000, "instructed_currency_code": "USD", "instructed_to_settlement_exchange_rate": "1" }, "debtor": { "name": "Alex Smith", "account_identifier": { "type": "account_number", "value": "..." }, "address": { "line_one": "string | null", "line_two": "string | null", "line_three": "string | null", "town_name": "string | null", "country_sub_division": "string | null", "post_code": "string | null", "country": "string | null" } }, "debtor_agent": { "business_identifier_code": "string | null", "name": "string | null", "local_routing_identifier": { "scheme": "USABA", "value": "021000021" }, "address": { "...": "..." } }, "instructing_agent": { "name": "Lead Bank", "business_identifier_code": "string | null", "local_routing_identifier": { "scheme": "USABA", "value": "101019644" } }, "instructed_agent": { "name": "JPMorgan Chase Bank", "business_identifier_code": "CHASUS33", "local_routing_identifier": { "scheme": "USABA", "value": "021000021" } }, "creditor_agent": { "business_identifier_code": "CHASUS33", "name": "JPMorgan Chase Bank", "local_routing_identifier": { "scheme": "USABA", "value": "021000021" }, "address": { "...": "..." } }, "creditor": { "name": "Example Beneficiary Inc.", "account_identifier": { "type": "account_number", "value": "..." }, "address": { "line_one": "123 Main St", "line_two": "Suite 100", "line_three": null, "town_name": "Kansas City", "country_sub_division": "MO", "post_code": "64105", "country": "US" } }, "initiating_party": { "name": "Your Company Name", "account_identifier": { "type": "enum", "value": "string" }, "address": { "...": "..." } }, "ultimate_debtor": { "name": "John Smith" }, "ultimate_creditor": {}, "other_agents": { "previous_instructing_agent_one": {}, "previous_instructing_agent_two": {}, "previous_instructing_agent_three": {}, "intermediary_agent_one": {}, "intermediary_agent_two": {}, "intermediary_agent_three": {} }, "payment_identifiers": { "message_identification": "string | null", "end_to_end_identification": "string | null", "uetr": "string | null", "instruction_identification": "string | null", "return_identification": "string | null" }, "remittance_details": { "payment_notification": "string | null", "message_to_creditor": "string | null", "message_to_receiving_fi": "string | null", "fi_to_fi_message": "string | null", "transfer_purpose": { "type": "enum", "other_details": "string | null" } }, "charges": { "charge_bearer": "enum | null", "breakdown": [ { "amount": "string", "currency_code": "string", "charging_agent": {} } ] }, "related_wires": { "original_wire_id": "wire_xyz321 | null", "return_wire_ids": ["wire_xyz456"] }, "return_requests": [ { "status": "response_needed", "reason": "customer_requested", "details": "ISO Code: CUST; Beneficiary has not received funds", "deadline": "2026-06-10T23:30:00-04:00", "resolution": { "resolved_at": null, "resolved_by": null, "rejection_reason": null, "rejection_details": null }, "created_at": "2026-05-26T09:00:00Z" } ], "return": { "reason": "enum", "additional_information": "string | null" }, "rejection": { "reason": "enum", "additional_information": "string | null", "message_identification": "string | null" }, "metadata": {} } ``` ## Detailed API Changes by Endpoint **Create a Wire:** `POST /v2/wires` | Field | V1 | V2 | | :- | :- | :- | | URL path | `POST /v1/wires` | `POST /v2/wires` | | `corridor_type` | Not present | New required enum - `domestic` or `international`. Determines which `creditor_agent` routing fields are required. | | `creditor_agent.routing_number` | 9-digit ABA | Removed; replaced by `creditor_agent.local_routing_identifier.value`. Required when `corridor_type=domestic`. Scheme is auto-populated by Lead. | | `creditor_agent.business_identifier_code` | Required for international wires | Still required for international wires; now keyed to `corridor_type=international`. Not accepted when `corridor_type=domestic`. | | `instructed_agent.routing_number` | Optional | Removed; replaced by `instructed_agent.local_routing_identifier.value`. | | `creditor.address` | `line_one`, `line_two`, `line_three` (unstructured) | Hybrid address. `line_three` removed. `line_one` and `line_two` now optional (max 70 chars each). | | `creditor.address.town_name` | Not present | New - required (max 35 chars). | | `creditor.address.country` | Not present | New - required (ISO 3166-1 alpha-2, uppercase). | | `creditor.address.country_sub_division` | Not present | New - optional. | | `creditor.address.post_code` | Not present | New - optional. | | Text field validations | Standard | New ISO character-set validations on rail-bound text fields. CR, LF, Tab, and whitespace-only values are rejected. | | Response | WireV1 | WireV2 | **V2 Request Example** ```json theme={null} { "account_number_id": "account_number_xyz123", "corridor_type": "domestic", "amount": 10000, "currency_code": "USD", "creditor_agent": { "local_routing_identifier": { "value": "021000021" } }, "instructed_agent": { "business_identifier_code": "BOFAUS3N", "local_routing_identifier": { "value": "026009593" } }, "creditor": { "name": "Example Beneficiary Inc.", "account_identifier": { "type": "account_number", "value": "GB29NWBK60161331926819" }, "address": { "line_one": "123 Main St", "line_two": "Suite 100", "town_name": "Kansas City", "country_sub_division": "MO", "post_code": "64105", "country": "US" } }, "remittance_details": { "message_to_creditor": "Payment for invoice 12345", "transfer_purpose": { "type": "enum", "other_details": "string" } }, "payment_identifiers": { "end_to_end_identification": "E2E-20260525-001" }, "metadata": { "client_reference_id": "abc123" } } ``` **List All Wires:** `GET /v2/wires` | Field | V1 | V2 | | :- | :- | :- | | URL path | `GET /v1/wires` | `GET /v2/wires` | | `corridor_type` filter | Not present | New query parameter - `domestic` or `international`. | | Other filters | `account_number_id`, `direction`, `status`, `created_at`, `limit`, `starting_after`, `ending_before` | No change. | | Response | Array of WireV1 objects | Array of WireV2 objects. | **Retrieve a Wire:** `GET /v2/wires/{id}` | Field | V1 | V2 | | :- | :- | :- | | URL path | `GET /v1/wires/{wire_id}` | `GET /v2/wires/{id}` | | Request | No change | No change. | | Response | WireV1 | WireV2. | **Update a Wire:** `PATCH /v2/wires/{id}` | Field | V1 | V2 | | :- | :- | :- | | URL path | `PATCH /v1/wires/{wire_id}` | `PATCH /v2/wires/{id}` | | Request | `metadata` only | No change. | | Response | WireV1 | WireV2. | **Cancel a Wire:** `POST /v2/wires/{id}/cancel` | Field | V1 | V2 | | :- | :- | :- | | URL path | `POST /v1/wires/{wire_id}/cancel` | `POST /v2/wires/{id}/cancel` | | Request | No change | No change. | | Response | WireV1 | WireV2. | **Return a Wire:** `POST /v2/wires/{id}/return` | Field | V1 | V2 | | :- | :- | :- | | URL path | `POST /v1/wires/{wire_id}/return` | `POST /v2/wires/{id}/return` | | Target wire | Incoming transfer wires only | May also be called on incoming return wires to support return-of-a-return. Available only after the November 16, 2027 Fedwire ISO release. | | Return reason | `return_code` - raw ISO code (e.g. `AC06`, `NARR`) | `return_code` removed. Replaced by `reason` - a normalized enum: `account_blocked`, `wrong_amount`, `creditor_name_mismatch`, `honor_return_request`, `fraud_suspected`, `creditor_request`, `narrative`, `missing_debtor_data`, `missing_creditor_data`. | | Additional information | `return_additional_information`, required when `return_code=NARR` | `return_additional_information`, required when `reason=narrative`. Max 105 chars; new ISO character-set validations applied. | | Amount | Optional (defaults to original wire amount) | No change. | | Response | WireV1 | WireV2. | **Request Return:** `POST /v2/wires/{id}/request_return` For the full request and response schema, see the [Return Requests](/products/wire/return-requests) guide. | Field | V1 | V2 | | :- | :- | :- | | URL path | `POST /v1/wires/{wire_id}/request_return` | `POST /v2/wires/{id}/request_return` | | Target wire | Transfer wires | May also be called on incoming return wires to support return-of-a-return. Available only after the November 16, 2027 Fedwire ISO release. | **Reject Return Request:** `POST /v2/wires/{id}/reject_return_request` For the full request and response schema, see the [Return Requests](/products/wire/return-requests) guide. | Field | V1 | V2 | | :- | :- | :- | | URL path | `POST /v1/wires/{wire_id}/reject_return_request` | `POST /v2/wires/{id}/reject_return_request` | | Behavior | No change | No change. | # Wire Validations & Best Practices Source: https://docs.lead.bank/products/wire/validations-and-best-practices Best practices to reduce wire validation exceptions and manual review. Best practices to reduce wire validation exceptions. ## Overview Lead applies various validation checks on all wire transactions processed through our systems. Validations fall into two categories: * **Synchronous**: The API returns an immediate error response. The wire object is not created. * **Asynchronous**: The wire is created but subsequently rejected. A `wire.rejected` webhook fires when this occurs. ## Important Validations | Validation Type | Best Practice | Synchronous Rejection | | - | - | - | | `parameters_invalid` | Ensure all parameters conform to the requirements outlined in the API specification. | Yes | | `non_sufficient_funds` | Monitor your originating account balance before initiating wires. Ensure sufficient funds are available before submitting transfers. | Yes | | `per_transaction_limit_exceeded` | Review your per-transaction limits periodically and contact Lead if your use case requires higher transaction amounts. | Yes | | `account_number_incorrect` | Ensure your account numbers are shared accurately with counterparties to prevent formatting errors on incoming wires. | No | | `aggregate_limit_exceeded` | Monitor your aggregate wire volume and review your limits with Lead periodically. | No | | `creditor_name_mismatch` | Instruct your counterparties to use the name of the receiving entity as the creditor name when sending wires to your account numbers. | No | | `creditor_address_incorrect` | Ensure that wires contain a full physical address for the creditor. | No | | `regulatory_reason` | Avoid initiating wires to prohibited countries. | No | # The Wire Object Source: https://docs.lead.bank/products/wire/wire-object Field-level reference for the Wire object across V1 and V2, including debtor/creditor details and return-request entries. ```json theme={null} { "id": "wire_xyz123", "account_id": "account_xyz123", "account_number_id": "account_number_xyz123", "created_at": "ISO-8601", "updated_at": "ISO-8601", "settlement_date": "YYYY-MM-DD", "direction": "enum(incoming|outgoing)", "type": "enum(transfer|return)", "corridor_type": "enum(domestic|international)", "status": "enum(created|scheduled|processing|posted|under_review|rejected|canceled|cancel_pending)", "amounts": { "settlement_amount": 20000, "settlement_currency_code": "USD", "instructed_amount": 15500, "instructed_currency_code": "USD", "instructed_to_settlement_exchange_rate": "1.29" }, "debtor": { "name": "Alex Smith", "account_identifier": { "type": "enum(IBAN|other)", "value": "1234567890" }, "address": { "department": "string", "sub_department": "string", "street_name": "string", "building_number": "string", "building_name": "string", "floor": "string", "post_box": "string", "room": "string", "post_code": "string", "town_name": "string", "town_location_name": "string", "district_name": "string", "country_sub_division": "string", "country": "string", "line_one": "string", "line_two": "string", "line_three": "string" } }, "debtor_agent": { "business_identifier_code": "CHASUS33", "name": "JPMorgan Chase Bank", "routing_number": "987654321", "address": { ... }, "local_routing_identifier": { "scheme": "string", "value": "string" } }, "instructing_agent": { "name": "Lead Bank", "routing_number": "123456789", "business_identifier_code": "CHASUS33" }, "instructed_agent": { "name": "JPMorgan Chase Bank", "routing_number": "987654321", "business_identifier_code": "CHASUS33" }, "creditor_agent": { "business_identifier_code": "CHASUS33", "name": "JPMorgan Chase Bank", "routing_number": "987654321", "address": { ... }, "local_routing_identifier": { "scheme": "string", "value": "string" } }, "creditor": { "name": "Alex Smith", "account_identifier": { "type": "enum(IBAN|other)", "value": "1234567890" }, "address": { ... } }, "ultimate_debtor": { "name": "string", "account_identifier": { "type": "enum(IBAN|other)", "value": "1234567890" }, "address": { ... } }, "ultimate_creditor": { "name": "string", "account_identifier": { "type": "enum(IBAN|other)", "value": "1234567890" }, "address": { ... } }, "other_agents": { "previous_instructing_agent_one": { ... }, "previous_instructing_agent_two": { ... }, "previous_instructing_agent_three": { ... }, "intermediary_agent_one": { ... }, "intermediary_agent_two": { ... }, "intermediary_agent_three": { ... } }, "payment_identifiers": { "message_identification": "20231215MMQFMP2L017726", "end_to_end_identification": "string", "uetr": "e331acb3-e23f-42f4-8815-43da484a939b", "instruction_identification": "string", "return_identification": "string" }, "remittance_details": { "payment_notification": "string", "message_to_creditor": "string", "message_to_receiving_fi": "string", "fi_to_fi_message": "string", "transfer_purpose": { "type": "enum(salary_payment|invoice_payment|gift|payment_for_goods|payment_for_services|insurance_premium_payment|interest_payment|loan|loan_repayment|account_management|cash_management_transfer|other|tax_payment|government_payment|benefits_payment|pension_payment|rent_payment|utilities_payment|education_payment|healthcare_payment|charitable_payment|refund|fee_payment|intercompany_transfer|investment_payment|fx_or_treasury|derivatives_payment|card_network_settlement)", "other_details": "string" } }, "charges": { "charge_bearer": "enum(debtor|shared|creditor)", "breakdown": [ { "amount": "string", "currency_code": "USD", "charging_agent": { "business_identifier_code": "string", "name": "string", "routing_number": "string", "address": { ... }, "local_routing_identifier": { "scheme": "string", "value": "string" } } } ] }, "related_wires": { "original_wire_id": "wire_xyz321", "return_wire_ids": ["wire_xyz456"] }, "return": { "reason": "enum(account_number_incorrect|creditor_account_number_invalid|account_closed|account_blocked|debtor_account_type_invalid|agent_invalid|account_details_changed|account_sequestered|account_liquidated|transaction_forbidden|bank_operation_code_invalid|zero_amount|amount_too_high|currency_not_allowed|non_sufficient_funds|duplication|amount_too_low|amount_blocked|wrong_amount|control_sum_invalid|returned_previously|creditor_name_mismatch|creditor_address_incorrect|initiating_party_unrecognized|unknown_customer|debtor_address_invalid|bank_error|authorization_canceled|creditor_bank_not_registered|currency_incorrect|customer_requested|debtor_bank_not_registered|return_for_technical_reason|settlement_date_invalid|correspondent_bank_unattainable|balance_information_requested|settlement_failed|emv_liability_shifted|eri_option_unsupported|local_instrument_code_invalid|honor_return_request|fraud_suspected|final_response_mandate_canceled|no_mandate|missing_mandate_information|end_customer_requested|end_customer_deceased|creditor_request|per_agent_request|narrative|customer_no_response|non_compliant|transaction_not_found|pin_liability_shifted|routing_number_format_incorrect|creditor_bic_incorrect|transaction_reference_not_unique|missing_debtor_account_number|missing_debtor_data|missing_creditor_data|regulatory_reason|returned_unable_to_apply|debtor_agent_specific_service|creditor_agent_specific_service|creditor_not_whitelisted_by_debtor|creditor_blacklisted_by_debtor|direct_debit_count_exceeded|direct_debit_limit_exceeded|payment_stopped|payment_stopped_previously|service_not_rendered|untimely_transaction|removed_from_tracking|undue_payment|other)", "code": "string", "additional_information": "string" }, "rejection": { "reason": "enum(account_blocked|account_closed|account_number_incorrect|amount_blocked|creditor_account_number_invalid|creditor_address_incorrect|creditor_name_mismatch|creditor_request|debtor_address_invalid|honor_return_request|narrative|per_agent_request|non_sufficient_funds|regulatory_reason|routing_number_format_incorrect|aggregate_limit_exceeded)", "additional_information": "string", "message_identification": "string" }, "return_requests": [ { "created_at": "ISO-8601", "status": "enum(response_needed|pending|accepted|rejected)", "reason": "enum(creditor_account_number_invalid|wrong_amount|customer_requested|duplication|fraud_suspected|narrative|technical_problem|undue_payment|per_agent_request|other)", "details": "string", "deadline": "ISO-8601", "resolution": { "resolved_at": "ISO-8601", "resolved_by": "enum(lead|client|counterparty)", "rejection_reason": "enum(account_closed|non_sufficient_funds|customer_requested|legal_decision|customer_no_response|returned_previously|narrative|per_agent_request|other)", "rejection_details": "string" } } ], "metadata": {} } ``` # Activate an Account Number Source: https://docs.lead.bank/api-reference/endpoint/account-number/activate-an-account-number POST /v1/account_number/{account_number_id}/activate Activate an Account Number. # Assign an Account Number Source: https://docs.lead.bank/api-reference/endpoint/account-number/assign-an-account-number POST /v1/account_number/{account_number_id}/assign Assigns an Account Number with either a ClientCustomerID or EntityID. Only one of these should be provided # Cancel an Account Number Source: https://docs.lead.bank/api-reference/endpoint/account-number/cancel-an-account-number POST /v1/account_number/{account_number_id}/cancel Cancel an Account Number. # Create an Account Number Source: https://docs.lead.bank/api-reference/endpoint/account-number/create-an-account-number POST /v1/account_number Creates an Account Number. Optionally also assigns either a ClientCustomerID or EntityID to the Account Number # Deactivate an Account Number Source: https://docs.lead.bank/api-reference/endpoint/account-number/deactivate-an-account-number POST /v1/account_number/{account_number_id}/deactivate Deactivate an Account Number. # List all Account Numbers Source: https://docs.lead.bank/api-reference/endpoint/account-number/list-all-account-number GET /v1/account_number List all Account Numbers. # Register an Account Number Source: https://docs.lead.bank/api-reference/endpoint/account-number/register-an-account-number POST /v1/account_number/register Registers an Account Number. # Retrieve an Account Number Source: https://docs.lead.bank/api-reference/endpoint/account-number/retrieve-an-account-number GET /v1/account_number/{account_number_id} Retrieve an Account Number. # Update an Account Number Source: https://docs.lead.bank/api-reference/endpoint/account-number/update-an-account-number PATCH /v1/account_number/{account_number_id} Update an Account Number's metadata. # Activate an Account Source: https://docs.lead.bank/api-reference/endpoint/account/activate-an-account POST /v0/accounts/{id}/activate Transitions an account from `inactive` to `active` status. ## Idempotency The Idempotency-Key header is required. # Batch Create Account Entity Relationships Source: https://docs.lead.bank/api-reference/endpoint/account/batch-create-account-entity-relationships POST /v0/accounts/{id}/entity_relationships/batch Associates multiple entities with an account under a single relationship type. # Close an Account Source: https://docs.lead.bank/api-reference/endpoint/account/close-an-account POST /v0/accounts/{id}/close Transitions an account to `closed` status (terminal state). This action cannot be undone. ## Idempotency The Idempotency-Key header is required. # Create an Account Source: https://docs.lead.bank/api-reference/endpoint/account/create-an-account POST /v0/accounts Creates a new account. ## Business Rules - Status is set to `active` by default on creation - Maximum 20 entities per relationship type - Cannot mix individual and business/sole_prop entities in account_holders - Authorized signers required for business/sole_prop account holders - application_id is required for credit accounts ## Idempotency The Idempotency-Key header is required. Reusing a key with a different request body will return a 422 error. # Deactivate an Account Source: https://docs.lead.bank/api-reference/endpoint/account/deactivate-an-account POST /v0/accounts/{id}/deactivate Transitions an account from `active` to `inactive` status. ## Idempotency The Idempotency-Key header is required. # Delete Account Entity Relationship Source: https://docs.lead.bank/api-reference/endpoint/account/delete-account-entity-relationship DELETE /v0/accounts/{id}/entity_relationships/{entity_id} Deletes a specific entity relationship from an account and returns the updated list of entity relationships. The relationship_type must be specified to identify which relationship to delete. # List Account Entity Relationships Source: https://docs.lead.bank/api-reference/endpoint/account/list-account-entity-relationships GET /v0/accounts/{id}/entity_relationships Lists all entity relationships for a specific account. # Retrieve an Account Source: https://docs.lead.bank/api-reference/endpoint/account/retrieve-an-account GET /v0/accounts/{id} Retrieves a specific account by its ID. Accepts a server-generated ID (account_*). Note: Entity relationships are not included in the response. Use GET /v0/accounts/{id}/entity_relationships to retrieve them. # Retrieve an Account by Client Account ID Source: https://docs.lead.bank/api-reference/endpoint/account/retrieve-an-account-by-client-account-id GET /v0/accounts Retrieves an account by the `client_account_id` you assigned, supplied as a query parameter: `GET /v0/accounts?client_account_id=...`. This is the filtered form of the accounts collection and is distinct from `GET /v0/accounts/{id}`, which takes the server-generated Account ID (`account_*`). The response body is identical to `GET /v0/accounts/{id}`. # Update an Account Source: https://docs.lead.bank/api-reference/endpoint/account/update-an-account PATCH /v0/accounts/{id} Updates properties on an existing account. Note: To manage entity relationships, use the /entity_relationships endpoints. Status changes should use dedicated endpoints (/activate, /deactivate, /close). ## Idempotency The Idempotency-Key header is required. # Cancel an ACH Source: https://docs.lead.bank/api-reference/endpoint/ach/cancel-an-ach POST /v1/ach/{ach_id}/cancel Cancel an outgoing ACH. # Create an ACH Source: https://docs.lead.bank/api-reference/endpoint/ach/create-an-ach POST /v1/ach Creates an outgoing ACH. # List all ACH Source: https://docs.lead.bank/api-reference/endpoint/ach/list-all-ach GET /v1/ach List all ACH objects. # Retrieve an ACH Source: https://docs.lead.bank/api-reference/endpoint/ach/retrieve-an-ach GET /v1/ach/{ach_id} Retrieve an ACH object. # Return an ACH Source: https://docs.lead.bank/api-reference/endpoint/ach/return-an-ach POST /v1/ach/{ach_id}/return Issue a return against an incoming ACH. # Reverse an ACH Source: https://docs.lead.bank/api-reference/endpoint/ach/reverse-an-ach POST /v1/ach/{ach_id}/reverse Reverse an outgoing ACH. # Update an ACH Source: https://docs.lead.bank/api-reference/endpoint/ach/update-an-ach PATCH /v1/ach/{ach_id} Update an ACH object. # Create an Application Source: https://docs.lead.bank/api-reference/endpoint/application/create-an-application POST /v0/applications Creates a new credit application in terminal status. ## Business Rules - Applications MUST be created in terminal status (approved, declined, canceled) - Maximum 20 entities per relationship type - Credit fields required for all applications - Adverse action notice required for declined applications - Authorized signers required for commercial account holders - credit.limit cannot exceed credit.max_limit ## Idempotency The Idempotency-Key header is required. Reusing a key with a different request body will return a 422 error. # List Application Entity Relationships Source: https://docs.lead.bank/api-reference/endpoint/application/list-application-entity-relationships GET /v0/applications/{id}/entity_relationships Lists all entity relationships for a specific application. # Retrieve an Application Source: https://docs.lead.bank/api-reference/endpoint/application/retrieve-an-application GET /v0/applications/{id} Retrieves a specific application by its server-generated ID (application_*). To retrieve an application by the client_application_id you assigned, use the filtered collection form instead: GET /v0/applications?client_application_id=... # Retrieve an Application by Client Application ID Source: https://docs.lead.bank/api-reference/endpoint/application/retrieve-an-application-by-client-application-id GET /v0/applications Retrieves an application by the `client_application_id` you assigned, supplied as a query parameter: `GET /v0/applications?client_application_id=...`. This is the filtered form of the applications collection and is distinct from `GET /v0/applications/{id}`, which takes the server-generated Application ID (`application_*`). The response body is identical to `GET /v0/applications/{id}`. # Update an Application Source: https://docs.lead.bank/api-reference/endpoint/application/update-an-application PATCH /v0/applications/{id} Updates properties on an existing application. Uses JSON Merge Patch semantics (RFC 7396): omitted fields are unchanged, explicit values overwrite, nested objects merge recursively. Note: Entity relationships are set when the application is created and cannot be modified afterward. There is no endpoint for adding or removing entity relationships on an existing application; GET /v0/applications/{id}/entity_relationships is read-only. ## Idempotency The Idempotency-Key header is required. Update mutable properties on an existing application. The endpoint uses JSON Merge Patch semantics (RFC 7396): omitted fields stay unchanged, explicit values overwrite, and nested objects merge recursively. ## Mutable Fields The following top-level fields accept updates on this endpoint. | Field | Notes | | - | - | | `status` | Correct a previously reported terminal state. Allowed values: `approved`, `declined`, `canceled`. | | `details` | Partial update of `product_name`, `credit`, and `adverse_action_notice`. Subfields merge recursively per JSON Merge Patch. | | `decision` | Partial update of the decision sub-object. | | `documents` | Replaces the entire array. To add or remove a single document, send the full intended array. | | `metadata` | Replaces the entire metadata object. | All updates are subject to the same field validations that apply on `POST /v0/applications`. See [Applications API validations](/products/applications/validations) for the rule set. ## Immutable Fields The following fields cannot be modified after the application is created. * `id` — Server-generated on creation. * `created_at`, `updated_at` — Server-managed timestamps. * `entities` (account holders, authorized signers, authorized users) — Set when the application is created and immutable afterward. There is no endpoint for adding or removing entity relationships on an existing application; `GET /v0/applications/{id}/entity_relationships` is read-only. A PATCH that targets an immutable field returns `422 parameters_invalid` with the offending field name in `invalid_parameters`. ## Idempotency The `Idempotency-Key` header is required on every request. # Create a Blockchain Payment Source: https://docs.lead.bank/api-reference/endpoint/blockchain-payment/create-a-blockchain-payment POST /v0/blockchain_payments Creates a blockchain payment for fiat or cross-border payments. # List all Blockchain Payments Source: https://docs.lead.bank/api-reference/endpoint/blockchain-payment/list-all-blockchain-payments GET /v0/blockchain_payments List all Blockchain Payments. # Retrieve a Blockchain Payment Source: https://docs.lead.bank/api-reference/endpoint/blockchain-payment/retrieve-a-blockchain-payment GET /v0/blockchain_payments/{blockchain_payment_id} Retrieve a Blockchain Payment. # Create a Card Source: https://docs.lead.bank/api-reference/endpoint/card/create-a-card POST /v0/cards > **Beta:** This endpoint is in beta and may change before general availability. Creates a new card. ## Business Rules - A new card is created in the `active` state. `status` is system-managed and cannot be set on create; status changes go through the status-transition endpoints. - `details.replacement_for` references an existing card that this card replaces. When provided, the referenced card must be in `closed` status at the time of the write and must not already be referenced by another card. ## Idempotency The Idempotency-Key header is required. Reusing a key with a different request body will return a 422 error. # Retrieve a Card Source: https://docs.lead.bank/api-reference/endpoint/card/retrieve-a-card GET /v0/cards/{id} > **Beta:** This endpoint is in beta and may change before general availability. Retrieves a specific card by its ID. Accepts either the server-generated Card ID (`card_*`) or the `client_card_id` of a card created via file upload. # Create an Entity Source: https://docs.lead.bank/api-reference/endpoint/entity/create-an-entity POST /v0/entities Create an Individual, Sole Prop or Business Entity. # Retrieve an Entity by Client Customer ID Source: https://docs.lead.bank/api-reference/endpoint/entity/retrieve-an-entity-by-client-customer-id GET /v0/entities Retrieve an entity by the client customer id # Retrieve an Entity by Entity ID Source: https://docs.lead.bank/api-reference/endpoint/entity/retrieve-an-entity-by-entity-id GET /v0/entities/{id} Retrieve an entity by entity id # Update an Entity Source: https://docs.lead.bank/api-reference/endpoint/entity/update-an-entity PATCH /v0/entities/{id} Certain updates on Entity trigger KYC re-screening, requiring an updated kyc_details.result and kyc_details.screened_at. For individual entities, KYC re-screening is triggered by changes to: first name, last name, date of birth, tax ID value, switching between `us_entity` and `non_us_entity` when that adds or removes a tax ID, and an existing identification document (for non-US entities). The requirement applies only when kyc_details has previously been submitted for the entity, and the new kyc_details.screened_at must be later than the previous one. For business and sole proprietorship entities, KYC re-screening is triggered by changes to: business name, business type, tax ID (US entities), and existing identification document (non-US entities). Note: Business and sole proprietors cannot switch between US and non-US entities. A new entity must be created in such case. # Cancel an Instant Payment Source: https://docs.lead.bank/api-reference/endpoint/instant-payment/cancel-an-instant-payment POST /v1/instant_payments/{instant_payment_id}/cancel Attempt to cancel an outgoing instant payment that is currently in "created" or "under_review" status. # Check Instant Payment Availability Source: https://docs.lead.bank/api-reference/endpoint/instant-payment/check-instant-payment-availability POST /v1/instant_payments/check_availability Check if a given routing number is eligible to receive an instant payment. # Create an Instant Payment Source: https://docs.lead.bank/api-reference/endpoint/instant-payment/create-an-instant-payment POST /v1/instant_payments Initiates an outgoing instant payment. # List all Instant Payments Source: https://docs.lead.bank/api-reference/endpoint/instant-payment/list-all-instant-payments GET /v1/instant_payments List instant payments with optional filtering. # Reject Return Request for Instant Payment Source: https://docs.lead.bank/api-reference/endpoint/instant-payment/reject-return-request-for-instant-payment POST /v1/instant_payments/{instant_payment_id}/reject_return_request Reject the active return request associated with an incoming instant payment. Returns the updated instant payment object with the status of the active return request set to "rejected". # Request Return for Instant Payment Source: https://docs.lead.bank/api-reference/endpoint/instant-payment/request-return-for-instant-payment POST /v1/instant_payments/{instant_payment_id}/request_return Send a return request to the counterparty for a previously posted outgoing instant payment. Returns the updated instant payment object with a new entry in the return_requests array. # Retrieve an Instant Payment Source: https://docs.lead.bank/api-reference/endpoint/instant-payment/retrieve-an-instant-payment GET /v1/instant_payments/{instant_payment_id} Retrieve the details of an instant payment. # Return an Instant Payment Source: https://docs.lead.bank/api-reference/endpoint/instant-payment/return-an-instant-payment POST /v1/instant_payments/{instant_payment_id}/return Initiates an outgoing instant payment return. If there is an outstanding return request, invoking this endpoint is also understood as accepting the active return request. # Activate an Originator Source: https://docs.lead.bank/api-reference/endpoint/originator/activate-an-originator POST /v0/originators/{originator_id}/activate Activate an Originator. # Cancel an Originator Source: https://docs.lead.bank/api-reference/endpoint/originator/cancel-an-originator POST /v0/originators/{originator_id}/cancel Cancel an Originator. # Create an Originator Source: https://docs.lead.bank/api-reference/endpoint/originator/create-an-originator POST /v0/originators Create an Originator carrying your ACH origination parameters. # Deactivate an Originator Source: https://docs.lead.bank/api-reference/endpoint/originator/deactivate-an-originator POST /v0/originators/{originator_id}/deactivate Deactivate an Originator. # List all Originators Source: https://docs.lead.bank/api-reference/endpoint/originator/list-all-originators GET /v0/originators List all Originators. # Retrieve an Originator Source: https://docs.lead.bank/api-reference/endpoint/originator/retrieve-an-originator GET /v0/originators/{originator_id} Retrieve an Originator. # Update an Originator Source: https://docs.lead.bank/api-reference/endpoint/originator/update-an-originator PATCH /v0/originators/{originator_id} Update an Originator's parameters. # Cancel a Wire Source: https://docs.lead.bank/api-reference/endpoint/wire/cancel-a-wire-v1 POST /v1/wires/{wire_id}/cancel Cancel a wire object. # Cancel a Wire Source: https://docs.lead.bank/api-reference/endpoint/wire/cancel-a-wire-v2 https://docs.lead.bank/openapi.json POST /v2/wires/{id}/cancel Cancel a wire object. > [!NOTE] > > See [Errors](/api-reference/using-the-api/errors-v2) for the common errors every v2 endpoint can return. # Create a Wire Source: https://docs.lead.bank/api-reference/endpoint/wire/create-a-wire-v1 POST /v1/wires Create a new outgoing wire. # Create a Wire Source: https://docs.lead.bank/api-reference/endpoint/wire/create-a-wire-v2 https://docs.lead.bank/openapi.json POST /v2/wires Create a new outgoing wire > [!NOTE] > > See [Errors](/api-reference/using-the-api/errors-v2) for the common errors every v2 endpoint can return. # List all Wires Source: https://docs.lead.bank/api-reference/endpoint/wire/list-all-wires-v1 GET /v1/wires List all wire objects. # List all Wires Source: https://docs.lead.bank/api-reference/endpoint/wire/list-all-wires-v2 https://docs.lead.bank/openapi.json GET /v2/wires List all wire objects. > [!NOTE] > > See [Errors](/api-reference/using-the-api/errors-v2) for the common errors every v2 endpoint can return. # Reject a Return Request for a Wire Source: https://docs.lead.bank/api-reference/endpoint/wire/reject-return-request-for-wire-v1 POST /v1/wires/{wire_id}/reject_return_request Reject the currently active incoming return request associated with the wire. # Reject a Return Request for a Wire Source: https://docs.lead.bank/api-reference/endpoint/wire/reject-return-request-for-wire-v2 https://docs.lead.bank/openapi.json POST /v2/wires/{id}/reject_return_request Reject the currently active incoming return request associated with the wire. > [!NOTE] > > See [Errors](/api-reference/using-the-api/errors-v2) for the common errors every v2 endpoint can return. # Request return for a Wire Source: https://docs.lead.bank/api-reference/endpoint/wire/request-return-for-wire-v1 POST /v1/wires/{wire_id}/request_return Send a return request (camt.056) to the counterparty financial institution for a previously sent outgoing wire. Returns the updated wire object with a new entry in the `return_requests` array in `pending` status. # Request Return for a Wire Source: https://docs.lead.bank/api-reference/endpoint/wire/request-return-for-wire-v2 https://docs.lead.bank/openapi.json POST /v2/wires/{id}/request_return Create a return request for a previously sent outgoing wire. > [!NOTE] > > See [Errors](/api-reference/using-the-api/errors-v2) for the common errors every v2 endpoint can return. # Retrieve a Wire Source: https://docs.lead.bank/api-reference/endpoint/wire/retrieve-a-wire-v1 GET /v1/wires/{wire_id} Retrieve a wire object. # Retrieve a Wire Source: https://docs.lead.bank/api-reference/endpoint/wire/retrieve-a-wire-v2 https://docs.lead.bank/openapi.json GET /v2/wires/{id} Retrieve a wire object. > [!NOTE] > > See [Errors](/api-reference/using-the-api/errors-v2) for the common errors every v2 endpoint can return. # Return a Wire Source: https://docs.lead.bank/api-reference/endpoint/wire/return-a-wire-v1 POST /v1/wires/{wire_id}/return Initiate a return against an incoming wire. # Return a Wire Source: https://docs.lead.bank/api-reference/endpoint/wire/return-a-wire-v2 https://docs.lead.bank/openapi.json POST /v2/wires/{id}/return Initiate a return against an incoming wire. > [!NOTE] > > See [Errors](/api-reference/using-the-api/errors-v2) for the common errors every v2 endpoint can return. # Update a Wire Source: https://docs.lead.bank/api-reference/endpoint/wire/update-a-wire-v1 PATCH /v1/wires/{wire_id} Update a wire. # Update a Wire Source: https://docs.lead.bank/api-reference/endpoint/wire/update-a-wire-v2 https://docs.lead.bank/openapi.json PATCH /v2/wires/{id} Update a wire. > [!NOTE] > > See [Errors](/api-reference/using-the-api/errors-v2) for the common errors every v2 endpoint can return. # API Overview, OAuth Authentication, and IP Allowlist Source: https://docs.lead.bank/api-reference/using-the-api/authentication Authenticate to Lead's REST APIs with OAuth2, choose the right access token scopes, and configure your IP allowlist for production traffic. > [!WARNING] > > **Upcoming Change** > > OAuth access tokens will be cached for up to 23 hours and must be reused until expiration. Partners requesting a new token before every API call will need to update their authentication implementation before enforcement begins. > > 👉 [View Details](/upcoming-changes#oauth-access-token-caching) ## Introduction Lead's APIs are [REST](https://en.wikipedia.org/wiki/Representational_state_transfer)-based, accept and return JSON-encoded payloads, and use standard HTTP response codes, authentication, and verbs. ## Authentication Lead uses [OAuth2](https://oauth.net/2/) for Authentication. When we onboard your program, you will be set up with a `client_id` and a `client_secret`. These credentials can be used to retrieve an `access_token` which you will use to authenticate further requests. > [!TIP] > > By default, access tokens have a 24 hour expiry, and will need to be replaced before they expire. See the `expires_in` passed in the token response to track the TTL (time-to-live). They can also be limited to certain API scopes which can help you with access control while preventing unauthorized requests. ### Steps **1. Get Access Token** Use your `client_id` and `client_secret` to get an `access_token` with the [Authentication API](/api-reference/endpoint/oauth/get-an-access-token). **2. Authenticate Requests** Use the `access_token` in the `'authorization: Bearer '` header to authenticate further API requests. ### Available scopes Pass one or more of the following values in the `scope` parameter of the [token request](/api-reference/endpoint/oauth/get-an-access-token) (space-delimited) to provision an access token. Request the least-privileged scope appropriate to the operation. A token presented to an endpoint that requires a scope it was not provisioned for returns `403`. Requesting a scope your program is not provisioned for in the token request itself also returns `403` with code `insufficient_scope`. | Scope | Resource | Access | | :- | :- | :- | | `account/read` | Accounts | Read | | `account/read_write` | Accounts | Read/write | | `account_number/read` | Account Numbers | Read | | `account_number/read_write` | Account Numbers | Read/write | | `ach/read` | ACH | Read | | `ach/read_write` | ACH | Read/write | | `application/read` | Applications | Read | | `application/read_write` | Applications | Read/write | | `blockchain_payment/read` | Blockchain Payments | Read | | `blockchain_payment/read_write` | Blockchain Payments | Read/write | | `card/read` | Cards | Read | | `card/read_write` | Cards | Read/write | | `card_network_settlement/read_write` | Receivables | Sandbox simulation of card network settlements | | `core_account/read` | Core Accounts | Read | | `core_balance/read` | Core Balances | Read | | `core_transaction/read` | Core Transactions | Read | | `entity/read` | Entities | Read | | `entity/read_write` | Entities | Read/write | | `event/read` | Webhook Events | Read | | `file/read` | Files | Read | | `file/read_write` | Files | Read/write | | `funding/read` | Funding | Read | | `funding/read_write` | Funding | Read/write | | `instant_payment/read` | Instant Payments | Read | | `instant_payment/read_write` | Instant Payments | Read/write | | `internal_transfer/read` | Internal Transfers | Read | | `internal_transfer/read_write` | Internal Transfers | Read/write | | `lending/read` | Lending | Read | | `lending/read_write` | Lending | Read/write | | `receivable/read` | Receivables | Read | | `receivable_sale/read` | Receivable Sales | Read | | `subledger_balance/read` | Subledger Balances | Read | | `subledger_balance/read_write` | Subledger Balances | Read/write | | `user_account/read` | User Accounts | Read | | `user_account/read_write` | User Accounts | Read/write | | `user_credit_balance/read` | User Credit Balances | Read | | `user_credit_balance/read_write` | User Credit Balances | Read/write | | `user_credit_transaction/read` | User Credit Transactions | Read | | `user_credit_transaction/read_write` | User Credit Transactions | Read/write | | `wire/read` | Wires | Read | | `wire/read_write` | Wires | Read/write | > [!NOTE] > > There is no separate `originator/*` scope for the `/v0/originators` endpoints. If you're unsure which scope a specific endpoint requires, contact your Technical Account Manager. ## IP Allowlist An IP allowlist restricts API access to a predefined set of approved IPv4 addresses or subnets. Requests originating from addresses outside the allowlist are rejected. This provides an additional layer of protection by ensuring that only trusted networks can access the API. ### Configuration Each API partner can be configured with a set of allowed IP subnets. When a request is received, the API server validates the request’s source IP address against the configured allowlist: * If the source IP address falls within an allowed subnet, the API processes the request. * If the source IP address doesn't match any allowed subnet, the API rejects the request with status code `403`. The error code depends on the API version: ```http v2 theme={null} HTTP/1.1 403 Forbidden { "code": "source_ip_not_permitted", "message": "This request came from an IP address that isn't on your program's allowlist. Send from an allowlisted IP, or contact Lead to update the list." } ``` ```json v1 theme={null} { "status": 403, "code": "source_ip_not_allowed", "title": "Requests from this IP address are not permitted for this program.", "invalid_parameters": [ { "parameter": "source_ip", "reason": "source IP not allowed for program" } ] } ``` For the full list of error codes, see [Errors for v2](/api-reference/using-the-api/errors-v2) or [Errors for v1](/api-reference/using-the-api/errors). ### Setup To utilize Lead’s IP allowlist feature: **1. Provide Lead With Your IP Subnets** Give them to your Technical Account Manager. **2. Specify Each Subnet** Use [CIDR notation](https://en.wikipedia.org/wiki/Classless_Inter-Domain_Routing). **Configuration limits:** * Maximum subnets: 30 * Supported IP version: IPv4 only * Supported CIDR prefix lengths: /20 to /32 * Broader ranges such as /16 or /8 are not supported. ### Unsupported IP Addresses The following IP address types cannot be included in the IP allowlist. **IPv6 addresses** * Only IPv4 addresses are supported. **Private IP ranges** * `10.0.0.0/8` * `172.16.0.0/12` * `192.168.0.0/16` **Loopback addresses** * `127.0.0.0/8` **Link-local addresses** * `169.254.0.0/16` **Invalid formats** * Any address not in valid IPv4 format (`x.x.x.x`, where each octet is between 0 and 255). # Errors Source: https://docs.lead.bank/api-reference/using-the-api/errors Understand how Lead handles errors and error messages. Lead uses HTTP status codes to indicate the success or failure of an API request. * Codes in the `2xx` range indicate success. * Codes in the `4xx` range indicate a problem with the request. These are fixable using the information in the error response. * Codes in the `5xx` range indicate a problem on Lead's side. These are rare and are usually safe to retry. > [!NOTE] > > Always use the HTTP status code on the response to determine the outcome of a request. The `status` field in the response body is a convenience copy and may be missing on some responses. ## Error response Most error responses use this shape, however all fields are optional: ```json theme={null} { "code": "string", "title": "string", "detail": "string", "status": "string", "instance": "string", "invalid_parameters": [ { "parameter": "string", "reason": "string" } ] } ``` | **Field** | **Type** | **Description** | | - | - | - | | `code` | string | A machine-readable string that identifies the error. Use this field to handle errors programmatically. | | `title` | string | A short, human-readable summary of the error. Meant for developers, not end users. The text may change, so don't use it programmatically. | | `detail` | string | A human-readable explanation specific to this occurrence of the error. The text may change, so don't use it programmatically. | | `status` | string | The HTTP status code, as a string (for example, `"422"`). | | `instance` | string | The ID of the object the error relates to, when there is one. | | `invalid_parameters` | array | Present when one or more request fields failed validation. Each entry has a `parameter` (the field path) and a `reason`. | ## HTTP status codes | **Status** | **Meaning** | | - | - | | `400` | The request couldn't be processed. Common causes: the body isn't valid JSON, a required header such as `Idempotency-Key` is missing, or the operation isn't allowed on the object in its current state. | | `401` | The request couldn't be authenticated. Check your access token. | | `403` | The request was authenticated but isn't permitted, such as a control or policy blocking the payment. | | `404` | The URL or object couldn't be found. For security, objects that belong to another program also return `404`. | | `409` | The request conflicts with another request in progress, typically one using the same idempotency key. | | `422` | The request was well-formed but failed validation or a business rule. Check `detail` and `invalid_parameters`. | | `429` | You've exceeded the rate limit. Wait and retry. | | `500` | Something went wrong on Lead's side. Retry the request with the same idempotency key. If it keeps happening, contact Lead. | ## Variations by API Some APIs don't yet return the standard shape for every error. Code defensively against these cases: | **API** | **Variation** | | - | - | | Instant Payments | Business-rule errors return only `detail` and `status`, with no `code` or `title`. Schema validation and idempotency errors return `{"message": "..."}`. | | Entities, Accounts, Applications, Cards | Validation failures use the code `validation_error` with `invalid_parameters`. A timestamp that isn't a real calendar date can return `400` with `{"message": "..."}`. | | Lending Disbursements | A `500` on retrieve may return an empty body. | > [!NOTE] > > We're standardizing error responses across all Lead APIs as part of our V2 update. Changes to error formats will be announced before they take effect. # Idempotency Source: https://docs.lead.bank/api-reference/using-the-api/idempotency Safely retry requests without creating duplicate operations. ## Overview Network issues, timeouts, or service interruptions can make it unclear whether an API request succeeded. Idempotency keys address this by allowing you to safely retry requests without creating duplicate operations. When you include an idempotency key, you can retry the same request as needed. If the original request was successful, the API returns the same response. If it was not, the request is processed normally. ### Idempotent Requests To make an idempotent request, include an Idempotency-Key header with a unique value: ```bash theme={null} curl --request POST \ --url https://api.sandbox.lead.bank/v1/ach \ --header 'Idempotency-Key: example-payment-123-retry-001' \ --header 'accept: application/json' \ --header 'content-type: application/json' \ --data '{ "echo": "Hello!" }' ``` ### Idempotency Key Requirements * **Key format:** Use any string up to 255 characters. We recommend using a V4 UUID or another random string to ensure uniqueness. * **Key expiration:** The idempotency key is valid for 48 hours from the time of API submission. After this period, the key expires and can be reused for another API request. ## How It Works When you make requests with idempotency keys, our API handles them as follows: * **Same key, successful original request:** The API returns the identical response from the original request without performing any new operations. * **Same key, failed original request:** Depending on the error, the API may attempt the operation again. Please look at the response for further details. * **Same key, different parameters:** The API returns an error since the request parameters don't match the original. > [!TIP] > > Two requests are considered identical when they use the same idempotency key and target the same endpoint within the 48-hour window. ## Why Use An Idempotency Key? * **Eliminates duplicate operations:** Network issues and timeouts won't result in duplicate payments, transfers, or other critical operations. * **Simplifies error handling:** You can safely retry any request without complex logic to check if the original succeeded. * **Improved reliability:** Guarantees that repeated requests will not have additional unintended effects, giving you confidence in the consistency of your transactions. # Webhooks & Events Source: https://docs.lead.bank/api-reference/using-the-api/webhooks Receive Lead webhooks, verify signatures, handle retries and duplicates, and pair event delivery with reconciliation for ACH, wires, and accounts. > [!NOTE] > > Lead sends webhooks to notify you about events that happen within your program. We use HTTPS to send events as a JSON payload. You can then use these events to trigger new actions in your system. ## Webhook Authentication To verify a webhook came from Lead, every webhook contains a signature in the header: `Lead-Signature`. The format of the `Lead-Signature` header is `t={0},v0={1}`. * `t` is the timestamp in milliseconds * `v0` is a [HMAC signature](https://en.wikipedia.org/wiki/HMAC) with [SHA-256](https://en.wikipedia.org/wiki/SHA-2). It uses the webhook endpoint's signing secret as the key, and the event payload (the request body) in string bytes as the message. * The `hmac` portion of the signature header is base64 encoded. To authenticate a webhook, calculate the HMAC of the `t` and webhook request body concatenated with `.`, i.e. base64(HMAC256(t + `.` + webhook request body)), and ensure it matches v0, the signature sent in the `Lead-Signature` header. > [!TIP] > > Ensure to concatenate the webhook request body as bytes (directly as it is received) without any additional processing. For added security, you can also compare `t`, the timestamp the webhook was sent to the current timestamp on your server and decide if it's within your tolerance to prevent a [replay attack](https://en.wikipedia.org/wiki/Replay_attack). ### Webhook IP Addresses Lead will always send webhooks from the following IP addresses: * **Production:** `3.216.219.186` * **Sandbox:** `34.234.237.195` ## Replayed & Missed Events Lead will consider an event successfully delivered once we receive a 2XX HTTP response from your webhook endpoint. If an event delivery receives a non-2XX response, we will retry delivery every three hours until we receive a success response from your endpoint, or we've made 24 attempts. > [!TIP] > > An event may be delivered multiple times to a webhook endpoint. > > To prevent processing the same event multiple times you can use the unique event `id` as an idempotency key. To ensure you haven't missed any events, use the [List all events API](/api-reference/endpoint/events/list-all-events) to retrieve previous events up to 90 days. > [!WARNING] > > Retrieving an event older than 90 days will result in a 404. ### Pairing Webhooks With Reconciliation Webhooks are the recommended way to receive real-time lifecycle updates, but they should not be your only signal. A polling-only integration is fragile, and a webhook-only integration can miss events. Pair webhooks with a periodic reconciliation pass for the following reasons: * **Not every status sends a webhook.** Some states are marked `Webhook Sent: No` in the event tables below (for example, `wire.created`, `ach.processing`, `ach.pending_return`, `account_number.activated`). You will only observe those states by retrieving the underlying resource (such as `GET /v1/wires/{wire_id}` or `GET /v1/ach/{ach_id}`) or by listing events. * **Delivery is retried but not guaranteed forever.** Failed deliveries retry every three hours up to 24 attempts. After that, the event is not retried. * **Events may be delivered more than once.** Use the event `id` as an idempotency key when processing. * **Events expire after 90 days.** Reconcile before that window closes. For most programs, the recommended pattern is: 1. Process webhooks in real time as the primary trigger for downstream logic. 2. Run a periodic reconciliation job (for example, hourly or daily) that calls [List all events](/api-reference/endpoint/events/list-all-events) and/or the relevant resource endpoint to catch anything missed. 3. Use the resource endpoint (`GET /v1/wires/{wire_id}`, `GET /v1/ach/{ach_id}`, `GET /v1/instant_payments/{id}`, etc.) when you need the authoritative current status of a single transfer. ## Webhook Format Sample of `Lead-Signature` header with the hmac value under `v0` : ```text theme={null} "t=1713350954014,v0=EonRn+iGDCUm+VSc+rR9RVvMOofQDR/bfEJvihRSx6g=" ``` An event body will follow this shape: ```json theme={null} { "id": "string", "created_at": "ISO-8601" "object": {hash}, "event": "string", } ``` | **Field** | **Description** | | - | - | | id | A unique identifier for this specific event. | | created\_at | The ISO-8601 timestamp of when the event object was created. | | object | The most up to date version of the object affected by this event. | | event | A machine-readable string describing this event. | ## Event Types > [accordion] ACH Events > > | **Event** | **Description** | **ACH Direction** | **Webhook Sent** | > | - | - | - | - | > | ach.scheduled | The Lead platform has received an incoming ACH and is waiting on settlement to post to your account. | incoming | Yes | > | ach.processing | The ACH will be submitted soon for Fed processing. Outgoing ACH in this status can no longer be canceled via the API. | outgoing | No | > | ach.submitted | The Lead platform has submitted the ACH transfer for Fed processing. | outgoing | Yes | > | ach.posted | The ACH transfer has successfully completed and has been posted to the receiving bank account. *For outbound, if the receiver is at a different bank, the funds may take a few hours to appear.* | outgoing incoming | Yes, except if previous status = ach.pending\_return | > | ach.under\_review | The ACH transfer has triggered a validation rule that requires further review by the Lead Payment Ops team. Please see best practices on how to avoid this status. We may reach out to you for additional information. | outgoing incoming | Yes for outbound; No for inbound | > | ach.approved | A successful result of a manual review by Lead. This indicates that the ACH transfer will continue to process. | outgoing incoming | Yes | > | ach.rejected | An unsuccessful result of a manual review, indicating that Lead Payment Ops has detected an issue with the ACH transfer. Review the data in the rejection hash to determine what to fix and resubmit a corrected ACH transfer if appropriate. This is a terminal status. Please reach out to support via your Slack channel if you have further questions about this decision. | outgoing | Yes | > | ach.pending\_return | The Lead platform has received notice that a previously posted ACH transfer is going to be returned. | incoming | No | > | ach.returned | A return processed successfully, and the original ACH transaction is now returned. | outgoing incoming | Yes | > | ach.return\_dishonored | A dishonored return processed successfully, and the original ACH transaction is now dishonored. | outgoing incoming | Yes | > | ach.return\_contested | A contested return processed successfully, and the original ACH transaction is now contested. | outgoing incoming | Yes | > | ach.corrected | Sent if the counterparty has updated any information about their account. | outgoing | Yes | > [accordion] Internal Transfer Events > > | **Event** | **Description** | **Webhook Sent** | > | - | - | - | > | internal\_transfer.posted | The internal transfer was completed and money has successfully moved from the `sender_account_number_id` to the `receiver_account_number_id` | Yes | > | internal\_transfer.rejected | The internal transfer was not completed and will not be retried. Please see `rejection.reason` and `rejection.details` for more information. | Yes | > [accordion] Instant Payment Events > > **Incoming** > > | **Event** | **Description** | **Webhook Sent** | > | :- | :- | :- | > | instant\_payment.under\_review | **Lead** is manually reviewing the incoming instant payment. | Yes | > | instant\_payment.posted | **Lead** posted the incoming instant payment to your account. | Yes | > | instant\_payment.rejected | **Lead** rejected the incoming instant payment. | Yes | > | instant\_payment.return\_request\_response\_needed | You received an incoming return request that requires a response from you. | Yes | > > **Outgoing** > > | **Event** | **Description** | **Webhook Sent** | > | :- | :- | :- | > | instant\_payment.under\_review | **Lead** is manually reviewing the outgoing instant payment before sending it to the network. | Yes | > | instant\_payment.posted | The outgoing instant payment has been posted to the **Lead** account. | Yes | > | instant\_payment.rejected | The outgoing instant payment has been rejected by **Lead**, the counterparty, or the network. | Yes | > | instant\_payment.counterparty\_status\_updated | The counterparty status of the outgoing instant payment has been updated. | Yes | > | instant\_payment.return\_request\_status\_updated | The status of the outgoing return request has been updated. | Yes | > [accordion] Wire Events > > **Incoming** > > | **Event** | **Description** | **Webhook Sent** | > | - | - | - | > | wire.posted | A wire is received by Lead and funds are successfully posted to the corresponding account's balance. | Yes | > | wire.rejected | A wire is received but later rejected by Lead. Lead has returned the funds to the sender. See `rejection` section in the wire object for reasons and dest | Yes | > > **Outgoing** > > | **Event** | **Description** | **Webhook Sent** | > | :- | :- | :- | > | wire.created | The wire was created. | No | > | wire.scheduled | The wire transaction has passed Lead's internal review and is scheduled to be submitted to the Fedwire network. *This is the last stage you can cancel a wire.* | Yes | > | wire.processing | Lead's system is processing the wire submission. *You can not cancel this wire after reaching this stage.* | Yes | > | wire.posted | The wire has been successfully submitted to the counterparty financial institution. `IMAD`*value is available in the object.* | Yes | > | wire.under\_review | Lead is performing additional review on this wire transaction. | Yes | > | wire.rejected | Lead has reviewed and rejected this wire transaction. | Yes | > | wire.cancel\_pending | Lead has received the cancel request and we are processing the request. | No | > | wire.canceled | Lead has successfully canceled the wire and related funds have been returned to your account. | Yes | > > **Return Requests** > > | **Event** | **Description** | **Webhook** Sent | > | - | - | - | > | wire.return\_request\_response\_needed | You received an incoming return request that requires a response from you. | Yes | > | wire.return\_request\_pending | The outgoing return request is created and is pending a response from the counterparty. | No | > | wire.return\_request\_status\_updated | The status of an outgoing return request has changed. | Yes | > [accordion] Account Number Events > > | **Event** | **Description** | **Webhook Sent** | > | - | - | - | > | account\_number.created | The Account Number was created. | Yes if created by Lead. Otherwise, no. | > | account\_number.activated | The Account Number was activated. | No; synchronous 200 | > | account\_number.deactivated | The Account Number was deactivated. | No; synchronous 200 | > | account\_number.canceled | The Account Number was canceled. | No; synchronous 200 | > [accordion] Lending Events > > | **Event** | **Description** | **Webhook Sent** | > | - | - | - | > | lending.disbursement.processing | The Disbursement is being processed. You cannot cancel the Disbursement anymore. | Yes | > | lending.disbursement.succeeded | The Disbursement has succeeded. The funds should have landed in the counterparty’s account. | Yes | > | lending.disbursement.failed | The Disbursement has failed. The `failure` field on the Disbursement object will provide details on the failure. | Yes | > | lending.disbursement.ach\_correction | Sent if the counterparty’s account details have been corrected by their bank. This is only applicable for ACH. | Yes | > [accordion] Funding Events > > | Event | Description | Webhook Sent | > | - | - | - | > | funding.posted | The funding request was completed and money has successfully moved to the funding account(s) configured for your program. | Yes | > | funding.rejected | The funding request was not completed and will not be retried. Sent for v0 fundings only. v2 fundings have no `rejected` status. | Yes | > [accordion] Receivable Sale Events > > | Event | Description | Webhook Sent | > | - | - | - | > | receivable\_sale.created | The daily sale was created with one or more receivables. Its receivables and `purchase_amount` are frozen. | Yes | > | receivable\_sale.no\_receivables\_for\_sale | The daily sale ran and found no receivables to sell, so `purchase_amount` is 0. | Yes | > | receivable\_sale.settled | The sale's `purchase_amount` was debited from your account. `core_transaction_id` is set. | Yes | > | receivable\_sale.failed | The sale could not be settled because your account had insufficient funds or was closed. The sale's `status` is `failed`; check `failure.reason` for the cause and `failure.details` for next steps. | Yes | # Run a Credit or Charge Card Program Source: https://docs.lead.bank/guides/issue/credit-and-charge-card-program Launch revolving credit your customers spend through a card, with the receivables purchased from Lead on a daily sale cycle. This guide covers the building blocks of a card-based credit program on Lead: revolving credit lines, cards issued through your issuer processor, card spending that settles through the card networks, and the daily purchase of the [receivables](/products/lending/receivables-and-the-daily-sale) that card spending creates. ## **How It Works** The credit flow is the same as any lending program: **Entity** → **Application** → **Account** → **Balance**. For card programs, you open and maintain the Balance through the daily Balances file, not the API. Repayments restore available credit. You create cards with your **issuer processor** and report them to Lead as **Card** objects. Card spending settles with the networks through Lead's [Network Settlement](/products/network-settlement/overview) process. Because Lead is the lender of record, network settlement originates **receivables** on Lead's books, which Lead groups into a daily **sale** that you purchase. Today you purchase the sale through the Sales Request/Response file exchange. ## **Example Scenario** Fieldstone issues charge cards to small landscaping businesses. When Bluebonnet Landscaping signs up, Fieldstone creates an Entity for the business, including its beneficial owners and control persons, plus an Entity for each employee who will carry a card as an authorized user. Fieldstone approves Bluebonnet for a \$25,000 line, reports the application to Lead, opens the account, issues a card through its processor and reports it to Lead, and opens the balance. Bluebonnet spends \$4,000 in the first week; the networks settle that spend, which creates receivables at Lead that roll into the daily sales Fieldstone purchases. Each day, Fieldstone reports Bluebonnet's balance, spend, and repayments to Lead. ## **Objects Involved** | **Object** | **Surface** | **Role in this flow** | **Reference** | | :- | :- | :- | :- | | Entity | user | The business, including its beneficial owners and control persons, plus any authorized users | [Entities](/api-reference/endpoint/entity/create-an-entity) | | Application | user | The terminal credit decision for the line | [Applications](/api-reference/endpoint/application/create-an-application) | | Account | user | The credit relationship (credit\_with\_underwriting) | [Accounts](/api-reference/endpoint/account/create-an-account) | | Card | user | Your report of each card issued at your processor | [Cards](/api-reference/endpoint/card/create-a-card) | | Balance / Transaction reporting | user *(file only)* | The Balances file is where you create each Balance and report its daily position. The Transactions file is where you report new activity: card spend, repayments, interest, and fees. | [Balances](/file-reference/balances-and-transactions/balances-schema) & [Transactions](/file-reference/balances-and-transactions/transactions-schema) file schemas | | Daily sale (receivables) | execution *(file today)* | Your purchase of the receivables network settlement created | [Sales Request file schema](/file-reference/sales/request-schema), [Sales Response file schema](/file-reference/sales/response-schema), and [how settlement amounts work](/products/funding-and-receivables/sales-settlement-amount). | ## **Before You Start** * Obtain sandbox credentials with scopes for entities, applications, accounts, and card/read\_write. You also need an issuer-processor relationship: you create cards with your issuer processor, and you report them to Lead through the Cards API for oversight only. * **The receivables sale runs on files today.** You acknowledge each day's purchase through the Sales Request/Response exchange over SFTP — [Sales Request file schema](/file-reference/sales/request-schema), [Sales Response file schema](/file-reference/sales/response-schema), and [how settlement amounts work](/products/funding-and-receivables/sales-settlement-amount). * **Balances and Transactions are file-only for card programs.** You open and service each Balance (repayments, interest, fees) through the daily [Balances](/file-reference/balances-and-transactions/balances-schema) and [Transactions](/file-reference/balances-and-transactions/transactions-schema) files. Card programs cannot use the Subledger Balance API. ## **Integration Steps** ### **Step 1: Create the Borrower Entity (or Entities)** Report each borrower along with your attested KYC/OFAC screening results. For a business borrower, first create an individual Entity for each beneficial owner, control person, and authorized user. Then create the business Entity and link its beneficial owners and control persons. For a sole proprietorship, create the individual first, then create the `sole_prop` Entity and link the individual as its `sole_proprietor`. See [Beneficial Ownership Requirements](/products/entity/beneficial-ownership) and [Roles](/products/entity/roles). ```text theme={null} POST /v0/entities { "type": "business", "beneficial_owners": [{ "entity_id": "..." }], "control_persons": [{ "entity_id": "...", "title": "..." }]... } ``` ### **Step 2: Report the Underwriting Decision via Application** You always report Applications in a terminal status: approved, declined, or canceled. Lead does not require you to report in-flight applications. If you report a decline, include the adverse-action fields. ```text theme={null} POST /v0/applications { "status": "approved"... } ``` ### **Step 3: Open the Account** ```text theme={null} POST /v0/accounts { "capabilities": ["credit_with_underwriting"], "application_id": "...", "entity_id": "..." } ``` Lead creates the Account in an active status. The Account includes a reference to the Application from the prior step. Then add any authorized users to the Account with [Batch Create Account-Entity Relationships](/api-reference/endpoint/account/batch-create-account-entity-relationships) so their cards can reference it. ### **Step 4: Report the Card** Create the card with your issuer processor, then report it to Lead for oversight, referencing the Account and the cardholder's Entity. ```text theme={null} POST /v0/cards { "account_id": "...", "entity_id": "...", "details": { "card_product_name": "...", "card_type": "commercial", "is_virtual": false, "expiry_date": "2029-10-31", "last_four": "1234" } } ``` Lead creates Cards in an active status. When a card's status changes at your processor, update it in Lead through the activate, deactivate, and close endpoints. Lead uses card status for compliance oversight. See [Card Validations](/products/cards/validations). ### **Step 5: Create the Balance** Card programs create Balances through the daily [Balances file](/file-reference/balances-and-transactions/balances-schema). Card programs cannot use the Subledger Balance API. To create a Balance, include a row with a new `client_balance_id`, the `account_id` from Step 3, and `type` = `credit`. Lead creates a Balance for any `client_balance_id` that does not already exist. Lead must have processed the Account before you submit the Balances file that references it ([Balance Validations](/file-reference/balances-and-transactions/balance-validations)). ### **Step 6: Cardholder Spends on the Card (Outside of Lead)** Your issuer processor handles authorization, and the card networks handle settlement. You do not call Lead in this step. Funds move through Lead's [Network Settlement](/products/network-settlement/overview) process, and because Lead is the lender of record, settled spend results in receivables on Lead's books. ### **Step 7: Report Balance and Transaction Updates via Files** Each day, send: * **Balances file:** the current position of every Balance in a non-terminal status (anything other than `closed` or `receivable_transferred`). Include each one every day, even if nothing changed. * **Transactions file:** new activity since the last file, including settled card spend, repayments, interest, and fees. For card spend, set `transfer_type` = `card`, include the `card_id` from Step 4, and set `settlement_date` to the date the transaction appeared in the network's raw settlement file. Lead uses your settled card transactions to run [Network Settlement Reconciliation](/products/network-settlement/reconciliation). See the [Transactions file schema](/file-reference/balances-and-transactions/transactions-schema) for all fields. ### **Step 8: Purchase the Day's Receivables** Each business day, Lead groups the receivables that have cleared your program's hold period into a single sale, priced according to [how settlement amounts work](/products/funding-and-receivables/sales-settlement-amount): principal plus imputed interest for the hold period. You acknowledge the purchase through the Sales Request/Response file exchange over SFTP ([Sales Request file schema](/file-reference/sales/request-schema), [Sales Response file schema](/file-reference/sales/response-schema)), and the settlement amount moves from your settlement account. The day's sale settles in full or not at all, so fund your settlement account before each sale. **Note: upcoming Sale API** Lead plans to release a Sale API that replaces the file exchange with a daily sale object you review and accept in a single call ([Platform Evolution](/core-concepts/platform/platform-evolution)). ## **Related** [Receivables & the Daily Sale](/products/lending/receivables-and-the-daily-sale) · [Sales Settlement Amount](/products/funding-and-receivables/sales-settlement-amount) · [Network Settlement](/products/network-settlement/overview) · [Balances & Transactions](/products/balances-and-transactions/overview) · [Cards](/products/cards/overview) · [Launch a Debit Card Program](/guides/issue/debit-card-program) · [Instant Loan Origination and Disbursement](/guides/lend/instant-loan-origination-and-disbursement) *If something in this guide does not match what you see, contact your Lead team.* # Launch a Debit Card Program Source: https://docs.lead.bank/guides/issue/debit-card-program Add debit cards to a deposit program: report issuance, keep lifecycle current, and reconcile network settlement. This guide covers adding debit cards to a deposit program — cards your customers spend with against money they hold at Lead. It assumes the deposit chain from [Launch a deposit program](/guides/store/launch-a-deposit-program) is in place; what's new is the card layer, organized here by building block. ## **How it works** Cards are created with your **issuer processor** — Lead's role is oversight, so you *report* each card to Lead as a **Card** object, keep its status current, and report card spend in your daily Transactions file like any other activity. Settlement with the networks runs through Lead's [network settlement](/products/network-settlement/overview) process; your job there is reconciliation. ## **Example scenario** Nest Egg (from the deposit guide) adds a debit card offering. Priya orders one; Nest Egg's issuer processor creates it, Nest Egg reports it through the Cards API the same day and activates it when Priya confirms receipt. Her coffee purchase is authorized at the processor, settles through the networks, appears in Nest Egg's Transactions file, and reconciles against Lead's settlement report for that cycle. ## **Objects involved** | **Object** | **Surface** | **Role in this flow** | **Reference** | | :- | :- | :- | :- | | Card | user | Your report of each card issued at your processor | [Cards](/products/cards/overview) | | Account | user | The deposit account the card spends against | [Accounts](/products/accounts/overview) | | Transaction | user | Card spend in your daily reporting | [Balances](/file-reference/balances-and-transactions/balances-schema) & [Transactions](/file-reference/balances-and-transactions/transactions-schema) | | Settlement accounts | core | Lead-managed accounts network settlement moves through | [Network Settlement](/products/network-settlement/overview) | ## **Before you start** * A working deposit integration [Launch a deposit program](/guides/store/launch-a-deposit-program) and an issuer-processor relationship. * **Use the Cards API** (Beta) for new programs; the [card file schema](/file-reference/card/schema) remains the path for existing file-integrated programs. * Card spend rides the same daily Transactions file as the rest of your activity — file-based today, with user transaction APIs as the planned successor ([Platform Evolution](/core-concepts/platform/platform-evolution)). ## **Reporting card issuance** Report each card at creation: `POST /v0/cards` `{ "account_id": "...", "form": "physical | virtual", "...": "..." }` **Decision point (physical cards):** report at creation and activate on customer confirmation — the report-then-activate pattern mirrors the card-in-hand reality; virtual cards typically report and activate together. ## **Keeping the lifecycle current** Use the dedicated activate/deactivate/close endpoints as the card's real-world state changes. Statuses describe *your report*: a card closed in error is correctable back to active — you're fixing the record, not reopening a card. Promptness matters; Lead's compliance picture depends on your reports. ## **Settlement and reconciliation** Spend settles at your processor and the networks; funds move through Lead's [network settlement](/products/network-settlement/overview) process. Consume the [network settlement reports](/file-reference/reports/network-settlement-reports) and reconcile each cycle against the card activity you reported — reconcile at least one full cycle end-to-end in test before launch. Please refer to [Network Settlement Reconciliation](/products/network-settlement/reconciliation) to understand expectations and methodology. ## **Reporting spend** Card transactions flow through your daily Transactions file alongside everything else — same schemas, same 6:00 a.m. CT deadline, same validation. ## **Getting started** With the deposit chain live in sandbox: report a card via the Cards API, round-trip its lifecycle (activate → deactivate → close → correct), include card transactions in a test Transactions file, and validate. Testing Network Settlement in sandbox is usually not feasible due to issuer processor and network limitations. Please reach out if you have questions ## **Handling exceptions** | **What happens** | **Signal** | **What to do** | | :- | :- | :- | | Card reported in error | Your own reconciliation | Correct via the status endpoints — reports are correctable, including closed → active. | | Settlement doesn't reconcile | [network settlement reports](/file-reference/reports/network-settlement-reports) vs. your reported activity | Investigate cycle-by-cycle; escalate to your Lead team with the report reference. | | Spend on a deactivated card | Your processor's controls | Authorization is your processor's domain — Lead's Card object is oversight, not an authorization switch. | ## **Testing this flow in sandbox** Deposit-chain coverage per [Launch a deposit program](/guides/store/launch-a-deposit-program). Card-specific sandbox coverage: see above. ## **Related** [Launch a deposit program](/guides/store/launch-a-deposit-program) · [Cards](/products/cards/overview) · [Network Settlement](/products/network-settlement/overview) · [Balances](/file-reference/balances-and-transactions/balances-schema) & [Transactions](/file-reference/balances-and-transactions/transactions-schema) · [Run a credit or charge card program](/guides/issue/credit-and-charge-card-program) *If something in this guide doesn't match what you see, contact your Lead team.* # Instant Loan Origination and Disbursement Source: https://docs.lead.bank/guides/lend/instant-loan-origination-and-disbursement Originate a term loan or line of credit, disburse instantly over FedNow, and run the daily servicing and receivables-purchase cycles. This guide walks through originating a term loan or line of credit — personal loans, BNPL, or other credit products — disbursing the proceeds instantly over the Instant Payments API, and the two operating cycles typically ran afterward: daily servicing reporting, and the daily purchase of the receivables Lead originates. It's for platforms that underwrite and service their own borrowers with Lead as the regulated lender of record. ## **How it works** Your borrower becomes an **Entity**; your underwriting decision becomes an **Application**; the borrower's legal relationship with Lead is an **Account** with the credit\_with\_underwriting capability; the loan's terms live on a **Balance**; drawing principal is a **Funding** — where real money is moved from a Lead GL to a Funding FBO; and the disbursement is an **instant payment** from that FBO to the borrower's external account. Because Lead is the lender of record, each Funding also creates a **receivable** — Lead's claim on the loan. After your program's hold period has passed, receivables are grouped into a daily **sale** that you purchase, moving the asset from Lead's balance sheet to yours. Origination is a per-loan flow; servicing reporting and the daily sale are program-level rhythms. ## **Example scenario** Lakeshore Lending offers small-dollar personal loans inside its budgeting app. Maya applies for \$2,000; Lakeshore approves her in-app, reports her personal information and the approval to Lead, opens her loan, draws the principal, and sends it to her checking account at her own bank over FedNow — Maya receives the money before she closes the app. The draw creates a receivable on Lead's books; after the hold period it rolls into a daily sale alongside that day's other loans, and Lakeshore purchases it from Lead. Maya's repayments are reported back to Lead through Lakeshore's daily servicing files. ## **Objects involved** | Object | Surface | Role in this flow | Reference | | - | - | - | - | | Entity | user | Maya, with Lakeshore's KYC/OFAC results attested | [Entity endpoints](/api-reference/endpoint/entity/create-an-entity) | | Application | user | The terminal underwriting decision | [Applications endpoints](/api-reference/endpoint/application/create-an-application) | | Account | user | Maya's credit relationship with Lead (credit\_with\_underwriting) | [Accounts endpoints](/api-reference/endpoint/account/create-an-account) | | Balance | user | The loan's terms and position (type: credit) | [Subledger Balance endpoints](/api-reference/endpoint/subledger-balance/create-a-subledger-balance) | | Funding | execution | Draws principal from a Lead GL into the Funding FBO | [Funding endpoints](/api-reference/endpoint/funding/create-a-funding) | | Funding FBO | core | The Lead-managed account the principal lands in | [Banking Infrastructure](/products/banking-infrastructure/overview) | | Instant Payment | execution | The disbursement to Maya's external account | [Instant Payments endpoints](/api-reference/endpoint/instant-payment/create-an-instant-payment) | | Daily sale (receivables) | execution *(file today)* | Your purchase of the receivables Lead originated | [Sales File schemas](/file-reference/sales/request-schema) | | Balance / Transaction reporting | user *(file today)* | Your daily servicing report — repayments, interest, fees | [Balance](/file-reference/balances-and-transactions/balances-schema) & [Transaction](/file-reference/balances-and-transactions/transactions-schema) File schemas | ## **Before you start** * Sandbox credentials with scopes covering entities, applications, accounts, subledger balances, fundings, and instant payments. Your Funding FBO exists from onboarding. * Note Instant Payments reaches FedNow-participating institutions today; RTP support is targeted for early Q4 2026 on the same API. Not every receiving bank participates. * **Two parts of this program run on files today.** Servicing is reported through the daily Balance and Transaction files, and the daily receivables sale runs as the Sales Request/Response file exchange — schemas for both in the [File Reference](/file-reference/balances-and-transactions/balances-schema). API successors are planned for both — user balance/transaction APIs and a sale API that tells you when a sale is generated ([Platform Evolution](/core-concepts/platform/platform-evolution)); the shape of each cycle is unchanged across the transition, and this guide will be updated as they ship. * The Accounts and Subledger Balance APIs used below will also be succeeded by their unified-model equivalents (user accounts and user balances — [Platform Evolution](/core-concepts/platform/platform-evolution)). ## **Integration steps** ### **Step 1: Create the borrower Entity** Report the borrower with your KYC/OFAC screening results attested. ```text theme={null} POST /v0/entities { "type": "individual"... } ``` ### **Step 2: Report the underwriting decision via Application** Applications are always reported in a terminal status — approved, declined, or canceled. Lead does not require you to report in-flight applications. Declines require the adverse-action fields. ```text theme={null} POST /v0/applications { "status": "approved"... } ``` ### **Step 3: Open the Account** ```text theme={null} POST /v0/accounts { "capabilities": ["credit_with_underwriting"], "application_id": "...", "entity_id": "..." } ``` Created in an active status, and references the Application object created in the prior step. *(Note: today this is the Account API; its unified-model successor is the User Account API — [Platform Evolution](/core-concepts/platform/platform-evolution).)* ### **Step 4: Define the loan using a Balance** **Decision point:** For non-revolving credit products, several terms are required up front: expected\_maturity\_date, max\_funding\_amount, term, and the repayment schedule.\ For revolving credit products, fewer terms are required up front. See more about the two structures at [The Balance & Funding Objects](/api-reference/endpoint/subledger-balance/create-a-subledger-balance). ```text theme={null} POST /v0/subledger_balances { "type": "credit", "structure": "non_revolving", "max_funding_amount": 200000, "...": "..." } ``` *(Note: the Subledger Balance API's unified-model successor is the User Credit Balance API — [Platform Evolution](/core-concepts/platform/platform-evolution).)* ### **Step 5: Draw the principal with Funding** Principal decomposes into external\_disbursement\_amount, withheld\_amount, and merchant\_origination\_fee\_amount. **Decision point:** Based on your product’s funds flows, you will use some subset of these three components. For many programs, the entire loan amount is submitted as external\_disbursement\_amount. ```text theme={null} POST /v0/fundings { "subledger_balance_id": "...", "external_disbursement_amount": 200000, "withheld_amount": 0, "merchant_origination_fee_amount": 0 } ``` Once Lead has made the funds available in your Funding FBO, you will receive a funding.posted webhook. When it fires, the principal is in your Funding FBO ready to disburse, and the receivable this draw creates on Lead's books enters your program's hold period. ### **Step 6: Check Instant Payment reach before promising instant funds to your end-user** ```text theme={null} POST /v1/instant_payments/check_availability { "routing_number": "..." } ``` **Decision point:** build this into the UX before the borrower chooses instant disbursement. If the borrower's bank can't receive, fall back to ACH from the same FBO — same funds, slower rail — rather than failing the loan. ### **Step 7: External disbursement** ```text theme={null} POST /v1/instant_payments { "amount": 200000, "debtor": { "account_id": "your Funding FBO" }, "creditor": { "...": "borrower's external account" } } ``` Design for finality: instant sends are irrevocable. Track two lifecycles — the payment's status to posted, then counterparty\_status for when the borrower's bank has actually credited the funds. Tell Maya "sent" and "delivered" separately. ### **Step 8: Purchase the day's receivables** Each business day, the receivables that have cleared your program's hold period are grouped into a single sale — the day's purchase of loans from Lead, priced per [how settlement amounts work](/products/funding-and-receivables/sales-settlement-amount) (principal plus imputed interest for the hold period). Today you acknowledge the purchase through the Sales Request/Response file exchange over SFTP ([Sales File schema](/file-reference/sales/request-schema)); the settlement amount moves from your settlement account. This cycle is not optional — it's how the loans you originate become yours — so build it as a daily operational rhythm from day one, including the empty-day case. **Note: upcoming Sale API** The planned Sale API replaces the file exchange with a daily sale object you review and accept in a single call, with acceptance settling the funds ([Platform Evolution](/core-concepts/platform/platform-evolution)). The cycle's shape — daily grouping, whole-day purchase, settlement — is unchanged; build your reconciliation against the day's sale as a unit, not against file mechanics. For funding-based programs the API successor lands together with the unified-model migration. ## **Handling exceptions** | What happens | Signal | What to do | | - | - | - | | Application declined | Your own decision | Report it with adverse-action fields via Application — declines are reported too, not skipped. | | Instant payment rejected | status → rejected; rejection.rejected\_by | Lead, network, or counterparty — retry/repair logic differs by which. | | Sent in error / fraud-induced send | Your own decision | POST /v1/instant\_payments//request\_return; the only recourse, and it's a request, not a recall. | | Insufficient funds for the day's receivable sale | Settlement failure on the sale cycle | Fund your settlement account and re-run the acknowledgment; the day's purchase settles whole, so treat settlement-account funding as a daily pre-check, not a reaction. | ## **Testing this flow in sandbox** The origination chain runs end-to-end in sandbox: POST /v0/fundings//advance to simulate the funding posting, and the five instant-payment simulators for the disbursement leg including all three return-request outcomes ([Environments & testing](/core-concepts/platform/environments-and-testing)). Reconcile a sandbox run using the payment identifiers (end\_to\_end\_id, transaction\_id, uetr). Servicing files can be validated against the [File Reference](/file-reference/overview) schemas before production submission. ## **Related** [Balances & Transactions](/products/balances-and-transactions/overview) (servicing) · [Funding & Receivables](/products/funding-and-receivables/overview) · [Instant Payments](/products/instant-payments/overview) · [Originate Your First Loan](/get-started/quickstart/originate-your-first-loan) (full payloads) · [Run a credit or charge card program](/guides/issue/credit-and-charge-card-program) (revolving credit and card receivables) · [Executing vs. reporting](/core-concepts/platform/executing-vs-reporting) *If something in this guide doesn't match what you see, contact your Lead team.* # Collecting and Disbursing ACH Payments Source: https://docs.lead.bank/guides/move/collecting-and-disbursing-ach-payments Collect funds from one party and pay them out to another over ACH, including the returns and reversals you'll handle along the way. This guide walks through the most common money-movement pattern on Lead: collect funds from one party, then pay them out to another. Rent collection, invoice payment, marketplace payouts, and bill pay are all versions of this flow. The guide covers three things: * The two ways to collect: debit the payer's account yourself, or give the payer a dedicated account number to send to. * When to release the payout, since a collected payment can still be returned after it posts. * How to handle returns and reversals: payments the other bank sends back, payments you need to send back, and how to undo your own mistakes. ## How it works Your program's funds sit in a core account at Lead (your FBO or operating account). Collection works one of two ways. If you pull, you originate an ACH debit against the payer's external account. If the payer pushes, their bank sends an ACH credit to the dedicated Account Number you provisioned for them (attached to your core account, attributed to the payer via `entity_id`). The payout is an ACH credit you originate to the payee's external account. One concept to get right early: on the `ach` object, `direction` tracks who originated the entry, not which way the money moved. A pulled debit is an **outgoing** entry that brings money in; a pushed payment is the only **incoming** entry in this flow. Return windows and correction rights follow the entry's direction, not the money's, which is why the guide keeps the two separate. Every origination goes out under an originator: the identity on the payer's bank statement. That identity is either your program's default, configured at onboarding, or a per-client originator bound to the Account Numbers you originate from. The collection and payout legs are independent payments with independent lifecycles and return windows, and the key design decision is when to release the payout. Unlike wires, ACH is built for correction: a payment you originated can come back as a return (the other bank sends it back, within code-specific windows); a payment you received can be returned by you; and a payment you originated in error can be reversed by you within a short window. Each is a distinct flow with its own clock. ## Example scenario RentRelay collects rent for landlords. Tenant Marcus's rent comes in one of two ways: RentRelay originates an ACH debit for \$1,800 against his checking account, or Marcus's own bank pushes \$1,800 to the dedicated account number RentRelay provisioned for him. Either way the funds land on RentRelay's core account and attribute to Marcus. Because RentRelay collects on behalf of its property-manager clients, it creates an originator per client and originates each client's payments from Account Numbers carrying that client's originator, so Marcus's statement reads "MAPLE PROPERTIES," the name on his lease, rather than a platform he's never heard of. RentRelay waits out its risk window, then originates an ACH credit for \$1,800 (less its fee) to landlord Dana's bank account. Marcus and Dana never open accounts anywhere new. The correction flows all have RentRelay stories too: Marcus's debit comes back R01 (insufficient funds) and RentRelay retries it after payday; a push arrives on a number belonging to a tenant who moved out last month, and RentRelay returns it; a duplicate payout goes to Dana, and RentRelay originates a reversal the same afternoon; and eight weeks later, a different tenant disputes a debit as unauthorized, and the return arrives long after the landlord was paid. ## Objects involved | Object | Surface | Role in this flow | Reference | | - | - | - | - | | Core account | core | Where collected funds sit between the legs | \[Banking Infrastructure] | | Account Number | core | Per-payer routable address on your core account, attributed via `entity_id`; also where origination identity binds via `ach_controls.originator_id` | \[Account Numbers endpoints] | | Entity | user | The payer/payee, represented per your program's structure | \[Entity endpoints] | | `ach` (outgoing debit) | execution | Pull collection from the payer's external account | \[ACH endpoints] | | `ach` (incoming credit) | execution | Push collection arriving on the payer's account number | \[ACH endpoints] | | `ach` (outgoing credit) | execution | The payout to the payee's external account | \[ACH endpoints] | | Return | execution | A payment sent back: by the other bank on your originations, or by you on incoming payments | \[ACH returns] | | Reversal | execution | Your correction of an erroneous origination, within the reversal window | \[ACH returns] | | Originator | configuration | The identity payments send under: your program's default, or per-client via the API, bound to sending Account Numbers | \[Originators] | ## Before you start Sandbox credentials with ACH, entity, and account-number scopes; your core account's `account_id` from onboarding. Your program's default origination identity is configured at onboarding. You only integrate the \[Originators] API if you originate on behalf of your own clients (the Step 2 decision). There is no separate originator scope; confirm access with your Lead team when you request approval for the Originator API. For pull collection, authorization to debit the payer is yours to obtain and retain. Returns for unauthorized debits are the expensive failure mode, and your authorization records are what a dispute turns on. This flow is fully API-based. (Under the unified model, account numbers will attach to balances rather than accounts; same concept, typed IDs; \[Platform Evolution].) ## Integration steps ### Step 1: Choose how each payment comes in For any given collection there are exactly two options: * **You pull the payment.** You originate an ACH debit against the payer's account, under an authorization you hold. You control timing and amount, which fits scheduled obligations like rent. The risk: the payer's bank can return the debit after it appears settled. * **The payer pushes it.** They send from their own bank to the dedicated account number you provisioned for them. This nearly eliminates unauthorized-return risk and fits invoice-style "pay when ready" flows. The cost: you wait on the payer. This is not a program-wide setting; choose per collection type. Most programs pull their scheduled payments and accept pushes for one-off ones. ### Step 2: Decide whose name the money moves under: the default identity, or per-client originators Every origination is sent under an originator: the identity that carries the company name onto the counterparty's bank statement, along with the SEC codes and limits Lead enforces on that identity. **Decision point:** there are two models, and most programs only ever need the first. **Program-default (no Originators integration).** Your program originates under a single identity, your own, configured by Lead at onboarding. Payments pick it up automatically; you never call the Originators endpoints. If everything you originate should say your name, this is you: skip to Step 3. **Per-client originators (integrate the API).** You originate on behalf of your own clients (property managers, merchants, employers) and each should appear under their own name. The identity does not ride on the payment call; it binds to the Account Numbers you originate from. Three moves: 1. Create an originator per client and get it to `active`: ```text theme={null} POST /v0/originators { "entity_id": "the client's entity", "account_id": "...", "company_name": "MAPLE PROPERTIES", "ach": { "allowed_sec_codes": ["PPD"], "limits": { "...": "..." } } } ``` 2. Provision the Account Number(s) you will originate that client's payments from (on your core account, per Step 3), and set the client's originator on each: `ach_controls.originator_id`, at creation or via update (\[Payment Controls]). 3. Originate that client's pulls (Step 4) and payouts (Step 6) from those Account Numbers. Entries sent from them carry the client's `company_id` and `company_name` in the batch header, subject to the originator's `allowed_sec_codes` and limits. This looks like a branding decision, but it is really a returns decision: the statement descriptor is what the payer sees, and an unrecognized descriptor is a leading driver of the R10 unauthorized-return disputes in Step 7. "MAPLE PROPERTIES" on Marcus's statement, matching the name on his lease and his authorization, generates fewer disputes than a platform name he's never heard of. If your payers authorized a client of yours rather than you, per-client originators aren't cosmetic; they keep the descriptor consistent with the authorization. ### Step 3: Provision a dedicated Account Number per payer (push mode) ```text theme={null} POST /v1/account_number { "account_id": "your core account_id", "entity_id": "the payer's entity_id", "...": "..." } ``` The `account_id` is your core account's: account numbers attach to the core account, never to a user Account, with the payer carried on `entity_id` (\[Object Model]). Assign and activate per the \[Account Number lifecycle]; the number can't transact until `active`. Incoming funds attribute to the payer automatically by which number they arrived on; this attribution is the whole point of per-payer numbers. Use per-number \[controls] to scope what each address accepts (e.g. incoming ACH only), and cancel numbers when the relationship ends. A retired tenant's number left active is how Step 8's misdirected-push case happens. **Decision point:** one number per payer 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 each. ### Step 4: Receive the push (or originate the pull) **Push:** handle `ach.posted` on incoming payments; attribute by account number. In sandbox: ```text theme={null} POST /v1/simulate/ach/incoming_ach { "account_number_id": "Marcus's dedicated number", "transaction_type": "credit", "amount": 180000, "currency_code": "USD", "sec_code": "PPD", "statement_descriptor": "RENT MAY", "sender_name": "MARCUS BAKER", "sender_company_id": "1234567890", "sender_routing_number": "021000021" } ``` **Pull:** originate the debit, from the Account Number that carries the right originator if you're on the per-client model from Step 2: ```text theme={null} POST /v1/ach { "account_number_id": "...", "transaction_type": "debit", "amount": 180000, "currency_code": "USD", "delivery_type": "next_business_day", "sec_code": "PPD", "statement_descriptor": "RENT MAY", "counterparty": { "name": "Marcus Baker", "routing_number": "...", "account_number": "...", "account_type": "checking" } } ``` **Decision point, same-day vs. standard windows:** same-day costs more and compresses your operational day but shortens time to (apparent) settlement. Choose per leg via `delivery_type`; many programs collect standard and pay out same-day. Cutoffs and settlement times: \[ACH Timing & Availability]. ### Step 5: Decide how long to hold before paying out Posted is not final on a pulled debit: insufficient-funds returns typically arrive within two banking days, and certain consumer unauthorized returns can arrive up to 60 calendar days later. **Decision point (the core one):** your hold policy trades payee experience against return risk. Hold 2 to 3 banking days to clear the NSF window, pay out immediately and absorb returns as a business cost, or tier by payer history and collection mode (pushed funds warrant shorter holds than pulled funds, since the payer initiated them). ### Step 6: Pay out ```text theme={null} POST /v1/ach { "account_number_id": "...", "transaction_type": "credit", "amount": 180000, "currency_code": "USD", "delivery_type": "same_business_day", "sec_code": "PPD", "statement_descriptor": "RENT PAYOUT", "counterparty": { "name": "Dana Whitfield", "routing_number": "...", "account_number": "...", "account_type": "checking" } } ``` Handle `ach.posted` on this leg to mark the payout delivered. ### Step 7: Handle returns on payments you originated, by code, not generically When the other bank returns your origination, the return carries a return code, and the code determines your next move. A single "payment failed" handler is the mistake to avoid (\[ACH returns] carries the full code reference): | Code family | What it means | Your move | | - | - | - | | R01 / R09 (insufficient / uncollected funds) | The money wasn't there | Retriable. Nacha permits up to two retries of a returned entry; time them sensibly (after payday beats tomorrow morning). | | R02 / R03 / R04 (account closed / not found / invalid) | The details are wrong or dead | Don't retry as-is. Fix the details, check for a NOC, or go back to the counterparty for new ones. | | R10 / R11 (unauthorized / not per authorization) | The payer disputes the debit | Stop. Do not re-originate on the existing authorization. This is a dispute, not a failure: pull your authorization records, and re-collect only on a fresh authorization. Repeated unauthorized returns are also a program-health metric Lead monitors; if your dispute rate clusters on payers who don't recognize the descriptor, revisit the Step 2 decision. | | R29 (corporate not authorized) | Business-account analog of R10 | Same discipline; business rules and shorter windows apply. | Returns of your credit originations (the payout leg) are simpler: funds come back; fix and re-originate per the exceptions table below. ### Step 8: Return an incoming payment you received Sometimes money arrives that you shouldn't keep: a push to a canceled or unrecognized account number, a duplicate, or a debit posted against your account that you didn't authorize. Return it within the return window (two banking days for most cases; 60 calendar days plus a WSUD for unauthorized consumer debits) rather than letting it sit: ```text theme={null} POST /v1/ach/{ach_id}/return { "return_code": "R23" } ``` The `return_code` must fit the case (\[ACH returns] maps codes to situations and deadlines). **Decision point:** define the auto-return cases up front. Unattributable pushes and duplicates should return on a runbook clock, not accumulate in a suspense process. Unexplainable funds are a compliance problem that compounds with age. ### Step 9: Reverse your own mistakes, fast When you originated in error (a duplicate payout, wrong amount, or wrong account) ACH gives you a correction tool the wire rail doesn't: the reversal, an offsetting entry you originate within five banking days of settlement, and only for those three error types. It is not a dispute mechanism or a change-of-mind button: ```text theme={null} POST /v1/ach/{ach_id}/reverse { "reversal_reason": "duplicate" } ``` A reversal is best-effort. It pulls from the receiver's account, and if the funds are gone it can itself be returned. A same-afternoon reversal of a duplicate payout usually succeeds; a day-four reversal is a coin flip. Notify the receiver that a reversal is coming (Nacha expects it, and surprise debits generate disputes). Past five banking days, the reversal window is closed and recovery is a conversation, not a rail operation. ### Step 10: Keep counterparty details current Handle NOCs (\[ACH NOCs]) on originated legs. A NOC means the receiving bank corrected the details you used; Lead normalizes it into the `correction` object on the original entry, and the `ach.corrected` webhook tells you it arrived. Use the corrected details on the next origination; Lead may reject re-use of the old details with the `previously_corrected` rejection reason. ## Handling exceptions Failures on the two legs interact; handle them as combinations: | Collection leg | Payout leg | What it means | What to do | | - | - | - | - | | Pulled debit returned before payout sent | Not yet sent | The common protected case | Don't send the payout; notify the payer; retry per the Step 7 code table. | | Pulled debit returned after payout posted | Posted | You've paid out funds you no longer have | Reversal is not available; the payout wasn't erroneous when sent. Recover from the payer through your own process; this exposure is what your Step 5 hold policy prices. | | Pulled debit returned R10, weeks later | Long since posted | An unauthorized-debit dispute landed outside any hold window | Funds claw back from your account. Stop collection on that authorization, work the dispute with your records, recover out of band. No hold policy prices a 60-day window; payer-quality controls and a recognizable descriptor (Step 2) do. | | Pushed payment can't be attributed | (none) | Funds arrived on an unknown or canceled number | Return it (Step 8) on your runbook clock. | | Incoming reversal hits your account | (none) | A counterparty is correcting their own erroneous push | It posts like any incoming debit; reconcile it against the original credit. If it doesn't correspond to one, return it. | | Posted | Payout returned (R02/R03) | Payee's details wrong or account closed | Funds come back; check for a NOC, fix, re-originate. | | Posted | Duplicate/wrong payout, caught same-day | Your origination error | Reverse it (Step 9) immediately; this is the reversal's home case. | | Posted | Your reversal is returned | The payee's funds were already gone | The rail is exhausted; recover through your own process with the payment identifiers. | | NOC on either originated leg | (none) | Details corrected, payment still succeeded | Update stored details before the next cycle. | ## Testing this flow in sandbox If you're on the per-client model, create a sandbox originator first, activate it, set it on a sandbox Account Number's `ach_controls`, and confirm entries originated from that number carry it. Simulate the push leg with `POST /v1/simulate/ach/incoming_ach` against a dedicated account number and verify your attribution logic. Originate a pull debit and a payout credit with `POST /v1/ach`; outgoing entries stay in `scheduled` until you advance them with `POST /v1/simulate/ach/{ach_id}/advance` (\[ACH Sandbox Testing]). The correction machinery tests as follows. Returning an incoming payment and reversing your own origination are real endpoints (`/return`, `/reverse`) and work in sandbox directly; no simulator is involved. Counterparty returns of your originations use `POST /v1/simulate/ach/{ach_id}/incoming_return`; exercise the code families in Step 7, including an R01-then-retry sequence, an R10 (verify your handler stops collection rather than retrying), and a return arriving after the payout leg has been sent, which is the scenario your hold policy exists for. For the reversal-returned outcome, call the `incoming_return` simulator against the reversal's own `ach_id` (a reversal is an ordinary outgoing entry). \[VERIFY in a live sandbox run before publish: the reversal-returned sequence above.] Per the sandbox-honesty convention: a sandbox transfer that trips a validation rule enters `under_review` and stays there permanently (manual review is not simulated). If a test entry gets stuck, create a new one; see \[ACH Sandbox Testing] for avoiding review triggers. # Run an Escrow Flow Over Wires Source: https://docs.lead.bank/guides/move/escrow-flow-over-wires Receive, verify, disburse, and return wires, using dedicated account numbers per transaction. This guide walks through how to operate an escrow or trust-style flow using Lead’s wire rail: a payer funds a transaction by wire, you hold the funds until the required conditions are met, and then disburse them by wire. Wires are well suited for large, time-sensitive payments where same-day settlement and finality are important. This guide covers the full flow, including receiving and verifying funds, disbursing at closing, returning incoming wires, and handling return requests. ## **How it works** Funds are held in your **core account** at Lead. For each transaction, you provision a dedicated **Account Number** under the core account and associate it with the payer using `entity_id`. This allows you to identify which deal an incoming wire belongs to based on the receiving account number, rather than relying on memo fields. Both incoming and outgoing payments are represented as wire objects. Wires submitted before the cutoff generally settle the same business day. Once a wire is posted, it cannot be reversed. Funds can only be sent back through a new return wire. This guide covers the key escrow flows: receiving funds, disbursing funds, returning an incoming wire, and sending and responding to return requests. ## **Example scenario** Keystone Escrow handles residential closings. **Setup:** For the 14 Maple St. purchase, Keystone provisions a dedicated account number attributed to buyer Elena and puts the routing details on her wire instructions. **Funding:** Elena's bank wires \$85,000. The wire lands on Keystone's escrow account, identified by the account number. Keystone verifies the originator and amount against the file before treating the deal as funded. **Closing:** Keystone wires the payoff to the seller's lender and the net proceeds to the seller. **Deal falls through:** Inspection kills the deal. Keystone returns Elena's \$85,000 by wire. **Fraud:** Elena was tricked by a spoofed email into wiring twice. Her bank sends a return request to Keystone. **Disbursement error:** Keystone sends the payoff to the wrong account and must send a return request. ## **Objects involved** | Object | Surface | Role in this flow | Reference | | - | - | - | - | | Core escrow account | core | The Lead-managed account all deal funds sit in | [Banking Infrastructure](/products/banking-infrastructure/overview) | | Account Number | core | Per-deal routable address, attributed to the payer via entity\_id | [Account Numbers endpoints](/api-reference/endpoint/account-number/create-an-account-number) | | Entity | user | Elena (and other deal parties your program represents) | [Entity endpoints](/api-reference/endpoint/entity/create-an-entity) | | Wire (incoming) | execution | The buyer's funding wire | [Wires endpoints](/api-reference/endpoint/wire/create-a-wire-v1) | | Wire (outgoing) | execution | Closing disbursements or return wires | [Wires endpoints](/api-reference/endpoint/wire/create-a-wire-v1) | | Return request | execution | The ask, in either direction, to send posted funds back | [Wires - return requests](/api-reference/endpoint/wire/request-return-for-wire-v1) | ## **Before you start** * Sandbox credentials with wire, entity, and account-number scopes, plus the `account_id` for your core escrow account provided during onboarding. * Build on the current wire API version. Existing integrations should read [wire V2 migration](/products/wire/v2-migration) first. * Wires run on business days with same-day settlement inside Lead's published cutoffs — see [wire windows and cutoffs](/products/wire/processing-windows). A disbursement initiated after cutoff moves the next business day, which for a contractual closing date is an important fact to plan around. * Domestic Fedwire is the focus here. USD international wires use the same API to support cross-border payments. See [international wires](/products/wire/international-wires) for more details. * If your program represents deal parties as customers with reported balances, the daily reporting obligations apply unchanged. This guide covers only the wire mechanics. ## **Integration steps** ### **Step 1: Provision a dedicated account number for each deal** Create an account number under your core escrow account and associate it with the entity funding the deal. ```text theme={null} POST /v1/account_number { "account_id": "your core escrow account_id", "entity_id": "Elena's entity_id", "...": "..." } ``` The `account_id` is the identifier of your **core** account. The entity\_id identifies the party associated with the account number. Account numbers are always created under a core account, not a user Account. See [Object Model](/core-concepts/platform/object-model) for more details. Once created, assign and activate the account number following the [Account Number lifecycle](/products/account-number/statuses), then provide its routing and account numbers in the wire instructions for the deal. For escrow, we recommend using a unique account number for each deal. This makes it easier to attribute incoming funds to the correct deal and retire the account number when the deal closes. For recurring counterparties, a dedicated account number per party may be more appropriate. Finally, configure the account number [controls](/products/account-number/controls) to accept incoming wires only. The account number used to fund the deal should not accept ACH payments. ### **Step 2: Receive and verify the funding wire** When the incoming wire is posted, Lead sends a `wire.posted` event confirming that the funds have arrived. The account number that received the wire identifies the associated deal. Before treating the deal as funded, verify the incoming wire against the expected funding details, including: * Originator information * Funding amount * Receiving account number Define how mismatches should be handled before going live. For example, an unexpected originator, duplicate wire, or incorrect amount may require the wire to be returned rather than held in the escrow account. See Step 4 for the return flow. In Sandbox, use the incoming wire simulator to test this flow. See [Simulate Incoming Wire](/api-reference/endpoint/simulation/simulate-incoming-wire) for details. ### **Step 3: Disburse at closing** When the deal is ready to close, initiate an outgoing wire from the deal’s account number to the beneficiary. ```text theme={null} POST /v1/wires { "amount": 8500000, "debtor": { "account_number_id": "the deal's account number" }, "creditor": { "...": "beneficiary bank and account details" }, "...": "..." } ``` Before sending the wire, independently verify the beneficiary’s payment instructions. For example, confirm any instructions received by email using a known phone number or another trusted channel. This is especially important when payment instructions have changed. Once a wire has been sent, it cannot be reversed. If funds are sent incorrectly, you can request a return, but the receiving financial institution is not required to return them.\ Track the wire until it reaches `posted` and retain the wire identifiers as part of your closing records. ##### **Plan around wire cutoffs** Initiate closing disbursements early enough to meet the [cutoff](/products/wire/processing-windows). A wire initiated after cutoff will be sent the next business day, which can affect time-sensitive closing obligations. ### **Step 4: Return a wire you received** If the deal falls through or the funding wire fails the verification in Step 2, return the funds to the originator. Use the wire return flow to return the funds and reference the original incoming wire. See [Return a Wire](/api-reference/endpoint/wire/return-a-wire-v1) for API details. Once the deal is complete and the account number is no longer needed, cancel it to prevent additional funds from being sent to the closed deal. ### **Step 5: Send a return request** If you sent a wire in error, for example to the wrong beneficiary, for the wrong amount, or as a duplicate, you can request that the receiving financial institution return the funds. ```text theme={null} POST /v1/wires/{id}/request_return { "...": "reason and reference details" } ``` Track the return request through its status and webhooks. A return request does not move funds, and an accepted request does not guarantee that the funds will be returned. Funds are only returned when the receiving financial institution sends a return wire. For this reason, submit the return request as soon as you identify the error. ### **Step 6: Respond to incoming return requests** If the sending financial institution requests the return of a wire you received, you’ll receive a return request with a deadline for response. Review the request based on the status of the funds and your established policies. For example, whether the funds are still available or have already been disbursed may affect how you respond. Respond to the request through the API before the deadline. Because return requests are time-sensitive, define your review process before launch so your team can respond consistently and on time. ## **Handling exceptions** | What happens | Signal | What to do | | - | - | - | | Outgoing wire rejected | wire status → rejected | Review the wire’s error code or rejection reason, correct the underlying issue, then resubmit if appropriate. | | Inbound wire matches no deal | Your Step 2 verification | Return the wire (Step 4) if you cannot identify or verify the intended recipient of the funds. | | Amount doesn't match the expected funding | Step 2 verification | Review the discrepancy and handle it according to your established funding policy. If the wire needs to be returned, follow Step 4. | | Your return request is declined | Return-request status | Review the decline reason to understand why the request was rejected and determine the appropriate next steps. | | Return request arrives on disbursed funds | Incoming request notification | Respond according to your policy by the deadline. | | Disbursement misses cutoff | [cutoffs](/products/wire/processing-windows) | The wire will be sent the next business day. Account for cutoff times when planning time-sensitive disbursements. | ## **Testing this flow in sandbox** Before going live, test the key parts of your escrow flow in Sandbox: * Simulate an incoming wire to a deal account number and verify that it is attributed correctly. * Create an outgoing wire and test its lifecycle through `posted`. * Test returning an incoming wire. * Test sending and responding to return requests. # Guides Source: https://docs.lead.bank/guides/overview End-to-end walkthroughs for building on Lead — deposit programs, card programs, lending, payments, and escrow — organized by what you're launching. End-to-end walkthroughs for building on Lead, organized by what you're launching. Each guide composes the [Products](/products/overview) pieces for its scenario — program and compliance requirements included — and links to the underlying pages for depth. **Store — deposit accounts and customer money.** Represent customers as [Entities](/products/entity/overview), open deposit-capability [Accounts](/products/accounts/overview), attach [Account Numbers](/products/account-number/overview), move money over the rails, report [Balances & Transactions](/products/balances-and-transactions/overview). → [*Launch a Deposit Program*](/guides/store/launch-a-deposit-program) **Move — payments-led programs.** Disbursements, payouts, and money-in flows on any rail. → [*Collecting and Disbursing ACH Payments*](/guides/move/collecting-and-disbursing-ach-payments) · [*Run an Escrow Flow Over Wires*](/guides/move/escrow-flow-over-wires) **Lend — credit products.** Report the underwriting decision ([Applications](/products/applications/overview)), open a credit-capability [Account](/products/accounts/overview), define terms on a credit [Balance](/products/lending/balance-object), draw principal with [Funding](/products/lending/funding-object), service via [Balances & Transactions](/products/balances-and-transactions/overview), and purchase the receivables Lead originates ([Receivables & the Daily Sale](/products/lending/receivables-and-the-daily-sale)). → [*Instant Loan Origination and Disbursement*](/guides/lend/instant-loan-origination-and-disbursement) **Issue — card programs.** Report issuance via [Cards](/products/cards/overview), settle spend through [Network Settlement](/products/network-settlement/overview), report activity in [Balances & Transactions](/products/balances-and-transactions/overview). → [*Launch a Debit Card Program*](/guides/issue/debit-card-program) · [*Run a Credit and Charge Card Program*](/guides/issue/credit-and-charge-card-program) # Launch a Deposit Program Source: https://docs.lead.bank/guides/store/launch-a-deposit-program Open deposit accounts your customers hold at Lead, move their money, and report their ledger. 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](/core-concepts/platform/money-movement); 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](/core-concepts/platform/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** | **Object** | **Surface** | **Role in this flow** | **Reference** | | :- | :- | :- | :- | | Entity | user | Priya, with your KYC/OFAC results attested | [Entity](/api-reference/endpoint/entity/create-an-entity) | | Account | user | Priya's deposit product (capability: deposit) | [Accounts](/api-reference/endpoint/account/create-an-account) | | Program FBO | core | The Lead-managed pooled account customer funds sit in | [Banking Infrastructure](/products/banking-infrastructure/overview) | | Account Number | core | Routable address attached to the FBO, attributed to Priya via `entity_id` | [Account Numbers](/api-reference/endpoint/account-number/create-an-account-number) | | Balance / Transaction | user | Your daily report of Priya's position and activity | [Balances](/file-reference/balances-and-transactions/balances-schema) & [Transactions](/file-reference/balances-and-transactions/transactions-schema) | | ach\_payment (etc.) | execution | Money movement in and out | [Payment Rails](/core-concepts/platform/money-movement) | ## **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](/file-reference/balances-and-transactions/balances-schema) & [Transactions](/file-reference/balances-and-transactions/transactions-schema), [SFTP setup](/file-reference/sftp-setup). User transaction and balance APIs are planned successors ([Platform Evolution](/core-concepts/platform/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](/core-concepts/platform/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", "...": "..." }` > [!NOTE] > > ##### **The account\_id here is the core account's** Both the user Account (Step 2) and your core FBO have `account_`-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](/core-concepts/platform/object-model), "How the Two Surfaces Connect"). Then assign and activate per the [Account Number lifecycle](/products/account-number/account-number-object) — 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](/products/account-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](/api-integrations/using-the-api/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](/core-concepts/platform/money-movement). **Decision point:** rail choice is a product decision — [Money Movement](/core-concepts/platform/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](/file-reference/overview) schemas. Cadence and semantics: [Balances](/file-reference/balances-and-transactions/balances-schema) & [Transactions](/file-reference/balances-and-transactions/transactions-schema). ## **Handling exceptions** | **What happens** | **Signal** | **What to do** | | :- | :- | :- | | Incoming ACH returned | Return per [ACH returns](/products/ach/exceptions) | Debit your ledger; notify the customer. Certain consumer unauthorized returns can arrive weeks after posting — hold policies are a product decision. | | NOC received | [ACH NOCs](/products/ach/statuses) | Update counterparty details before your next origination. | | Payment held for review | status under\_review | Monitor; don't promise availability until posted. | | Inbound payment can't be attributed | Your reconciliation of the FBO | Check which account number it arrived on and its entity\_id; unattributable funds are an ops process to define before launch. | | File fails validation | [file delivery errors](/file-reference/delivery/errors) | Correct and resubmit before the deadline. | ## **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](/core-concepts/platform/environments-and-testing). Exercise at least one return path per rail and validate files against realistic volume before production submission. ## **Related** [Object Model](/core-concepts/platform/object-model) (the two surfaces — read this if Step 3's warning surprised you) · [Balances](/file-reference/balances-and-transactions/balances-schema) & [Transactions](/file-reference/balances-and-transactions/transactions-schema) · [Account Numbers](/products/account-number/overview) · [Payment Rails](/core-concepts/platform/money-movement) · [Make Your First Payment API Call](/get-started/quickstart/make-your-first-payment-api-call) · [Launch a Debit Card Program](/guides/issue/debit-card-program) · [Reports Lead Delivers](/file-reference/reports/platform-reconciliation) *If something in this guide doesn't match what you see, contact your Lead team.* # The Application Object Source: https://docs.lead.bank/products/applications/application-object Field-level reference for the Application object with an example payload. An Application is your report of a final underwriting decision. It is always in one of three terminal statuses: `approved`, `declined`, or `canceled`. ## Application Object | **Attribute** | **Type** | **Description** | | :- | :- | :- | | `id` | string | Unique identifier for the application. Prefixed with `application_`. | | `client_application_id` | string | Read-only identifier you assigned. Present only for applications created via file upload; omitted for applications created through the API, which are identified solely by their server-generated `id`. | | `created_at` | timestamp | Lead server-generated ISO 8601 timestamp when the application was created. | | `updated_at` | timestamp | Lead server-generated ISO 8601 timestamp when the application was last updated. | | `status` | string | Terminal state of the application: `approved`, `declined`, or `canceled`. **There is no in-progress state**, and all three outcomes must be reported. Status cannot be changed after creation. If you reported the wrong status, contact your Technical Account Manager. | | `entities` | object | Contains information about the account holder and authorized signers. See below. | | `details` | object | Contains product, credit, and adverse action notice details. See below. | | `decision` | object | Contains information about the underwriting decision. See below. | | `documents` | array | Document references associated with the application. See below. | | `metadata` | object | Arbitrary key-value pairs for storing additional information. | ### `entities` (sub-object) | **Attribute** | **Type** | **Description** | | :- | :- | :- | | `account_holder_type` | string | **Derived, never set directly.** `consumer` if all account holders are individuals; `commercial` if all are businesses or sole proprietors. The one-category rule applies: business and sole proprietor may combine, individual and business may not. | | `account_holders` | array | Entity IDs that are account holders on the application. Returned on the Application object. | | `authorized_signers` | array | Entity IDs that are authorized signers on the application. Returned on the Application object. | | `authorized_users` | array | **Request-only.** Entity IDs to associate as authorized users. Accepted on creation but **not returned** on the Application object — retrieve it from `GET /v0/applications/{id}/entity_relationships`. | Maximum 20 entities per relationship type. > [!TIP] > > The `entities` object gives you the entity IDs for account holders and authorized signers. For the full relationship records — including authorized users, which the Application object does not return — call `GET /v0/applications/{id}/entity_relationships`. It lists every relationship with its `relationship_type`: `account_holder`, `authorized_signer`, or `authorized_user`. ### `details` (sub-object) | **Attribute** | **Type** | **Description** | | :- | :- | :- | | `product_name` | string | **Required.** Your internal product name. This tells Lead's Due Diligence team which product this application opens an account for if approved. Use your stable internal name. | | `credit` | object | **Required on every application**, including non-credit products. Credit-specific properties. See `details.credit` below. | | `adverse_action_notice` | object | Adverse action notice details. **Required when `status` is `declined`.** See below. | ### `details.credit` (sub-object) | **Attribute** | **Type** | **Description** | | :- | :- | :- | | `is_secured` | boolean | **Always required.** `true` if the product is secured (collateral attached); `false` otherwise. | | `is_mla` | boolean | **Always required.** `true` if the applicant is subject to the Military Lending Act; `false` otherwise. | | `currency` | string | **Required.** ISO 4217 currency code for the application (e.g., `USD`). | | `underwriting_grade` | string | Your internal underwriting grade, mapped to your scoring framework. Accepts any string. **Required when `status` is `approved` or `declined`.** | | `limit` | integer | The credit limit assigned to the applicant, in minor units (e.g., cents). **Required when `status` is `approved`.** | | `max_limit` | integer | The maximum credit limit the applicant was approved for based on original underwriting, in minor units. **Required when `status` is `approved`.** | | `report` | object | Credit bureau report data. Optional for most programs. See `details.credit.report` below for its conditional requirements. | ### `details.credit.report` (sub-object) The credit report is optional for most programs, but when you supply one, `pulled_at` and `source` are always required, and **exactly one of `score` or `non_score_value` must be provided** — the two are mutually exclusive. Programs whose underwriting policy requires credit bureau data on every approval have an additional check enabled, which requires the report on approved applications. See [Validation Rules and Errors](/products/applications/validations). | **Attribute** | **Type** | **Description** | | :- | :- | :- | | `score` | integer | Credit score returned by the bureau. Supported range: 300–850. Mutually exclusive with `non_score_value`. | | `non_score_value` | string | The state of the credit file when no numeric score is available: `unestablished` or `frozen`. Mutually exclusive with `score`. | | `pulled_at` | timestamp | ISO 8601 timestamp when the credit report was pulled. Required whenever a report is supplied. | | `source` | string | Credit bureau that issued the report: `equifax`, `experian`, or `transunion`. Required whenever a report is supplied. | ### `details.adverse_action_notice` (sub-object) Required when `status` is `declined`. All three fields are required when the object is present. | **Attribute** | **Type** | **Description** | | :- | :- | :- | | `delivered_at` | timestamp | ISO 8601 timestamp when the adverse action notice was sent to the applicant. | | `reason` | string | The reason stated in the adverse action notice. | | `delivery_method` | string | How the notice was delivered: `email`, `text`, or `other`. | ### `decision` (sub-object) | **Attribute** | **Type** | **Description** | | :- | :- | :- | | `decided_at` | timestamp | ISO 8601 timestamp when the underwriting decision was made. **Required.** | | `reason` | string | The reason for the decision. **Required.** | | `exception_approval_reason` | string | **Provide only when the decision was an exception to your underwriting criteria** — the reason for approving outside the traditional process. | ### `documents` (array of objects) | **Attribute** | **Type** | **Description** | | :- | :- | :- | | `document_id` and `type` are always required. Each document type is either a **disclosure** or a **consent**, and that determines which timestamp you must supply. | | | | **Attribute** | **Type** | **Description** | | :- | :- | :- | | `document_id` | string | Unique identifier for the document being referenced. Use the file name of the file delivered to Lead's `/documents` SFTP directory. **Required.** | | `type` | string | Document type — for example `truth_in_lending_document`, `fcra_notice`, or `consent_to_link_account`. **Required.** See the [API Reference](/api-reference/endpoint/application/create-an-application) for the full enum. | | `displayed_at` | timestamp | ISO 8601 timestamp when the document was displayed to the applicant. **Required for disclosure types.** | | `consented_at` | timestamp | ISO 8601 timestamp when the applicant consented to the document. **Required for consent types.** | | `version` | string | Recommended for static documents uploaded once and referenced for many applicants. Use a new `document_id` for each new version. | > [!NOTE] > > Consent types — `esign_agreement`, `credit_pull_consent`, `consent_to_link_account`, `consent_to_link_hsa`, `negative_option_consent`, `deposit_agreement`, `cardholder_agreement`, `autopay_authorization` — require `consented_at`. Every other type is a disclosure and requires `displayed_at`. Supplying the wrong timestamp for the type fails validation. ## Mutability `PATCH /v0/applications/{id}` accepts `details`, `decision`, `documents`, and `metadata`. `status` cannot be changed: a `PATCH` that includes it returns `200` and leaves the status unchanged. `id`, `created_at`, `updated_at`, and `entities` are immutable — entities are set when the application is created, and no endpoint adds or removes entity relationships afterward. Two behaviours to plan for: `documents` and `metadata` **replace wholesale rather than merging**, so send the full intended array or object. And every update runs the same validations as creation, so an update to a `declined` application must still carry a complete `details.adverse_action_notice`. For merge-patch semantics, the per-field notes, and the `422` behaviour on immutable fields, see [Update an Application](/api-reference/endpoint/application/update-an-application). ## Example Application Object ```json theme={null} { "id": "application_xyz123", "created_at": "2026-05-14T15:59:30Z", "updated_at": "2026-05-14T15:59:30Z", "status": "approved", "entities": { "account_holder_type": "commercial", "account_holders": ["entity_abc123"], "authorized_signers": ["entity_def456"] }, "details": { "product_name": "Growth Business Credit Line", "credit": { "is_secured": false, "is_mla": false, "currency": "USD", "underwriting_grade": "99", "limit": 5000000, "max_limit": 10000000, "report": { "score": 712, "pulled_at": "2026-05-14T15:58:40Z", "source": "transunion" } } }, "decision": { "decided_at": "2026-05-14T15:59:12Z", "reason": "Meets program underwriting criteria" }, "documents": [ { "document_id": "document_2N5Hk8xYmQpL9rBvC3jD", "type": "truth_in_lending_document", "displayed_at": "2026-05-14T15:58:05Z", "version": "v1" }, { "document_id": "document_7Qw2Rt5YuI9oP3aS6dF1", "type": "consent_to_link_account", "consented_at": "2026-05-14T15:57:20Z" } ], "metadata": {} } ``` Full request schemas, including status-conditional requirements, are in the [API Reference](/api-reference/endpoint/application/create-an-application) and [Validation Rules and Errors](/products/applications/validations). # Applications API Best Practices Source: https://docs.lead.bank/products/applications/best-practices Recommended patterns for the Lead Applications API, including OAuth scopes, idempotency keys, terminal status selection, and adverse action notice fields. ## Use the Correct Authentication Scope Choose the right OAuth scope before making any API call: * `POST /v0/applications` and `PATCH /v0/applications/{id}` require **`application/read_write`**. * `GET /v0/applications/{id}`, `GET /v0/applications?client_application_id=…`, and `GET /v0/applications/{id}/entity_relationships` accept either **`application/read`** or **`application/read_write`**. Use the least-privileged scope appropriate to the operation. If your integration only needs to retrieve applications, use `application/read` and avoid provisioning broader write access. ## Use Idempotency Keys on POST Always include a unique `Idempotency-Key` header on every `POST /v0/applications` request. Use a UUID (e.g., `550e8400-e29b-41d4-a716-446655440000`). Key behaviors to be aware of: * If a request fails, use a new idempotency key when retrying — the original key stores the failed response for 48 hours and replays it. Two exceptions on **409** Conflict: if the error code is `idempotency_key_conflict` and you have not reused this key for a different request, your identical request raced with itself — retry once with the same key to receive the original outcome. If the error code is conflict (resource modified concurrently), reload the resource and resubmit with a new key. * If a request succeeds (**200**), reusing the same idempotency key returns the cached response without creating a duplicate application. * Omitting the `Idempotency-Key` header results in a 400 `operation_not_allowed` error. ## Choose the Right Status Applications are terminal-only. At creation time, set `status` to the actual underwriting outcome: * **`approved`** — the application was approved. * **`declined`** — the application was declined; an adverse action notice was issued. * **`canceled`** — the application was withdrawn or otherwise did not reach an approval/decline decision. Status cannot be changed after creation, so confirm the outcome before you submit. A `PATCH` that includes `status` returns `200` and leaves the status unchanged. If you reported the wrong status, contact your Technical Account Manager. See [The Application Object](/products/applications/application-object#mutability) for the mutable/immutable split. All `declined` and `canceled` applications from your program *must* be sent to Lead, even though Lead does not create Accounts for them, in order for Lead to ensure compliant approval processes. ## Include All Required Status-Specific Fields The status you choose drives which fields are required. Validate your payload against these rules before submitting: * **`declined`** requires a complete `details.adverse_action_notice` object. The adverse action notice object is all-or-nothing: if included, all three fields — `delivered_at`, `reason`, and `delivery_method` — must be present. * Every application requires a `decision` object with both `decided_at` and `reason`, regardless of status. * The `details.credit` object is required on every application, including non-credit products, and `is_secured`, `is_mla`, and `currency` are required within it. `underwriting_grade` is required when `status` is `approved` or `declined`; `limit` and `max_limit` are required on `approved`. * None of these credit-field rules inspect product type, even though several error messages say "for credit products." A non-credit product still has to supply them. * `details.credit.report` is optional for most programs, and has its own internal requirements when you include it. * Each entry in `documents` requires `document_id` and `type`, plus a timestamp that depends on whether the type is a consent or a disclosure. For the field-by-field rules and the error each one returns, see [Validation Rules and Errors](/products/applications/validations). ## Create Entities First The Applications API validates entity IDs on approved applications. Before calling `POST /v0/applications`, create the relevant entities using the Entity API and collect the `entity_`-prefixed IDs from those responses. Use the server-generated `id` (e.g., `entity_3frCuaBe93vyJZxK3yOhlVuriBY`) returned from the Entity API in the `entities.account_holders`, `entities.authorized_signers`, and `entities.authorized_users` arrays of your application request. Entity creation must be sequenced ahead of application creation — the Applications API does not create entities on your behalf. Use the [`intended_roles` parameter](/products/entity/troubleshooting#intended-role-parameter) on the entity creation request to confirm the entity meets the data requirements for the `account_holder` or `authorized_signer` role before you call `POST /v0/applications`. ## Understand Consumer vs. Commercial Applications `account_holder_type` is derived from the entity types in `entities.account_holders` — see [Consumer vs. Commercial Account Holder Types](/products/applications/overview) for how the derivation and the one-category rule work. When you build the roster: * List individuals as authorized signers for commercial applications rather than as account holders. * Commercial applications require at least one entry in `entities.authorized_signers`, and each of those entities must have the `authorized_signer` role assigned. Consumer applications do not require authorized signers. ## Retrieve Entity Relationships for Role Detail The `GET /v0/applications/{id}` response returns the derived `account_holder_type` along with the entity ID lists on `entities.account_holders` and `entities.authorized_signers`. `authorized_users` is accepted on creation but is not returned on the application object. For the full relationship records, including authorized users, call: ```text theme={null} GET /v0/applications/{id}/entity_relationships ``` This endpoint returns the full list of entity relationships for the application and is the authoritative source for entity association data. Entity relationships are set when the application is created and cannot be changed afterward — there is no update path for `entities` on an existing application. # Applications API Overview Source: https://docs.lead.bank/products/applications/overview Submit terminal underwriting decisions to Lead with the Applications API to satisfy Reg B and fair lending obligations — where it sits in the sequence, which products need it, scopes, and endpoints. ## Introduction The Applications API must be used for any underwritten lending or credit product built on Lead. When your underwriting process reaches a final outcome — approved, declined, or canceled — you submit that decision here. Lead uses this data to satisfy Reg B and fair lending obligations, and the resulting `application_id` is required to create Accounts for underwritten credit products downstream. This is a **reporting** API ([Executing vs. Reporting](/core-concepts/platform/executing-vs-reporting)): the underwriting decision happens in your system; the Application is your report of it. > [!NOTE] > > Certain credit-like products that do not have an underwriting process and decision (e.g., courtesy overdraft) do not need to have an Application object created. The vast majority of credit or lending products do need to have an Application object created via this API. The API sits between the Entity API and the Accounts API in the onboarding sequence: **1. Entity API** Create entity records for each applicant. Lead validates KYC/KYB data at this step. **2. Applications API** Submit the underwriting outcome, referencing the entity IDs from step 1. An approved application returns an `application_id`. **3. Accounts API** Create the account for the credit or lending product, referencing the `application_id` from step 2. Applications are always submitted in a terminal state — there is no in-progress state. Every `POST /v0/applications` request represents a final underwriting decision, and **all three outcomes must be reported**: declined and canceled applications are required for fair lending compliance even though no account is created for them. ## Authentication The Applications API uses two OAuth scopes ([authentication](/api-reference/using-the-api/authentication)): * **`application/read_write`** — required for `POST` and `PATCH` requests. * **`application/read`** — sufficient for `GET` requests. Use the least-privileged scope appropriate to your operation. ## Endpoints | Method | Path | Purpose | | :- | :- | :- | | `POST` | `/v0/applications` | Create a new application in a terminal state (`approved`, `declined`, or `canceled`). | | `GET` | `/v0/applications/{id}` | Retrieve an application by its server-generated `id`. | | `GET` | `/v0/applications?client_application_id=…` | Retrieve an application by the `client_application_id` you assigned. | | `PATCH` | `/v0/applications/{id}` | Update mutable properties. `status` cannot be changed after creation. | | `GET` | `/v0/applications/{id}/entity_relationships` | List every entity linked to an application, with its role. | > [!NOTE] > > Full request and response schemas: [API Reference](/api-reference/endpoint/application/create-an-application). ## Key Concepts **Terminal-Only Status Model** You must know the underwriting outcome before calling `POST /v0/applications`. Status cannot be changed after creation: a `PATCH` that includes `status` returns `200` and leaves the status unchanged. If you reported the wrong status, contact your Technical Account Manager. **Consumer vs. Commercial Account Holder Types** The `entities.account_holder_type` field in the response (`consumer` or `commercial`) is derived automatically from the entity types you supply — it is not set directly. Individual entities produce `consumer`; business or sole proprietor entities produce `commercial`. All entries in `account_holders` must share the same category — every entry an individual, or every entry a business or sole proprietor. Mixing an individual entity with a business or sole proprietor entity is not permitted, but business and sole proprietor entities may be combined within the same application. The application response returns the entity IDs in each role on `entities.account_holders` and `entities.authorized_signers`; for the full relationship records, including authorized users set on the application, call `GET /v0/applications/{id}/entity_relationships`. **Entity Prerequisites** Entities must exist in Lead's system before you can reference them in an application. Call the [Entity API](/products/entity/overview) first to create entity records, then use the `entity_`-prefixed IDs returned from that API in the `entities.account_holders`, `entities.authorized_signers`, and `entities.authorized_users` arrays of your application request. ## In This Section [The Application Object](/products/applications/application-object) — every field, the terminal statuses, and an example payload · [Validation Rules and Errors](/products/applications/validations) · [Best Practices](/products/applications/best-practices) · [Troubleshooting](/products/applications/troubleshooting) # Applications Troubleshooting Source: https://docs.lead.bank/products/applications/troubleshooting The most common errors when calling the Applications API — terminal-status requirements, adverse action notice fields, credit-field rules, document timestamps, and entity prerequisites. ## Common Errors Validation failures on the Applications API are returned synchronously as `422` responses with an `invalid_parameters` array naming the fields that failed. The patterns below are the ones partners hit most often. For the complete rule set, see [Validation Rules and Errors](/products/applications/validations). > [accordion] 422 on a declined application: missing adverse action notice > > **Symptom:** `POST /v0/applications` with `status: declined` returns 422. > > **Cause:** `details.adverse_action_notice` is required when the status is `declined`, and the object is all-or-nothing — `delivered_at`, `reason`, and `delivery_method` must all be present. > > **Fix:** deliver the notice per your Reg B process, then submit the application with the completed object. Declines and cancels must be reported even though no account is created for them — skipping them is a fair lending compliance gap, not a shortcut. > [accordion] 422 on an approved application: missing or inconsistent credit fields > > **Symptom:** 422 on `status: approved`, often with an error message mentioning "credit products" even though your product is not a credit product. > > **Causes:** > > * `details.credit.limit`, `details.credit.max_limit`, and `details.credit.underwriting_grade` are required on approval. `underwriting_grade` is also required on declines. > * The `details.credit` object itself is required on **every** application, and `is_secured`, `is_mla`, and `currency` are required within it — whatever the status. > * None of these rules inspect product type, despite what the error text says. A non-credit product still needs them. > * `limit` cannot exceed `max_limit`. > * If `details.credit.report` is included, `pulled_at` and `source` are always required, and you must supply **exactly one** of `score` (300–850) or `non_score_value` (`unestablished` or `frozen`). Supplying both, or neither, fails. > > **Fix:** complete the credit object per [Validation Rules](/products/applications/validations) and resubmit. > [accordion] 422 on documents: wrong timestamp for the document type > > **Symptom:** 422 on `documents` with the reason `Documents do not conform to schema specification`, on a payload that looks complete. The error names the array, not the entry that failed, so you have to check every entry. > > **Cause:** every document type is either a **consent** or a **disclosure**, and that determines which timestamp is required. Consent types — `esign_agreement`, `credit_pull_consent`, `consent_to_link_account`, `consent_to_link_hsa`, `negative_option_consent`, `deposit_agreement`, `cardholder_agreement`, `autopay_authorization` — require `consented_at`. Every other type is a disclosure and requires `displayed_at`. `document_id` and `type` are always required. > > **Fix:** match the timestamp to the type. If you're mapping from an internal document model, check that the mapping does not send `displayed_at` for consents by default. > [accordion] 422 referencing entities > > **Symptom:** 422 naming a field under `entities`. > > **Likely causes:** > > * An `entity_id` does not resolve to an existing entity. > * The entity exists but does not meet the data requirements for the role it is being used in. > * `account_holders` mixes an individual with a business or sole proprietor. That combination is not permitted; business and sole proprietor entities may be combined with each other. > * A commercial application is missing `authorized_signers`, which are required when account holders are businesses or sole proprietors. > > **Note:** entity ID resolution and role validation run only when `status` is `approved`. A declined or canceled application does not surface those errors, so an entity problem can stay hidden until your first approval. The duplicate-entity checks are the exception and run on every status. > > **How to confirm:** `GET` the entity and inspect the `role_details` array — an `inactive` role's `criteria_details` names the exact failed checks. See [Entity Troubleshooting](/products/entity/troubleshooting) for how to read them, including the "Understand Indirect Failures" section on roles that fail because a related child entity failed its own checks. > > **Fix:** correct the entity data or the account holder composition, then retry. Using [`intended_roles`](/products/entity/troubleshooting#intended-role-parameter) on entity creation surfaces these problems before you ever call the Applications API. > [accordion] Reported the wrong terminal status > > **Symptom:** an application was submitted as `approved` when the correct outcome was `declined`, or vice versa. > > **Fix:** contact your Technical Account Manager. Status cannot be changed after creation, and a `PATCH` that includes `status` returns `200` without changing it. > [accordion] Cannot find an application by your own ID > > **Symptom:** lookups by your own identifier return an error or 404. > > **Cause:** `GET /v0/applications/{id}` takes the server-generated `application_*` ID only. Your identifier is queried as `GET /v0/applications?client_application_id=…`, the filtered form of the collection. > > **Fix:** use the query-parameter form for partner-assigned IDs, and store the `application_*` ID from the create response for direct retrieval. Note that `client_application_id` is present only on applications created via file upload — applications created through the API are identified solely by their server-generated ID. Still stuck? Contact your Lead team with the `application_id` (or `client_application_id`), the full request payload, and the `422` response body. # Applications API Validation Rules and Errors Source: https://docs.lead.bank/products/applications/validations Synchronous 422 validation responses for the Lead Applications API, covering required fields, status-specific rules, and the invalid_parameters payload. ## Overview All validation failures on the Applications API are returned synchronously. Business logic errors are returned as `422` responses with an `invalid_parameters` array that identifies which fields failed and why, so you can correct the request before retrying. ```json theme={null} { "code": "validation_error", "title": "Validation Error", "detail": "One or more request parameters failed validation", "status": "422", "invalid_parameters": [ { "parameter": "", "reason": "" } ] } ``` *** ## POST /v0/applications — Required Fields | Parameter | Validation Rule | Error Reason | | :- | :- | :- | | `status` | Required; must be `approved`, `declined`, or `canceled` | `Status must be one of: approved, declined, canceled` | | `entities.account_holders` | Required; minimum 1 element | `Application is missing required account_holders field` | | `details` | Required object | `property "details" is missing` | | `documents` | Required array | `Application is missing required documents field` | | `decision` | Required object | `property "decision" is missing` | | `details.credit` | Required object on **every** application, including non-credit products | Schema validation: `details.credit` is required | | `Idempotency-Key` header | Required on POST | 400 `operation_not_allowed`: `value is required but missing` | *** ## POST /v0/applications — Entity Validations Most entity checks are enforced only when `status` is `approved` — a declined or canceled application does not surface them, so an entity problem can stay hidden until your first approval. The duplicate checks are the exception and run on every status. | Parameter | Validation Rule | Error Reason | | :- | :- | :- | | `entities.account_holders` | All entity IDs must resolve to existing entities | `expected N account holder entities but only M resolved successfully; one or more entity IDs were not found` | | `entities.authorized_signers` | All entity IDs must resolve to existing entities | `expected N authorized signer entities but only M resolved successfully; one or more entity IDs were not found` | | `entities.account_holders` | Cannot mix individual entities with business or sole\_prop entities. business and sole\_prop entities may be combined. | `account holders contain mixed entity categories; all must be individuals (consumer) or all must be business and/or sole_prop (commercial). business and sole_prop entities may be combined within the commercial category.` | | `entities.authorized_signers` | Required (min 1) when account holders are Business or Sole Prop entities | `Commercial application must have at least one authorized signer` | | `entities.authorized_signers` | Entities must have the `authorized_signer` role | `One or more authorized signer entities have incorrect role assignments` | | `entities.account_holders` | Entities must have an active `account_holder` role | Error code `app_account_holder_invalid_role` | | `entities.account_holders` | Must reference unique entities after resolution. Enforced on **every** status, not just approved | Error code `app_account_holder_duplicate_entities` | | `entities.authorized_signers` | Must reference unique entities after resolution. Enforced on **every** status, not just approved | Error code `app_authorized_signer_duplicate_entities` | *** ## POST /v0/applications — Field Validations > [!WARNING] > > Several error messages below say "for credit products" — `underwriting_grade`, `limit`, `max_limit`, and `is_mla`. **None of these rules inspect product type.** `underwriting_grade`, `limit`, and `max_limit` are gated on `status` alone; `is_mla` and the `details.credit` object are required on every application. Do not read the error text as an exemption for non-credit products. | Parameter | Validation Rule | Error Reason | | :- | :- | :- | | `details.product_name` | Required | `Application is missing required product_name field` | | `details.credit.currency` | **Required**; must be a valid ISO 4217 currency code | `Application is missing required currency field` | | `details.credit.is_secured` | **Always required**; must be a boolean | `IsSecured field must be a boolean value (true/false)` | | `details.credit.is_mla` | **Always required**; must be a boolean | `IsMLA must be a boolean value (true/false) when status is approved or declined for credit products` | | `details.credit.underwriting_grade` | Required when `status` is `approved` or `declined` | `UnderwritingGrade is required when status is approved or declined for credit products` | | `details.credit.limit` | Required when `status` is `approved` | `CreditLimit is required when status is approved for credit products` | | `details.credit.max_limit` | Required when `status` is `approved` | `MaxCreditLimit is required when status is approved for credit products` | | `details.credit.limit` | Cannot exceed `details.credit.max_limit` for approved applications | `CreditLimit must not exceed MaxCreditLimit for approved credit products` | | `details.credit.report.score` | When `report` is provided, required unless `non_score_value` is supplied; mutually exclusive with `non_score_value`; must be non-zero and within 300–850 | `CreditScore is required with credit_pulled_at and credit_report_source, allowed range is 300-850` | | `details.credit.report.non_score_value` | Alternative to `score` when no numeric score is available; must be `unestablished` or `frozen`; mutually exclusive with `score` | `CreditReportNonScoreValue must be one of: unestablished, frozen; mutually exclusive with credit_score` | | `details.credit.report.pulled_at` | Required whenever `report` is provided | `CreditPulledAt is required with credit_score and credit_report_source, must be valid ISO8601 datetime` | | `details.credit.report.source` | Required whenever `report` is provided; must be `equifax`, `experian`, or `transunion` | `CreditReportSource is required with credit_score and credit_pulled_at, must be one of: equifax, experian, transunion` | | `details.adverse_action_notice.delivered_at` | Required when `status` is `declined` | `AANDeliveredAt must be valid ISO8601 datetime when status is declined` | | `details.adverse_action_notice.reason` | Required when `status` is `declined` | `AANReason is required when status is declined` | | `details.adverse_action_notice.delivery_method` | Required when `status` is `declined`; must be `email`, `text`, or `other` | `AANDeliveryMethod must be one of: email, text, other when status is declined` | | `decision.decided_at` | Required on every application, whatever the status | `DecidedAt is required when status is approved, declined, or canceled` | | `decision.reason` | Required on every application, whatever the status | `DecisionReason is required when status is approved, declined, or canceled` | | `details.credit.report` | Presence of credit bureau data is required on approved applications **for programs where this check is enabled** — see below | `Credit bureau data (credit_score or credit_report_non_score_value, credit_pulled_at, credit_report_source) is required when application status is approved` | *** > [!NOTE] > > **The credit bureau presence check is off by default.** It requires that an approved application carry `pulled_at`, `source`, and one of `score` / `non_score_value`, but it is enabled per program rather than globally. If your program's underwriting policy requires bureau data on every approval, expect it to be on; otherwise `details.credit.report` remains optional. The field-level rules above still apply whenever you do send a report. ## POST /v0/applications — Document Validations Every document type is either a **consent** or a **disclosure**, and that determines which timestamp is required. Document failures are reported against the `documents` array as a whole rather than per entry, with the reason `Documents do not conform to schema specification`. The rules below are what that message covers — check each entry against all of them. | Parameter | Validation Rule | | :- | :- | | `documents[].document_id` | Required on every entry | | `documents[].type` | Required; must be a valid document type — see the [API Reference](/api-reference/endpoint/application/create-an-application) for the full enum | | `documents[].consented_at` | Required when `type` is a consent type: `esign_agreement`, `credit_pull_consent`, `consent_to_link_account`, `consent_to_link_hsa`, `negative_option_consent`, `deposit_agreement`, `cardholder_agreement`, `autopay_authorization` | | `documents[].displayed_at` | Required when `type` is any other (disclosure) type | *** ## PATCH /v0/applications/id `PATCH` uses JSON Merge Patch semantics (RFC 7396) and applies **the same field validations documented above for `POST /v0/applications`**. An update to a `declined` application must therefore still carry a complete `details.adverse_action_notice` object, just as it does on creation. | Validation | Error | | :- | :- | | `details`, `decision`, `documents`, and `metadata` are mutable | — | | `status` cannot be changed after creation | None. The `PATCH` returns `200` and the status is unchanged. If you reported the wrong status, contact your Technical Account Manager. | | `id`, `created_at`, `updated_at`, and `entities` are immutable | 422 `parameters_invalid` with the offending field in `invalid_parameters` | | `documents` and `metadata` replace wholesale rather than merging | — | | `Idempotency-Key` header | Required on `PATCH` | See [The Application Object](/products/applications/application-object#mutability) for a summary, or [Update an Application](/api-reference/endpoint/application/update-an-application) for the per-field detail. *** ## Downstream Constraints — Account Creation When you later use an approved application to create an Account, the Accounts API enforces matching between the application and the account. The rules below run on `POST /v0/accounts`, not on `POST /v0/applications`, but a mismatch blocks account creation against this application — design the roster on the application accordingly. | Constraint | Validation Rule | Error Reason | | :- | :- | :- | | `account_holder_type` | Must match the application | Account holder type does not match the linked application | | Account Holders and Authorized Signers | Must match between the application and the account on initial account creation. | Account Holders and Authorized Signers must match between the application and account on account creation. | | Application `status` | Must be `approved` when the application is referenced as `application_id` on an account | application\_id is not linked to an approved application | See the [Accounts API validations](/file-reference/account/validations) for the canonical application-match rules. *** ## GET /v0/applications/id and GET /v0/applications/id/entity\_relationships Applications created through the API are always terminal. Applications created by file upload can carry a non-terminal status, and those records are not retrievable through the API. | Validation | Error | | :- | :- | | `id` must match the pattern `^application_\w+$` | 422 `validation_error`: `string doesn't match the regular expression "^application_\w+$"` | | A `client_application_id` you assigned cannot be used on the path form — retrieve it with `GET /v0/applications?client_application_id=…` | 422 `validation_error` on `id` | | Application must exist | 404 `not_found`: `The requested application was not found` | | An application created by file upload that never reached a terminal status is not retrievable through the API | 404 `url_invalid`: `The requested application was not found` | *** ## Authentication | Scenario | Error | | :- | :- | | Using an `application/read` token to call `POST /v0/applications` or `PATCH /v0/applications/{id}` | 403 `insufficient_scope` | | Using an unrelated scope token (e.g., `account_number/read`) | 403 `insufficient_scope` | | Using an invalid or expired token | 403 `token_invalid` | # Cards API Best Practices Source: https://docs.lead.bank/products/cards/best-practices Guidance on OAuth scopes, idempotency keys, replacement cards, expiry date handling, and resource sequencing when integrating with the Lead Cards API. ### Use the Correct Authentication Scope Choose the right OAuth scope before making any API call. `POST /v0/cards`, `PATCH /v0/cards/{id}`, and the action endpoints require `card/read_write`; `GET /v0/cards/{id}` accepts `card/read` or `card/read_write`. Use the least-privileged scope appropriate to the operation. If your integration only needs to retrieve cards, use `card/read` and avoid provisioning broader write access. ### Use Idempotency Keys on POST and PATCH Always include a unique `Idempotency-Key` header on every `POST /v0/cards` request. Use a UUID (e.g., `550e8400-e29b-41d4-a716-446655440000`). Key behaviors to be aware of: * If a request fails, use a new idempotency key when retrying — the original key stores the failed response for 48 hours and will replay it. Two exceptions on **409** Conflict: if the error code is `idempotency_key_conflict` and you have not reused this key for a different request, your identical request raced with itself — retry once with the same key to receive the original outcome. If the error code is conflict (resource modified concurrently), reload the resource and resubmit with a new key. * If a request succeeds (200), reusing the same idempotency key returns the cached response without creating a duplicate card. * Omitting the `Idempotency-Key` header results in a 400 operation\_not\_allowed error. ### Sequence Resource Creation Correctly Because the API is synchronous and per-resource, you are responsible for sequencing. Create the Entity and the Account first, capture their IDs, and use them when creating the card. The card cannot be created until both the referenced entity and account exist, and the entity must already be linked to the account as an account holder or authorized user. ### Use replacement\_for for Replacement Cards When issuing a replacement, set `details.replacement_for` to the `card_id` of the card being replaced on the new card's creation request. The old card must already be in a `closed` status. This pattern means you do not need to create the new card first just to obtain its ID and then patch the old card. ### Treat Expiry Dates as End-of-Month Always set `expiry_date` to the last calendar day of the expiration month. This keeps reported expirations consistent with how card networks treat the expiry month. ### Use metadata for Your Own Context The optional `metadata` object is the supported place to store your own key-value context on a card, and it is one of only two fields editable after creation. Avoid encoding such context into immutable fields.\\ ### Correcting an Accidentally Closed Card The action endpoints exist primarily to support normal lifecycle progression. If a card is closed in error, moving it back to `active` (via `/activate`) or `inactive` (via `/deactivate`) is intended only as an error-correction path — it may not be enabled for your program during beta. If you close a card in error, contact your Lead representative to confirm whether the reopen path is available. # Cards: Reporting Card Issuance to Lead Source: https://docs.lead.bank/products/cards/overview Report physical and virtual card issuance to Lead for compliance oversight: creation, lifecycle status transitions, OAuth scopes, and the Card object. This is a reporting API ([Executing vs. Reporting](/core-concepts/platform/executing-vs-reporting)) — you notify Lead of cards created with your issuer processor; no call here creates a physical or virtual card. Integration surface today: Cards API — Beta, or the [card file schema](/file-reference/card/schema) in the File Reference. Status source of truth: [Integration Surfaces by Product](/core-concepts/platform/integration-surfaces-by-product). > [!NOTE] > > The Cards API is in beta: the interface may change before general availability, and changes will be announced in [Upcoming Changes](/upcoming-changes). Talk to your Lead Technical Account Manager before building on it. ## Introduction The Cards API reports physical and virtual card issuance to Lead for compliance oversight. You use it to report card creation, update card details, and keep card status current throughout the card lifecycle — because you are the system of record, statuses here describe *your report*, which is why even a closed card can be corrected back to active through the API if it was reported in error. Cards are created in active status. You manage the card lifecycle through dedicated status-transition endpoints — activate, deactivate, and close. You'll integrate with this API if you issue physical or virtual cards (for example, consumer, commercial, HSA, or FSA cards) to your customers. The Cards API sits downstream of the [Entity](/products/entity/overview) and [Accounts](/products/accounts/overview) APIs in the compliance onboarding sequence: **1. Entity API** Create the entity record for your cardholder. **2. Applications API** Submit the underwriting outcome during the cardholder’s onboarding. > [!NOTE] > > Only certain programs will have an underwriting process; programs without underwriting can skip this step. **3. Accounts API** Create the account the card will be linked to, and link the cardholder entity to it as an `account_holder` or `authorized_user`. **4. Cards API** Create the card, referencing the `account_id` and `entity_id` from the prior steps. > [!NOTE] > > A separate OpenAPI spec covers the full schema definition for request and response bodies. This page provides conceptual context for integrating with the API. ## Authentication Access is controlled via OAuth scopes: * `card/read_write`: Required for `POST` and `PATCH` requests and for all status-transition endpoints (`/activate`, `/deactivate`, `/close`). Grants both read and write access. * `card/read`: Sufficient for `GET /v0/cards/{id}`. Grants read-only access. Use the least-privileged scope appropriate to the operation you're performing. The Card object links to an `account_id` and an `entity_id`, which are sensitive tokens; the associated Entity objects (managed by the Entity API) hold the actual PII and are not exposed via the Cards API. > [!TIP] > > All endpoints are available in both Sandbox and Production. Versioning is handled via a prefix in the URI path (`/v0/`). This is the V0 API; we'll add non-breaking changes to V0, and breaking changes will require a new version. ## Endpoints | **Method** | **Path** | **Purpose** | | :- | :- | :- | | `POST` | `/v0/cards` | Create a new card. | | `GET` | `/v0/cards/{id}` | Retrieve a specific card by ID. | | `PATCH` | `/v0/cards/{id}` | Update a card's `card_product_name` and/or `metadata`. | | `POST` | `/v0/cards/{id}/activate` | Activate an `inactive` card. | | `POST` | `/v0/cards/{id}/deactivate` | Deactivate an `active` card. | | `POST` | `/v0/cards/{id}/close` | Close a card. | ## Card Object | **Attribute** | **Type** | **Description** | | :- | :- | :- | | `id` | string | Unique identifier for the card. Prefixed with `card_`. Server-generated and read-only. | | `client_card_id` | string | Partner-provided identifier for the card. Populated only for cards created via file upload; cards created through the API are identified solely by their server-generated ID. | | `entity_id` | string | Unique ID of the associated customer entity. Prefixed with `entity_`. | | `account_id` | string | Unique ID of the associated account. Prefixed with `account_`. | | `created_at` | timestamp | Lead server-generated ISO 8601 timestamp when the card was created. | | `updated_at` | timestamp | Lead server-generated ISO 8601 timestamp when the card was last updated. | | `status` | string | Current status of the card. Possible values: `active`, `inactive`, `closed`. Set by the system. | | `status_reason` | string | Reason for the current card status. Set via the status-transition endpoints. | | `details` | object | Detailed attributes of the card. See `details` object below. | | `metadata` | json | Arbitrary key-value pairs for storing additional information related to this object. | ### `details` (sub-object) | **Attribute** | **Type** | **Description** | | :- | :- | :- | | `card_product_name` | string | The name of the card product in your system. | | `is_virtual` | boolean | `true` if the card exists as a virtual card; `false` if a physical representation exists. | | `card_type` | string | The type of card. Possible values: `hsa`, `fsa`, `consumer`, `commercial`. | | `expiry_date` | date | Date the card expires (YYYY-MM-DD). Always expressed as the last day of the month — e.g., if expiration is 01/29, the value is `2029-01-31`. | | `replacement_for` | string | The `card_id` of the card this card replaces. The referenced card must be in a `closed` status. Set on creation; immutable. | | `last_four` | string | Last four digits of the card's PAN. Must match `^[0-9]{4}$`. | | `closed_at` | timestamp | ISO 8601 timestamp when the card was closed. Empty unless the card is in a `closed` status; set by the system based on the most recent `/close` call. Server-managed and read-only. | **Example Card Object** ```json theme={null} { "id": "card_abc123def456ghi789", "client_card_id": "id_123def456ghi789", "created_at": "2025-10-20T14:25:00Z", "updated_at": "2025-10-25T14:30:00Z", "account_id": "account_9h8g7f6e5d4c3b2a", "entity_id": "entity_mno456pqr789", "status": "active", "status_reason": "", "details": { "card_product_name": "Corporate Plus Rewards", "is_virtual": true, "card_type": "commercial", "expiry_date": "2028-10-31", "replacement_for": "card_1234523", "last_four": "1234", "closed_at": "" }, "metadata": {} } ``` ## Key Concepts **Lifecycle and the Action-endpoint Status Model** A card transitions through three states: `active`, `inactive`, and `closed`. When you create a card via `POST /v0/cards`, it starts directly in the active state. You make status changes exclusively through the dedicated action endpoints (`/activate`, `/deactivate`, `/close`) — you cannot set the status field via `POST` or `PATCH`. **The Closed State is Terminal** By default, `closed` is a terminal state. Support for moving a card from closed back to `active` or `inactive` is intended only to correct an accidental or erroneous closure. If a status was reported incorrectly, it can be corrected through the API. E.g., if a card was accidentally reported as `closed`, you can call the `/activate` endpoint to return it to an `active` status.  **Entity and Account Prerequisites** The entity and account a card references must exist before you create the card, and the entity must already be linked to the account as an `account_holder` or `authorized_user`. Capture the `account_id` and `entity_id` from the Accounts and Entity APIs and supply them on your card creation request. **Replacement Cards** When you issue a replacement, set `details.replacement_for` on the new card to the `card_id` of the closed card it replaces. This replaces the pattern used in the prior version of Lead’s product based on file uploads, where you were requested to include the “replacing” card’s ID when closing the “replaced” card. This is so that you don't need to create the new card first just to obtain its ID and then patch the old card’s status. # Cards API Validation Rules and Errors Source: https://docs.lead.bank/products/cards/validations Synchronous 422 validation responses for the Lead Cards API across create, retrieve, update, activate, deactivate, and close endpoints, plus enum rules. All validation failures on the Cards API are returned synchronously. Business logic errors are returned as `422` responses with an `invalid_parameters` array that identifies which fields failed and why, so you can correct the request before retrying. ```json theme={null} { "code": "validation_error", "title": "Validation Error", "detail": "One or more request parameters failed validation", "invalid_parameters": [ { "parameter": "", "reason": "" } ] } ``` Every mutating request (`POST`, `PATCH`, and the action endpoints) requires an `Idempotency-Key` header. Omitting it returns `400 operation_not_allowed` (reason: `parameter "Idempotency-Key" in header has an error: value is required but missing`). A request body that is not valid JSON returns `400 bad_request` with `The request body contains malformed JSON`. ## `POST /v0/cards` Creates a card. The card is always created in `active` status. ### Required Fields | **Parameter** | **Validation Rule** | **Error Reason** | | :- | :- | :- | | `account_id` | Required object | property `account_id` is missing | | `entity_id` | Required object | property `entity_id` is missing | | `details` | Required object | property `details` is missing | | `details.card_product_name` | Required | property `card_product_name` is missing | | `details.is_virtual` | Required | property `is_virtual` is missing | | `details.card_type` | Required | property `card_type` is missing | | `details.expiry_date` | Required | property `expiry_date` is missing | | `details.last_four` | Required | property `last_four` is missing | | `Idempotency-Key` header | Required (all mutations) | `400 operation_not_allowed` — parameter `Idempotency-Key` in header has an error: value is required but missing | ### Field Validations | **Parameter** | **Validation Rule** | **Error Reason** | | - | - | - | | `entity_id` | Must match the pattern `^entity_[^\s]{1,33}$` | String doesn't match the regular expression `^entity_[^\s]{1,33}$` | | `account_id` | Must match the pattern `^account_\w+$` | String doesn't match the regular expression `^account_\w+$` | | `details.last_four` | Must match the pattern `^[0-9]{4}$` | String doesn't match the regular expression `^[0-9]{4}$` | | `details.expiry_date` | Must be a valid ISO 8601 date (YYYY-MM-DD), expressed as the last day of the expiration month | String doesn't match the format "date" | | `details.expiry_date` | Must not be earlier than the time of object creation (e.g., if created any time on 2026-06-01 UTC, an `expiry_date` before 2026-06-01 is rejected) | `invalid_date` | | `details.card_type` | Must be one of `hsa`, `fsa`, `consumer`, `commercial` | value is not one of the allowed values `["hsa","fsa","consumer","commercial"]` | | `details.is_virtual` | Must be a boolean value | Value must be a boolean | | `details.replacement_for` | If provided, must reference a card that exists, is in `closed` status, is not already referenced by another card, and matches the pattern `^card_\w+$` | Referenced card must be in closed status to be replaced Referenced card not found Replacement for card has already been referenced String doesn't match the regular expression `^card_\w+$` | ### Reference Validations | **Parameter** | **Validation Rule** | **Error Reason** | | - | - | - | | `account_id` | Must reference a valid account whose status is `active` or `inactive` | The `account_id` referenced by this card does not exist | | `entity_id` | Must be linked to the provided `account_id` as an `account_holder` or `authorized_user` | The `entity_id` is not associated with the referenced account | > [!NOTE] > > Creating a card against a **closed** account is rejected with `400 operation_not_allowed` (title *"This operation cannot be done on this object."*) rather than a `422`, because it is an operation that cannot be performed on the object. ## `GET /v0/cards/{id}` Retrieves a card by its server-generated ID. | **Validation** | **Error** | | :- | :- | | `id` must match the pattern `^card_\w+$` | `404 not_found`: the card ID passed in cannot be found | | Card must exist and belong to the caller's program | `404 not_found`: the requested card was not found | ## `GET /v0/cards?client_card_id={client_card_id}` Retrieves a card by the partner-provided `client_card_id` (for cards created via file ingestion). | **Validation** | **Error** | | :- | :- | | `client_card_id` query parameter is required | `422 validation_error`: parameter `client_card_id` in query has an error: value is required but missing | | `client_card_id` must not be empty | `400 bad_request` | | Card must exist for the caller's program | `404 not_found`: the requested card was not found | ## `PATCH /v0/cards/{id}` Partial update. Only `details.card_product_name` and `metadata` are mutable. | **Parameter / Rule** | **Behavior** | **Error Reason** | | :- | :- | :- | | `details.card_product_name`, `metadata` | Mutable — updated when present | — | | Any other field (`status`, `details.expiry_date`, `details.is_virtual`, `details.card_type`, `details.last_four`, `account_id`, `entity_id`) | **Silently ignored** — the value is not applied, and `updated_at` is only bumped if a mutable field actually changed | — (returns `200`) | | `details.card_product_name` | If provided, must be a non-empty string | `422 validation_error`: `details.card_product_name` → `Card is missing required client_card_product_name field` | | Card `status` | A card in `closed` status cannot be updated | `422 validation_error`: `status` → `Card cannot be updated when status is closed` | | `metadata` | Must not exceed the DynamoDB item size limit | `422 validation_error` (oversized metadata) | > [!NOTE] > > Unlike a create, non-mutable fields sent on a `PATCH` are **ignored rather than rejected** (consistent with the Accounts API). A `PATCH` that changes nothing (empty body, or only non-mutable fields) returns `200` without bumping `updated_at`. The status of a card is system-managed and changes only through the three action endpoints below (each takes an `Idempotency-Key` header): | **Endpoint** | **Allowed source states** | **Required body** | **Enforced `status_reason` enum** | | :- | :- | :- | :- | | `POST /v0/cards/{id}/activate` | `inactive`, `closed` | — (no body) | — | | `POST /v0/cards/{id}/deactivate` | `active`, `closed` | `status_reason` | `dormant`, `frozen`, `other` | | `POST /v0/cards/{id}/close` | `active`, `inactive` | `status_reason` | `entity_closed`, `client_closed`, `paid_off`, `charged_off`, `canceled` | ## `POST /v0/cards/{id}/activate` | **Validation Rule** | **Error Reason** | | :- | :- | | Card must not already be `active` | `status` → `card is already active` | | A card whose `expiry_date` is in the past cannot be activated | `status` → `card is expired and cannot be activated` | | A card that has been replaced (i.e., its ID has been referenced in the `replacement_for` field on a separate card) cannot be reactivated | `status` → `card has been replaced and cannot be reactivated` | Reactivating a `closed` card clears its `closed_at` and `status_reason`. ## `POST /v0/cards/{id}/deactivate` | **Validation Rule** | **Error Reason** | | :- | :- | | `status_reason` is required | property `status_reason` is missing | | `status_reason` must be a valid enum value | value is not one of the allowed values `["dormant","frozen","other"]` | | Card must not already be `inactive` | `status` → `card is already inactive` | | A card that has been replaced (i.e., its ID has been referenced in the `replacement_for` field on a separate card) cannot be deactivated | `status` → `card has been replaced and cannot be deactivated` | Deactivating a `closed` card clears its `closed_at` and sets the new `status_reason`. ## `POST /v0/cards/{id}/close` | **Validation Rule** | **Error Reason** | | :- | :- | | `status_reason` is required | property `status_reason` is missing | | `status_reason` must be a valid enum value | value is not one of the allowed values `["entity_closed","client_closed","paid_off","charged_off","canceled"]` | | Card must not already be `closed` | `status` → `card is already closed` | ## Authentication Authentication and scope are enforced at the gateway. | **Scenario** | **Error** | | :- | :- | | Using a `card/read` token to call `POST`, `PATCH`, or an action endpoint | `403 insufficient_scope`: you cannot call /v0/cards with the scope `card/read` | | Using an unrelated scope token | `403 insufficient_scope` | | Using a missing, malformed, or expired token | `403` | # Network Settlement Funding Obligations Source: https://docs.lead.bank/products/network-settlement/funding How Lead funds daily card network settlement for debit, prepaid, credit, and push-to-card BINs — the funds flows, the report data points that drive them, timing, and weekend behavior. In order for Lead to fund the network settlement account, Lead requires daily network settlement reports for each network your BINs are active on ([formats per network](/file-reference/reports/network-settlement-reports)). Those reports drive the funds flows on this page: Lead parses each report's components and moves the corresponding funds between the accounts involved. > [!WARNING] > > **Drawdowns.** Network drawdowns and reports can be aggregated across BINs of the same type. For example, two debit BINs can be funded together — but credit and debit/prepaid BINs must be separated at the reporting level in order for Lead to perform the funds flows below. ## BIN Settlement by Type ### Debit / Prepaid ![Diagram showing the default BIN network settlement for debit and prepaid.](https://mintcdn.com/lead/xIgp8PZ3ECTtP05D/images/debit-prepaid-bin-settlement.png?fit=max\&auto=format\&n=xIgp8PZ3ECTtP05D\&q=85\&s=c6f03c1529835aa93572a7a46abe50d5) > [!TIP] > > The process of steps marked 1.\* is repeated twice — once for the primary network and again for the secondary network. For debit/prepaid BINs, the net of transactions minus refunds is funded from the **source of funds, typically your FBO** — it's your customers' money settling their own spend. ### Credit For credit BINs, the day's net transaction activity is funded from **Lead-owned funds — these are loans.** That is why settled credit spend creates **receivables** on Lead's books, which flow into your program's daily sale ([Receivables & the Daily Sale](/file-reference/sales/request-schema)). Refunds are remitted to you for collections purposes, and interchange is first remitted to Lead as owner of the related receivables, then sent to you per your contract — see the data-point table below for every component's path. > [!TIP] > > The credit BIN process is performed once per day based on the network settlement report; subsequent steps then depend on other inputs. ### Push-to-Card ![Diagram showing BIN settlement for push-to-card.](https://mintcdn.com/lead/xIgp8PZ3ECTtP05D/images/push-to-card-bin-settlement.png?fit=max\&auto=format\&n=xIgp8PZ3ECTtP05D\&q=85\&s=3fc39c77edfbeca0ae8e0523ae3f06c0) > [!TIP] > > In general, push-to-card has the same funds flow as a debit/prepaid BIN (net funds outflowing from a source of funds). There are differences around the accounts involved; your implementation team will provide details. ## Report Data Points Lead parses each daily network settlement report into these values, which determine how funds move: | **Data point** | **Description** | **Debit/Prepaid BIN** | **Credit BIN** | | :- | :- | :- | :- | | Transaction amount | Gross sales | The amount totaling transaction amount minus refund amount is taken from the source of funds, typically an FBO | Funded from Lead-owned funds, as these are loans | | Refund amount | Gross returns | Included in the above | Remitted to the partner for collections purposes | | Interchange amount | Net interchange sent from the network | Interchange revenue is remitted from the network settlement account to the partner per the contract | Interchange revenue is first remitted to Lead as owner of the related receivables, then sent to you per your contract | | Dispute amount | Net chargebacks sent from the network | Funds related to disputes are sent to the appropriate account for dispute management | Same as debit/prepaid | | Fee amount | Net fees charged by the network | Fees charged by the network are passed on to the partner per the contract | Same as debit/prepaid | ## Timing and Workflow Lead receives network settlement reports for all applicable networks, then performs the funds flows above. If a program has multiple networks (e.g., Visa primary and Maestro secondary on a debit program), Lead funds network settlement once **all** of the day's files are in place. Typically, issuer processors deliver these reports in the morning to Lead via [SFTP](/file-reference/sftp-setup), with each network having its own [folder](/file-reference/delivery/overview). Network settlement funding happens **independently of any other workflow** at Lead: Lead processes settlement files regardless of what other data has been shared, to ensure the networks receive funds on time. There is also **no T-1 dependency** — if the files for settlement on T don't appear until T+1, Lead still processes the T entries on T+1. ## Weekend Behavior Reports are sent every calendar day, but funds move to the network only on business days: Lead processes reports every day and performs the funds flows the same day if it's a business day, otherwise the next business day. | **Transaction day** | **Report day** | **Settlement day** | | :- | :- | :- | | Monday | Tuesday | Tuesday | | Tuesday | Wednesday | Wednesday | | Wednesday | Thursday | Thursday | | Thursday | Friday | Friday | | Friday | Saturday | Monday | | Saturday | Sunday | Monday | | Sunday | Monday | Monday | > [!TIP] > > Illustrative only; assumes the network's transaction window aligns with the calendar day. On Monday, three days' worth of transactions are requested from the network in a single drawdown — Lead processes each day separately, so cashflow is identical but funding appears as three individual steps (one per day). ## Settlement at a Non-Lead Bank (Local Currencies) If the BIN and program are configured to settle transactions in local currencies (e.g., GBP transactions settle in GBP rather than the USD equivalent), Lead does not perform those funds flows but still requires the data for oversight: * Network settlement data reflecting the non-USD activity in each relevant currency. * Transaction data that reconciles to both the non-USD currency and USD — `settlement_amount` and `settlement_currency` become required fields. Reach out to your implementation team for details. # Network Settlement: How Card Programs Settle Source: https://docs.lead.bank/products/network-settlement/overview How money moves when your cardholders spend: the daily settlement cycle, who does what across the network, issuer processor, your program, and Lead, and where BIN sponsorship fits. When your cardholders spend, the card networks — not Lead's payment rails — move the money. **Network settlement** is the daily process by which each network requests the funds owed for activity on your program's BINs, and Lead, as your BIN sponsor, pays the network and books the flows. Your side of the process is data: making sure the daily network settlement reports reach Lead so Lead knows how much to move, and reporting the underlying card transactions so Lead can reconcile and perform oversight. ## Who Does What | **Party** | **Role in settlement** | | :- | :- | | Cardholder | Spends on your card at merchants. | | Card network (Visa, Mastercard, …) | Clears the activity and requests settlement funds daily via drawdown. | | Issuer processor (your vendor) | Processes transactions in real time and produces the network settlement reports; typically delivers them to Lead via SFTP each morning. | | **Your program** | Ensures the daily settlement reports reach Lead in a supported format, and reports posted card transactions with their settlement dates in your daily [Transactions reporting](/products/balances-and-transactions/overview). | | **Lead** | Pays each network the day's net activity, books every component (interchange, refunds, disputes, fees) to the right account, and reconciles the network's numbers against yours. | ## How a Day Settles 1. **Cardholders transact** at your issuer processor on the networks. 2. **The network's daily settlement report** — covering transactions, refunds, interchange, fees, and disputes — reaches Lead, typically delivered by your issuer processor via SFTP each morning. If the processor provides it in a network-generated format (e.g., T461 or T140 for Mastercard), it can be submitted as-is; otherwise you reformat it into a supported format. Required formats and per-network specifics: [Network Settlement Reports](/file-reference/reports/network-settlement-reports). 3. **Lead funds the network.** For **debit/prepaid** BINs, net transaction activity is funded from the source of funds, typically your FBO — it's your customers' money moving. For **credit** BINs, activity is funded from **Lead-owned funds** — these are loans, which is why settled credit spend creates **receivables** on Lead's books that flow into your daily sale ([Receivables & the Daily Sale](/file-reference/sales/request-schema)). Full flows per BIN type, the report data points that drive them, timing, and weekend behavior: [Network Settlement Funding Obligations](/products/network-settlement/funding). 4. **You report, and Lead reconciles.** You submit posted card transactions with their network settlement dates through the daily Transactions reporting, and Lead reconciles them against the network reports: [Network Settlement Reconciliation](/products/network-settlement/reconciliation). > [!NOTE] > > Network settlement funding runs independently of every other workflow — Lead processes settlement files and pays the networks on time regardless of what other data has arrived, and there is no T-1 dependency: if a day's files arrive late, Lead still processes the entries when they appear. ## BIN Sponsorship at Lead If Lead is the BIN sponsor for your program, Lead performs network settlement for every network your BINs are active on. | **Network role** | **Description** | | :- | :- | | Primary | Every BIN needs a primary network. Lead is a principal member of Visa, Mastercard, and Amex. | | Secondary | Under the Durbin Amendment routing rule, debit/prepaid BINs require a secondary network (credit BINs need only a primary). Lead supports Maestro, Interlink, Pulse, Star, and Accel. | | Issuer processor | The third-party vendor you choose to process real-time transactions on the networks. These vendors typically connect directly to the networks and send the network reports to Lead. | Once networks are chosen, you'll work with Lead, your issuer processor, and the network(s) to launch the BIN, which can take three or more months. > [!NOTE] > > **Push to Card.** If Lead is processing OCT or AFT transactions on Lead's acquiring BINs, [Funding Obligations](/products/network-settlement/funding) and [Reconciliation](/products/network-settlement/reconciliation) still apply. Lead can support specific acquiring processors. ## In This Section [Network Settlement Funding Obligations](/products/network-settlement/funding) — how Lead funds each network per BIN type, the report data points, timing, and weekend behavior · [Network Settlement Reconciliation](/products/network-settlement/reconciliation) — how the transactions you report are matched against the network's numbers · [Network Settlement Reports](/file-reference/reports/network-settlement-reports) — the required file formats per network. # Network Settlement Reconciliation Source: https://docs.lead.bank/products/network-settlement/reconciliation How Lead reconciles the card transactions you report against the network's daily settlement reports — what's matched, on what key, and what to do when a day doesn't tie out. Every settlement day, two independent records of the same card activity reach Lead: the **network's settlement report** (the aggregate money truth — what the network cleared and drew down) and the **transactions you report** in your daily [Transactions file](/products/balances-and-transactions/overview) (the customer-level truth — which cardholder spent what). Network settlement reconciliation is Lead matching the two, so that the funds Lead moved to the networks ([Funding Obligations](/products/network-settlement/funding)) are fully explained by customer activity you've attributed. ## What Gets Matched * **The key is the settlement date, card network, and BIN.** You report each posted card transaction with its **network settlement date** — the date the network cleared it, which is the date whose report it must tie to. The card network and BIN ensure it identifies the correct report if there are multiple involved. * **The check is aggregate.** The sum of your reported card transactions for a settlement date (gross spend, gross refunds) is compared against the transaction and refund amounts in that date's network report. Interchange, disputes, and network fees are network-level components that Lead books from the report itself — your transaction reporting covers the spend and refund legs. ## What You Must Report for a Day to Tie Out * **Every posted transaction, with its settlement date** — reported through the daily Transactions file no later than 6:00 a.m. CT on T+1. * **Both legs of same-day exceptions.** If a transaction clears on settlement date T and is reversed the same day, the network report includes the spend in the transaction amount and the reversal in the refund amount — so **both transactions must be reported to Lead** for the day to pass reconciliation. * **The settlement report itself**, on time and in a supported format — reconciliation can't run against a missing report ([formats](/file-reference/reports/network-settlement-reports)). > [!NOTE] > > **Network timing nuances.** Some networks' report dates and funds-movement dates differ — for example, Pulse's PRC643 aligns to settlement date T while funds move T+1 or T+2 depending on purpose. Lead manages this behind the scenes; from your side, nothing changes — you report each transaction's settlement date as the date the network cleared it. Per-network specifics: [Network Settlement Reports](/file-reference/reports/network-settlement-reports). ## When a Day Doesn't Tie Out Reconciliation breaks surface through your program's [Slack alert channel](/file-reference/delivery/slack-alerts) as validation alerts on the file cycle, and do not block file processing. The usual causes, in order of frequency: 1. **Missing transactions** — activity the network settled that you haven't reported yet (often the reversal leg of a same-day exception). Fix: report the missing transactions in a future file version. 2. **Wrong settlement date** — transactions reported against the posting date or authorization date instead of the network settlement date, so they tie to the wrong day's report. Fix: correct the date and submit in a future file; the recovery loop is the standard one. 3. **A late or malformed settlement report** — the network file for the day hasn't arrived or wasn't parseable. Funding proceeds independently, but reconciliation waits; coordinate with your issuer processor on delivery. For credit programs, an unreconciled day also matters downstream: network settlement is what originates the day's receivables, so recon breaks and [daily sale](/file-reference/sales/request-schema) discrepancies usually share a root cause — fix the transaction reporting and both resolve. Still stuck? Escalate in your Slack channel with the settlement date, the network, and the delta the alert reported. # Activate a Card Source: https://docs.lead.bank/api-reference/endpoint/card/activate-a-card POST /v0/cards/{id}/activate > **Beta:** This endpoint is in beta and may change before general availability. Transitions a card from `inactive` or `closed` to `active` status. Reactivating a closed card clears its `closed_at` and `status_reason`. A card that has been replaced (i.e., its ID has been referenced in the `replacement_for` field on a separate card) or has an `expiry_date` in the past cannot be reactivated. ## Idempotency The Idempotency-Key header is required. # Close a Card Source: https://docs.lead.bank/api-reference/endpoint/card/close-a-card POST /v0/cards/{id}/close > **Beta:** This endpoint is in beta and may change before general availability. Transitions a card from `active` or `inactive` to `closed` status. A closed card can later be referenced as a `replacement_for` target or reactivated via the activate endpoint (unless it has been replaced). ## Idempotency The Idempotency-Key header is required. # Deactivate a Card Source: https://docs.lead.bank/api-reference/endpoint/card/deactivate-a-card POST /v0/cards/{id}/deactivate > **Beta:** This endpoint is in beta and may change before general availability. Transitions a card from `active` or `closed` to `inactive` status. ## Idempotency The Idempotency-Key header is required. # Retrieve a Card by Client Card ID Source: https://docs.lead.bank/api-reference/endpoint/card/retrieve-a-card-by-client-card-id GET /v0/cards > **Beta:** This endpoint is in beta and may change before general availability. Retrieves a card by the `client_card_id` you assigned, supplied as a query parameter: `GET /v0/cards?client_card_id=...`. This is the filtered form of the cards collection and is distinct from `GET /v0/cards/{id}`, which takes the server-generated Card ID (`card_*`). The response body is identical to `GET /v0/cards/{id}`. # Update a Card Source: https://docs.lead.bank/api-reference/endpoint/card/update-a-card PATCH /v0/cards/{id} > **Beta:** This endpoint is in beta and may change before general availability. Updates mutable attributes of a card. This is a partial update: only the fields present in the request body are changed; omitted fields are left unchanged. Card `status` is system-managed and changes through the status-transition endpoints, not this endpoint. ## Idempotency The Idempotency-Key header is required. Reusing a key with a different request body will return a 422 error. # List all Events Source: https://docs.lead.bank/api-reference/endpoint/events/list-all-events GET /v1/event List all event objects. # Retrieve an Event Source: https://docs.lead.bank/api-reference/endpoint/events/retrieve-an-event GET /v1/event/{event_id} Retrieves an event object. # Simulate Advance Funding Source: https://docs.lead.bank/api-reference/endpoint/funding/advance-a-funding POST /v0/fundings/{id}/advance Advances a Funding object from processing to posted status in the Sandbox environment. # Create a Funding Source: https://docs.lead.bank/api-reference/endpoint/funding/create-a-funding POST /v0/fundings Creates a Funding object to request that Lead move funds from a Lead GL to the partner's funding FBO account. # Retrieve a Funding Source: https://docs.lead.bank/api-reference/endpoint/funding/retrieve-a-funding GET /v0/fundings/{id} Retrieve a Funding object. # Create an Internal Transfer Source: https://docs.lead.bank/api-reference/endpoint/internal-transfer/create-an-internal-transfer-v1 POST /v1/internal_transfer Creates an asynchronous Internal Transfer. # List all Internal Transfers Source: https://docs.lead.bank/api-reference/endpoint/internal-transfer/list-all-internal-transfers-v1 GET /v1/internal_transfer List all Internal Transfers. # Retrieve an Internal Transfer Source: https://docs.lead.bank/api-reference/endpoint/internal-transfer/retrieve-an-internal-transfer-v1 GET /v1/internal_transfer/{internal_transfer_id} Retrieve an Internal Transfer. # Simulate Advance Disbursement Source: https://docs.lead.bank/api-reference/endpoint/lending-simulation/advance-a-disbursement POST /v0/simulate/lending/disbursements/{disbursement_id}/advance Advances a disbursement object status in the sandbox environment. # Cancel a Disbursement Source: https://docs.lead.bank/api-reference/endpoint/lending/cancel-a-disbursement POST /v0/lending/disbursements/{disbursement_id}/cancel Cancel a disbursement. > [!WARNING] > > The Disbursement API is currently not available for new partners. Please refer to the [Lending and Overdraft](/guides/lend/lending-and-overdraft-data-flow) overview for more details about the latest version of the product. # Create a Disbursement Source: https://docs.lead.bank/api-reference/endpoint/lending/create-a-disbursement POST /v0/lending/disbursements Creates a disbursement for a loan > [!WARNING] > > The Disbursement API is currently not available for new partners. Please refer to the [Lending and Overdraft](/guides/lend/lending-and-overdraft-data-flow) overview for more details about the latest version of the product. # Retrieve a Disbursement Source: https://docs.lead.bank/api-reference/endpoint/lending/retrieve-a-disbursement GET /v0/lending/disbursements/{disbursement_id} Retrieve a disbursement object. > [!WARNING] > > The Disbursement API is currently not available for new partners. Please refer to the [Lending and Overdraft](/guides/lend/lending-and-overdraft-data-flow) overview for more details about the latest version of the product. # Get an Access Token Source: https://docs.lead.bank/api-reference/endpoint/oauth/get-an-access-token POST /v1/oauth/token Exchange your client credentials for an access code. # Simulate Advance ACH Source: https://docs.lead.bank/api-reference/endpoint/simulation/simulate-advance-ach POST /v1/simulate/ach/{ach_id}/advance Advance an ACH in Sandbox. # Simulate Advance Wire Source: https://docs.lead.bank/api-reference/endpoint/simulation/simulate-advance-wire POST /v1/simulate/wires/{wire_id}/advance Advance a Wire in Sandbox. # Simulate Advance Wire Source: https://docs.lead.bank/api-reference/endpoint/simulation/simulate-advance-wire-v2 https://docs.lead.bank/openapi.json POST /v2/simulate/wires/{id}/advance Advance a Wire in Sandbox. > [!NOTE] > > See [Errors](/api-reference/using-the-api/errors-v2) for the common errors every v2 endpoint can return. # Simulate Incoming ACH Source: https://docs.lead.bank/api-reference/endpoint/simulation/simulate-incoming-ach POST /v1/simulate/ach/incoming_ach Simulate an incoming ACH. # Simulate Incoming ACH Return Source: https://docs.lead.bank/api-reference/endpoint/simulation/simulate-incoming-ach-return POST /v1/simulate/ach/{ach_id}/incoming_return Simulate an incoming Return. # Simulate Incoming Instant Payment Source: https://docs.lead.bank/api-reference/endpoint/simulation/simulate-incoming-instant-payment POST /v1/simulate/instant_payments/incoming Simulate an incoming instant payment. # Simulate Incoming Instant Payment Return Source: https://docs.lead.bank/api-reference/endpoint/simulation/simulate-incoming-instant-payment-return POST /v1/simulate/instant_payments/{instant_payment_id}/incoming_return Simulate an incoming instant payment return. # Simulate Incoming Instant Payment Return Request Source: https://docs.lead.bank/api-reference/endpoint/simulation/simulate-incoming-instant-payment-return-request POST /v1/simulate/instant_payments/{instant_payment_id}/incoming_return_request Simulate an incoming instant payment return request. # Simulate Incoming Instant Payment Return Request Acceptance Source: https://docs.lead.bank/api-reference/endpoint/simulation/simulate-incoming-instant-payment-return-request-acceptance POST /v1/simulate/instant_payments/{instant_payment_id}/incoming_return_request_acceptance Simulate an incoming instant payment return request acceptance. # Simulate Incoming Instant Payment Return Request Rejection Source: https://docs.lead.bank/api-reference/endpoint/simulation/simulate-incoming-instant-payment-return-request-rejection POST /v1/simulate/instant_payments/{instant_payment_id}/incoming_return_request_rejection Simulate an incoming instant payment return request rejection. # Simulate Incoming Wire Source: https://docs.lead.bank/api-reference/endpoint/simulation/simulate-incoming-wire POST /v1/simulate/wires/incoming Simulate an incoming Wire. # Simulate Incoming Wire Return Source: https://docs.lead.bank/api-reference/endpoint/simulation/simulate-incoming-wire-return POST /v1/simulate/wires/{wire_id}/incoming_return Simulate an incoming Wire Return. # Simulate Incoming Wire Return Request Source: https://docs.lead.bank/api-reference/endpoint/simulation/simulate-incoming-wire-return-request POST /v1/simulate/wires/{wire_id}/incoming_return_request Simulate an incoming wire return request. # Simulate Incoming Wire Return Request Acceptance Source: https://docs.lead.bank/api-reference/endpoint/simulation/simulate-incoming-wire-return-request-acceptance POST /v1/simulate/wires/{wire_id}/incoming_return_request_acceptance Simulate an incoming wire return request acceptance. # Simulate Incoming Wire Return Request Acceptance Source: https://docs.lead.bank/api-reference/endpoint/simulation/simulate-incoming-wire-return-request-acceptance-v2 https://docs.lead.bank/openapi.json POST /v2/simulate/wires/{id}/incoming_return_request_acceptance Simulate an incoming wire return request acceptance. > [!NOTE] > > See [Errors](/api-reference/using-the-api/errors-v2) for the common errors every v2 endpoint can return. # Simulate Incoming Wire Return Request Rejection Source: https://docs.lead.bank/api-reference/endpoint/simulation/simulate-incoming-wire-return-request-rejection POST /v1/simulate/wires/{wire_id}/incoming_return_request_rejection Simulate an incoming wire return request rejection. # Simulate Incoming Wire Return Request Rejection Source: https://docs.lead.bank/api-reference/endpoint/simulation/simulate-incoming-wire-return-request-rejection-v2 https://docs.lead.bank/openapi.json POST /v2/simulate/wires/{id}/incoming_return_request_rejection Simulate an incoming wire return request rejection. > [!NOTE] > > See [Errors](/api-reference/using-the-api/errors-v2) for the common errors every v2 endpoint can return. # Simulate Incoming Wire Return Request Source: https://docs.lead.bank/api-reference/endpoint/simulation/simulate-incoming-wire-return-request-v2 https://docs.lead.bank/openapi.json POST /v2/simulate/wires/{id}/incoming_return_request Simulate an incoming wire return request. > [!NOTE] > > See [Errors](/api-reference/using-the-api/errors-v2) for the common errors every v2 endpoint can return. # Simulate Incoming Wire Return Source: https://docs.lead.bank/api-reference/endpoint/simulation/simulate-incoming-wire-return-v2 https://docs.lead.bank/openapi.json POST /v2/simulate/wires/{id}/incoming_return Simulates an incoming return wire against an outgoing wire in sandbox. Automatically advances to posted on creation. > [!NOTE] > > See [Errors](/api-reference/using-the-api/errors-v2) for the common errors every v2 endpoint can return. # Simulate Incoming Wire Source: https://docs.lead.bank/api-reference/endpoint/simulation/simulate-incoming-wire-v2 https://docs.lead.bank/openapi.json POST /v2/simulate/wires/incoming Simulates an incoming wire against a creditor account in sandbox. Automatically advances to posted on creation; no call to advance required. > [!NOTE] > > See [Errors](/api-reference/using-the-api/errors-v2) for the common errors every v2 endpoint can return. # Create a Subledger Balance Source: https://docs.lead.bank/api-reference/endpoint/subledger-balance/create-a-subledger-balance POST /v0/subledger_balances Create a Subledger Balance object. The newly created Subledger Balance will have a `status` of `active` and a `status_reason` of `active`, and a unique `id` with prefix `subledger_balance_` will be auto-generated. # Retrieve a Subledger Balance Source: https://docs.lead.bank/api-reference/endpoint/subledger-balance/retrieve-a-subledger-balance GET /v0/subledger_balances/{id} Retrieve a Subledger Balance object. # Changelog Source: https://docs.lead.bank/changelog Source of record for released Lead platform, API, reporting, and operational changes, including new features, fixes, and breaking changes. > [!WARNING] > > **Note:** Some historical upcoming changes remain in this Changelog because they were published before the launch of the [**Upcoming Changes**](/upcoming-changes) page on June 10, 2026. Going forward, future changes will be published in **Upcoming Changes** and moved to the Changelog once released. **11/05/2026** 🛠 Improvement ## Travel Rule Enforcement on Incoming Instant Payments Effective November 4, 2026, Lead rejects incoming FedNow payments that fall under the Travel Rule and don't include the debtor address. The same rule applies to RTP payments when RTP launches on November 16, 2026. ### **Why We Made This Change** Incoming payments that fall under the Travel Rule must include the debtor address. ### **What Changed** * **Which payments:** Incoming business-to-business instant payments of \$3,000 or greater. * **What Lead rejects:** Payments where the sending bank leaves out the debtor address. * **How you see it:** Lead sends a `.rejected` webhook, and the `rejection` hash includes the reason `regulatory` and this detail: "Business-to-business payments of \$3,000 or greater must include debtor address." ### **What You Need To Do** No API or integration changes are needed. If an end customer's pay-in is rejected, ask them to check that their bank includes the debtor address when initiating the payment. The payment can be resent once the sending bank includes it. For outgoing instant payments that fall under the Travel Rule, Lead sends the debtor address from your saved entity information. ### **Who This Affects** This update applies to every partner with Instant Payments enabled to receive payments. Based on September 2026 data, fewer than 0.1% of incoming instant payments are affected. For more detail, see: * [Validations & Best Practices](/products/instant-payments/validations) **11/03/2026** 🐛 Fix ## Entity API Now Rejects Concurrent Writes with `conflict` We've fixed two issues that let an update to `POST` or `PATCH /v0/entities` go missing without a clear signal to your integration. When two requests change the same entity at the same time, Lead now applies one and rejects the other with `409 conflict`, the code described in our API best-practices guidance. ### **Why We Made This Change** * **Overwritten updates:** When two requests changed the same entity at the same time, both can returned `200`, and the later write replaced the earlier one's change. * **Misleading error code:** A request that lost to a concurrent change returned `409 idempotency_key_conflict`. That code indicates a problem with the `Idempotency-Key` itself. Integrations that handled it as a key problem dropped the update, even though Lead hadn't applied it. ### **What Changed** #### **Concurrent Writes No Longer Overwrite Each Other** When two API requests change the same entity at the same time, Lead applies the first to commit and returns `200`. Lead rejects the other with `409 conflict` and does not apply it. Creating an entity also returns `409 conflict` if another request changes an entity it links to, such as an owner or control person, at the same time. #### **Rejected Concurrent Writes Return `conflict`** Since November 2, 2026, a request that loses to a concurrent change returns `409 conflict` instead of `409 idempotency_key_conflict`. `idempotency_key_conflict` now only indicates a problem with the idempotency key, and its `detail` explains how to recover. This table compares the previous and new responses: | **Situation** | **Previous Response** | **New Response** | | :- | :- | :- | | Two requests update the same entity at the same time | Both return `200`, and the later write replaces the earlier one's change | First to commit returns `200`; the other returns `409 conflict` (not applied) | | A create links an entity that another request changes at the same time | `200` with the new link lost, or `400 duplicate_customer_id` | `409 conflict` (not applied) | | Request lost to a concurrent change (not applied) | `409 idempotency_key_conflict` | `409 conflict` | | Problem with the idempotency key, such as the same key is still in progress or the key is reused with a different request body | `409 idempotency_key_conflict` | `409 idempotency_key_conflict`, with a clearer `detail` | ### **What You Need To Do** On any `409` from the Entity API, retry with the same idempotency key and request body. If your original request succeeded, you'll receive its original response. If Lead rejected it, the retry applies your change to the latest version of the entity. If you reused a key for a different request, use a new key. If your integration doesn't retry `409` responses, add retries. Some requests that used to return `200` now return `409 conflict`, because Lead no longer lets them overwrite another request's change. For the Entity API, this replaces the guidance to resubmit a `conflict` with a new key. Retrying an entity create with a new key can return `409 duplicate_customer_id` instead of your original response. For more detail, see: * [Idempotency](/api-reference/using-the-api/idempotency) * [Errors](/api-reference/using-the-api/errors) ### **Who This Affects** This update applies to the V0 Entity API. You see more `409 conflict` responses if you send concurrent requests that change the same entity. You also see them if you create entities that link the same owner or control person at the same time. If your integration handles `idempotency_key_conflict` specifically, concurrent-write rejections now return `conflict` instead. You do not need to change your requests or schemas. **10/30/2026** 🛠 Improvement ## Multi-Card Program File Updates We've updated our network settlement processing to support multiple card products under the same program, including programs with different funds flows (for example, debit and credit card products operating on the same card network). This enhancement expands the flexibility of our card infrastructure and lays the foundation for additional card product support in the future. If you haven't migrated and offer one card product with Lead, you don't need to change anything. You must migrate when you offer a second card product with Lead. ### **Action Required** * **You already migrated:** No action is required. * **You offer one card product and haven't migrated:** No action is required until you offer a second card product with Lead. * **You offer a second card product with Lead:** You must migrate. ### **Why We Made This Change** Network settlement processing used to assume a single card product per program. As partners expand into multiple card products and card networks, we updated our settlement infrastructure to support more complex program structures while keeping settlement and transaction reporting accurate. ### **What Changes When You Migrate** #### **Network Settlement File Paths** The network settlement file path includes a settlement reporting identifier. **Before Migration** ```text theme={null} /network-settlement/{card_network}/ ``` **After Migration** ```text theme={null} /network-settlement/{card_network}/{settlement_reporting_id} ``` This identifier lets you run multiple card products on the same card network. #### **Transaction File Requirements** The `BIN` field is required for transactions where: * `type = card` * `type = oct` * `type = aft` You must provide the BIN enum value for each of these transactions. Lead gives you your program-specific BIN values when you migrate. ### **What You Need To Do** When you offer a second card product with Lead, you must migrate: 1. Tell Lead you plan to offer a second card product. 2. Update any systems that consume network settlement files to support the settlement reporting identifier in the file path. 3. Update transaction file generation to include the BIN enum values. 4. Check downstream processes that rely on settlement file locations. 5. Test file ingestion and processing. Lead provides your program-specific: * Settlement reporting identifiers * BIN enum values * Testing and implementation guidance ### **Why This Matters** If you migrate without completing these updates, you risk: * Failed settlement file processing * Missing settlement data * Transaction file validation errors * Delays in reconciliation and reporting workflows ### **Timeline** | **Milestone** | **Date** | | - | - | | Lead announced the change | June 10, 2026 | | Wave 1 rolled out | September 30, 2026 | | Wave 2 rolled out | October 30, 2026 | | All other programs | You migrate when you offer a second card product | **10/30/2026** 🛠 Improvement ## corridor\_type Now Available on the V1 Wires API You can now identify whether a wire is domestic or international directly through the V1 Wires API. This field was originally planned as an improvement for Wires API V2. We're adding it to V1 so you can use it before migrating to V2. ### **Why We Made This Change** The `corridor_type` field lets you price, screen, and report on domestic and international wires without maintaining your own classification logic. ### **What Changed** * **New response field:** V1 wire objects now include `corridor_type`, with values `domestic` or `international`. * **New list filter:** List Wires accepts `corridor_type` as a query parameter, allowing you to filter for domestic or international wires. Lead sets `corridor_type` based on the banks included in the wire message, regardless of whether the wire moved through SWIFT or Fedwire. A wire is international if any bank in the payment chain is located outside the U.S.; otherwise, it is classified as domestic. This is an additive, non-breaking change. * [Retrieve a wire API reference](/api-reference/endpoint/wire/retrieve-a-wire-v1) * [List all wires API reference](/api-reference/endpoint/wire/list-all-wires-v1) * [The Wire object](/products/wire/wire-object) ### **What You Need To Do** No action is required. If you currently derive domestic vs. international yourself, you can use `corridor_type` instead. ### **Who This Affects** This update applies to everyone using the V1 Wires API. **10/28/2026** 🛠 Improvement ## Settlement Amount Rounding We've clarified the [Settlement Amount guide](/products/funding-and-receivables/sales-settlement-amount) to show how Lead has been rounding settlement amounts. Nothing about the calculation has changed. * Lead calculates `imputed_interest_accrued` and `settlement_amount` for each loan to 6 decimal places, as reported in the Sales Request. * The amount Lead collects for a sale is the sum of every loan's `settlement_amount`, rounded once to the cent. Lead does not round each loan. * The worked examples previously showed each loan rounded to the cent. They now show the 6 decimal place values, and the guide includes a rounding example and how to reconcile per-loan amounts to the sale total. > [!TIP] > > Settlement Amount only applies to credit programs where imputed interest is charged. **10/06/2026** 🛠 Improvement ## New Balances and Transactions File Alert We’re adding a new Slack alert to indicate when the next day’s Balance and Transactions files can be submitted. The alert provides a definitive signal for submission timing, complementing the existing success alert, which confirms only that a file processed correctly.This is particularly helpful when a program is behind and the previous day’s files have not yet finished processing. This is an additive change to the existing file alert workflow. ### **Why We Made This Change** The previous successful-processing alert confirmed that a file was received and validated, but it was not intended to indicate readiness to submit the next file. The new alert closes that gap by providing a dedicated signal for when the next day's files can be submitted. ### **What Changed** Lead is adding a new Slack alert related to Balance and Transactions files. * The previous alert confirmed that files were submitted and validated successfully will continue to be sent. * The new alert will indicate when the next day's files can be submitted. * The new alert is intended to distinguish successful file validation from readiness to submit the next day’s files. ### **What You Need To Do** No action is required if you do not use Slack alerts to drive file-processing workflows. If you process Slack alerts programmatically: 1. Update your alert-handling logic to consume the new alert. 2. Use the alert to trigger any corresponding action, such as submitting the next day’s files. 3. Test the updated workflow before the alert is enabled for your program. ### **What Happens if You Don't Act** Your existing file-submission process will continue to work, but any automation that relies on Slack alerts will not receive or act on this new readiness signal unless it is updated to consume the alert. Those workflows may need to continue relying on existing error messages or manual checks to determine when to submit the next day’s files. ### **Who This Affects** This update applies to everyone with a deposit, debit, and/or prepaid program. **9/30/2026** 🛠 Improvement ## **Instant Payments Return API Updates** We are actively adding support for RTP as a payment rail. In preparation, we have updated portions of the Instant Payments API to align return request functionality across FedNow and RTP. These changes affect return-related fields and endpoints and introduce updated validation requirements for return reasons and supporting information. ### **Why We Made This Change** As we expand support for RTP and continue to align behavior across instant payment networks, we're standardizing how return requests and return responses are handled. These changes simplify the API, remove unsupported return scenarios, and ensure consistent behavior across instant payment rails. ### **What's Changing** #### **Reduced Maximum Length for** `additional_information` The `additional_information` field is limited to **105 characters** for the following endpoints: * `/return` * `/request_return` * `/simulate/incoming_return` * `/simulate/incoming_return_request` Requests exceeding this limit will fail validation. #### **Updated Return Request Reason Values** The following reason values are no longer supported on: * `/request_return` * `/simulate/incoming_return_request` Removed values: * `narrative` * `service_not_rendered` The following values are no longer supported on: * `return_requests.reason` Removed values: * `narrative` * `per_agent_request` * `service_not_rendered` #### **Changes to Return Request Rejections** The `/reject_return_request `endpoint no longer supports: * `additional_information` * `narrative` as a rejection reason The `/simulate/incoming_return_request_rejection` endpoint no longer supports: * `additional_information` * `narrative` and `per_agent_request` as rejection reasons The `return_requests.resolution.rejection_reason` field no longer supports: * `narrative` and `per_agent_request` Requests containing these values will fail validation. ### **What You Need To Do** If you have not already, please do the following: 1. Review any integrations that deal with returns, return requests, or return request responses. 2. Ensure additional\_information values do not exceed 105 characters. 3. Remove any usage of unsupported reason values. ### **Why This Matters** Partners that do not update their integrations may experience: * Validation errors * Failed return requests * Failed return request responses * Operational delays when processing return-related workflows **9/10/2026** 🛠 Improvement ## New Compliance Document Types We've added three compliance document types — `cardholder_agreement`, `periodic_statement`, and `autopay_authorization` — and reclassified `deposit_agreement` as a consent document. ### **What's Changing** The Applications and Accounts files and APIs accept three new values for `documents[].type`: * `cardholder_agreement` — requires `consented_at` * `periodic_statement` — requires `displayed_at` * `autopay_authorization` — requires `consented_at` `deposit_agreement` now requires `consented_at` instead of `displayed_at`, matching how the agreement is collected. No partner had submitted a `deposit_agreement` document before this change (verified against production data), so no existing integration is affected. See the updated [Compliance Documents](/file-reference/documents/compliance-documents) reference for the full list of types and required timestamps. **8/5/2026** 🛠 Improvement ## New Entity Role: Minor Account Holder We're introducing a new Entity role, `minor_account_holder`, that enables approved programs to offer accounts to individuals aged 16–17. ### **What's Changing** The Entity API adds one enum value, `minor_account_holder`, to two existing fields: * `intended_roles` on POST and PATCH requests * `role_details[].name` on GET responses There is no new API version and no schema change. Data requirements match the `account_holder` role, with a minimum age of 16 instead of 18. Eligibility transitions automatically to `account_holder` when the entity turns 18. See the updated [Roles](/products/entity/roles) documentation. The Accounts API adds one validation: `credit_with_underwriting` requires at least one adult `account_holder`-eligible account holder. Requests that do not meet it return a 422 `parameters_invalid` response with reason `account_requires_adult_account_holder`. This does not affect existing accounts or capabilities. **7/1/2026** 🛠 Improvement ## Slack File Alerts Now Include File Paths As part of an internal platform update, [Slack file alerts](/file-reference/delivery/slack-alerts) will begin including the full file path along with the filename wherever a file is referenced. This applies to both success and error alerts. #### **Why We’re Making This Change** Including the full file path gives you clarity on exactly where Lead received the file. This makes it unambiguous which file an alert refers to, so you can quickly locate and act on the file in question. #### What's Changing Any reference to a file in a Slack alert will now include its full file path. **Current Format** ```text theme={null} File 2026-04-30_transactions_v6.csv failed validation. ``` **New Format** ```text theme={null} File transactions/2026-04-30_transactions_v6.csv failed validation. ``` > [!TIP] > > No changes are being made to the file schema, folder structure, validations, or error codes. This is a presentation-only change to the text of Slack alerts. #### What You Need To Do No action is required for most partners. If you have downstream automation that parses or matches on the exact filename string in Slack alert messages, update it to account for the file path now being prepended to the filename. **6/8/2026** 🛠 Improvement ## Upcoming: Error Code Renames for Balances **Coming August 4, 2026** To make our validation error codes clearer and more accurate, we're renaming several balance-related error codes. These codes are returned during [Balances and Transactions](/file-reference/balances-and-transactions/balances-schema) file validation and appear in [Slack alerts](/file-reference/delivery/slack-alerts) and the [Errors reference](/file-reference/delivery/errors). **What's changing** * The legacy term `account_balance` is being replaced with `balance` — "account balance" is not a concept in the current product. * `balance_cannot_be_closed_with_processing_funding` is being renamed to accurately reflect that the validation applies to *both* the `closed` and `receivable_transferred` (terminal) statuses. | Current error code | New error code | | - | - | | `outstanding_card_account_balance_activity_mismatch` | `outstanding_card_balance_activity_mismatch` | | `previous_active_card_account_balance_missing` | `previous_active_card_balance_missing` | | `total_charged_off_amount_mismatch_card_account_balance` | `total_charged_off_amount_mismatch_card_balance` | | `total_interest_transaction_amount_mismatch_card_account_balance` | `total_interest_transaction_amount_mismatch_card_balance` | | `total_payment_transaction_amount_mismatch_card_account_balance` | `total_payment_transaction_amount_mismatch_card_balance` | | `total_reward_transaction_amount_mismatch_card_account_balance` | `total_reward_transaction_amount_mismatch_card_balance` | | `total_transaction_amount_mismatch_account_balance` | `total_transaction_amount_mismatch_balance` | | `transaction_missing_account_balance` | `transaction_missing_balance` | | `transaction_missing_card_account_balance` | `transaction_missing_card_balance` | | `balance_cannot_be_closed_with_processing_funding` | `balance_cannot_be_terminal_with_processing_funding` | > [!WARNING] > > **Action Required — Breaking Change** > > If you have downstream processes that key off these error code strings, update them to the new codes before **August 4, 2026**. After this date the previous codes will no longer be returned. Reach out to your Technical Account Manager (TAM) with any questions. *** ## Clearer Balance Mismatch Error Messages Balance component-sum mismatch errors now show the **expected sum** and the **delta** from your submitted value. **What's new** Error messages for balance mismatches (e.g. `unexpected_balance`, `unexpected_past_due_balance`, `unexpected_dispute_balance`, and `unexpected_charge_off_balance`) now follow this format, with the specific field, components, and values varying by error code. The example below is illustrative: > `balance` (316125.78) was expected to be 316124.78 (delta: 1.00), which is the sum of `outstanding_principal` (284937.42), `outstanding_interest` (19688.13), and `outstanding_fee` (11499.23). Example values shown for Sample ID `wallet-abc123`. > [!NOTE] > > **No Action Required** > > This is a non-breaking change to the Details in Slack error messages. No changes are being made to the file schema, validations, or error codes. These updates apply to both [Business Rules](/file-reference/delivery/errors#business-rules) and [Cross-File Reconciliation](/file-reference/delivery/errors#cross-file-reconciliation) balance mismatch validations. *** ## SLA Monitoring Now Covers Funding Programs SLA monitoring tracks whether your program's daily processing workflows have completed within the expected time window. When a workflow doesn't finish on time, an alert is posted to your monitoring Slack channel so the delay can be investigated. SLA monitoring alerts had not been turned on for programs using the Funding API. Now programs will start seeing these alerts, giving you and our team timely visibility and alerting when a workflow has not been completed in time. **6/2/2026** ✨ New ## New Validation: `funding_fee_amount_mismatch` We've added a new cross-file reconciliation validation for disbursement transactions linked to a Funding object. **What's new** When a transaction has `type` = `disbursement`, `transfer_type` = `internal_transfer`, and `funding_id` is populated, the `fee_amount` must equal the `other_fees.borrower_origination_fee_amount` on the associated Funding object. Submissions where these values differ will fail with a `funding_fee_amount_mismatch` error. **Why this matters**\ This validation ensures that origination fees reported in the Transactions file are consistent with what was recorded on the Funding object, preventing reconciliation discrepancies downstream. * [Transactions Schema](/file-reference/balances-and-transactions/transactions-schema) * [Errors](/file-reference/delivery/errors) **5/16/2026** 🛠 Improvement ## Clearer Error Details for Balances and Transactions Files **Coming May 26, 2026** On May 26th, we will be updating the Details for several validation errors for the [Balances](/file-reference/balances-and-transactions/balances-schema) and [Transactions](/file-reference/balances-and-transactions/transactions-schema) file schemas to be more specific and easier to act on. > [!NOTE] > > **No Action Required** > > These are non-breaking changes to the Details in Slack error messages. No changes are being made to the file schema or validations. Please reach out to your Technical Account Manager (TAM) if you have any questions. ### Balances File * Error messages related to balance mismatches (e.g., overall balance, outstanding principal/interest/fees, past-due amounts) now include the **Sample ID** of the specific record that failed. * Field names in error details are also now formatted to match the field names in the file schema exactly (e.g., `outstanding_principal` instead of "Outstanding principal"). ### Transactions File The error message for the `transaction_activity_check` validation now provides guidance based on the transaction `type`: * **`type = disbursement`** — `principal_amount` must be greater than zero; `interest_amount` and `fee_amount` must be zero. * **`type = interest_accrued`** — `interest_amount` must be greater than zero; `principal_amount` and `fee_amount` must be zero. * **`type = fee`** — `fee_amount` must be greater than zero; `principal_amount` and `interest_amount` must be zero. **5/5/2026** ✨ New ## USD International Wires Now Available USD International Wires are now generally available. You can send and receive USD international wires using the existing Wires API. ### Getting Started * **Setup & Configuration**: [International Wires Guide](/products/wire/international-wires) * **API Reference**: [Existing Wires API](/api-reference/endpoint/wire/create-a-wire-v1) > [!WARNING] > > **Enablement Required** > > Additional due diligence is required before enabling international wires for end users. To begin enablement, contact your Program Manager. *** ## Upcoming: Creditor Name Match Enforcement (Wires) **Coming June 30, 2026** To reduce fraud and misdirected funds, all incoming wires (domestic and international) will soon be validated against the receiving account’s legal name. **What’s Changing** * The creditor name on the wire must closely match the account’s legal entity name * If names don’t match, the payment will be **rejected and/or returned** * Rejection reason: `creditor_name_mismatch` **How Matching Works** * Individuals: approximate match on first + last name * Businesses: approximate match on legal name or DBA **Examples** > [accordion] Approved > > * `thomas thompson` → THOMAS THOMPSON RABINE > * `triangle lab` → TRIANGLE LABORATORIES INC > * `Justin hurwanti` → JUSTIN NURWANTI > [accordion] Rejected > > * `adl febriana` → Adi Daniel > * `james har` → Mohamed Haruna > * `John Smith` → ABC Global Logistics Commodities > [!WARNING] > > **Action Required** > > Ensure senders use the correct creditor name when initiating wires. We strongly recommend addressing mismatches now to avoid rejected payments when enforcement begins June 30, 2026. *** ## Creditor Name Match Enforcement (Instant Payments) **Generally available** To reduce fraud and misdirected funds, instant payments on account-validated rails (`pix` and `spei`) are validated against the receiving account’s legal name. Payments on other rails are not name-matched against the account. **How Matching Works** * The creditor name on the payment must closely match the legal name registered on the receiving account * Individuals: approximate match on first + last name * Businesses: approximate match on legal name or DBA **Rejection Reasons** Returned as `rejection_reason` on the payment (`GET /v1/blockchain_payment/{id}` and webhooks). Distinguish **retryable** from **terminal** to build the right resubmit logic: * `name in request and name on account do not match` — **terminal**. The creditor name did not match the account’s legal name. Do not resubmit unchanged; correct the creditor name to match the account. * `name could not be validated` — **retryable**. The receiving account’s name was not validated in time. Resubmit the same payment; it reuses the held account and succeeds once validation completes. * `account closed` — **terminal**. The receiving account is closed. > [!WARNING] > > **Action Required** > > Ensure the creditor name on instant payments to `pix` and `spei` matches the recipient’s account name to avoid rejected payments. *** ## Coming Soon: Return Requests API **Coming Q3 2026** We’ll be releasing a Return Requests API in Q3 to support wire return workflows. The API will allow you to: * Initiate return requests * Respond to incoming return requests Documentation: * [Guide](/products/wire/return-requests) (Preview) > [!WARNING] > > **Upcoming Action Will Be Required** > > You will be required to integrate with this API later this year. We will provide more details on enforcement dates, but we will ensure you have plenty of awareness so you can properly plan the effort on your roadmap. **4/28/2026** ✨ New ## New Transfer Types: International Wire and Instant Payment The Transactions file now supports two new `transfer_type` values for International Wires and FedNow / RTP Instant Payments. **New transfer types** * `international_wire` — use for international wire transactions. * `instant_payment` — use for instant payment transactions processed via RTP or FedNow. Report all instant payments as `instant_payment` regardless of the underlying rail. **Eligible combinations** Both transfer types are valid with the following transaction types: * **Deposit balances:** `debit` (applied and reversed), `credit` (applied and reversed) * **Credit balances:** `payment` (applied and reversed), `refund` (applied and reversed) **transfer\_ids requirement** If a transaction using `international_wire` or `instant_payment` was initiated via a Lead API, include the corresponding transfer ID in the `transfer_ids` field. * [Transactions Schema](/file-reference/balances-and-transactions/transactions-schema) * [Transaction Types](/products/balances-and-transactions/transaction-types) **4/15/2026** 🛠 Improvement ## Expanded Repayment Details for Lending The `repayment_details` object on the Subledger Balance API now supports a wider range of repayment schedules. New `expected_payment_frequency` options include: * `fixed_interval` — set a custom interval in days using `expected_payment_frequency_interval_days` * `maturity` — a single payment at the end of the loan term * `variable` — irregular or non-standard repayment schedules * `business_daily`, `semi_monthly`, `semi_annually` — additional standard frequencies You can also specify `expected_first_payment_date`, `expected_first_payment_amount`, `expected_last_payment_date`, `expected_last_payment_amount`, and `expected_payment_amount` to define the full repayment structure. Parallel changes have also been made to the Balances Schema so that these expanded repayment schedules can also be reported via Balance file submissions. * [Subledger Balance API reference](/api-reference/endpoint/subledger-balance/create-a-subledger-balance) * [Balances Schema](/file-reference/balances-and-transactions/balances-schema) *** ## Improved Validation Detail for `transaction_type_invalid_activity_check` We've updated the error detail for `transaction_type_invalid_activity_check` to provide clearer guidance on expected field values for each transaction type within the file interface. **What's Changed**\ The error message now specifies exact validation rules for `principal_amount`, `interest_amount`, and `fee_amount` based on the transaction `type`. **Updated validation details** * **Disbursement** * `principal_amount` must be a valid number **greater than zero** * `interest_amount` must be **zero** * `fee_amount` must be **zero** * **Interest Accrued (interest\_accrued)** * `principal_amount` must be **zero** * `interest_amount` must be a valid number **greater than zero** * `fee_amount` must be **zero** * **Fee** * `principal_amount` must be **zero** * `interest_amount` must be **zero** * `fee_amount` must be a valid number **greater than zero** **Why this matters**\ This update makes validation expectations more explicit, helping you more quickly identify and resolve file submission errors. *** ## Upcoming Update to Success Alert Messaging We're making a small update to the text copy used in successful Slack alerts. This update will go into effect on **April 27, 2026.** **What's changing** We're standardizing alert structure (program + environment + context) for improved consistency. Here's a quick view of the shift: > [accordion] Submitted Files Process Successfully > > *Current* > > 🟢 the following files ran successfully in \ for \ > > File: \ > > *New* > > 🟢 Success in \ \ environment for \ \ > **File:** \ > > *Current* > > \[\] > > 🟢 the following files ran successfully for \ > > File: \ > > *New* > > 🟢 Success in \ \ environment for batch ID \  \ > **File:** \ > [accordion] Sales Request File Posted Successfully > > > [!NOTE] > > > > Only applies to credit-based programs. > > *Current* > > 🟢 Sales Request successfully generated in prod for \ > > *New* > > 🟢 Success in \ \ environment for \ Sales Request File **4/6/2026** ✨ New ## Instant Payment API Updates We've made two changes to the Instant Payments API: * **Description field limit:** The `description` field when creating an instant payment now has a **140-character maximum**. Requests exceeding this limit will be rejected. * **Removed `accepted_amount`:** The `accepted_amount` field has been removed from the return request resolution schema, as partial returns are not supported. * [Instant Payments API Reference](https://docs.lead.bank/api-reference/endpoint/instant-payment/create-an-instant-payment) *** ## Payment Identifiers for International Wires In support of our international wires launch, we’re updating how payment identifiers are handled. **Effective April 21, 2026**, Lead will automatically populate select payment identifier fields when creating an outgoing wire via the [Create a Wire API](https://docs.lead.bank/api-reference/endpoint/wire/create-a-wire-v1). * **End-to-End Identification:** If `payment_identifiers.end_to_end_identification` is not provided, Lead will automatically generate and populate this value. * **Instruction Identification:**`payment_identifiers.instruction_identification` will now always be system-generated. These identifiers ensure every wire includes the tracking data required for both domestic and international processing. *** ## Accounts API: Batch and Delete Entity Relationships Two new endpoints are available for managing entity relationships on accounts: * **Batch create:** Associate multiple entities with an account under a single relationship type in one request using `POST /v0/accounts/{id}/entity_relationships/batch`. * **Delete:** Remove an entity relationship from an account using `DELETE /v0/accounts/{id}/entity_relationships/{entity_id}`, with an optional `relationship_type` filter. * [Accounts API Reference](/api-reference/endpoint/account/create-an-account) *** ## Entity API: SSN Now Accepted for Single-Member LLCs Single-member LLCs that do not have an EIN can now use a Social Security Number (SSN) for tax identification when creating or updating an entity. This reduces friction for sole-owner businesses that have not yet obtained an EIN. * [Entity API Guide](/products/entity/overview) *** ## Settlement Amount Documentation for Cancellations We've added detailed examples for how **full and partial loan cancellations** affect settlement amounts during the hold period. If a disbursement is fully cancelled with an `original_transaction_id` provided, imputed interest is zeroed out. For partial cancellations, imputed interest is recalculated based on the remaining receivable amount. * [Settlement Amount Guide](/products/funding-and-receivables/sales-settlement-amount) *** ## Customer File Submission Requirements Clarified We've clarified how Customer and Customer Relationship files should be submitted. Each day, submit a Customer file containing all new records created the previous day along with any updates to existing records. Do not include records that have not changed. * [Customer File Overview](/file-reference/customer/overview) **3/30/2026** 🛠 Improvement ## Instant Payment API Updates We've made three changes to our [Instant Payments API](/api-reference/endpoint/instant-payment/create-an-instant-payment) to improve consistency with our existing Wires API. Here's what we changed: 1. **Return Endpoint:** We removed `amount` and `currency` fields from the request body because partial outgoing returns will not be supported at launch. 2. **Enum Alignment:** We renamed the values of the four enums that appear in the Instant Payment object to match the Wires API. 3. **Separate Enums:** We separated three of the four enums into outgoing and incoming sets. > [accordion] Detailed list of the enum changes > > ### **Rejection Reasons** > > **Updated values** > > * `closed_creditor_account` -> `account_closed` > * `invalid_creditor_account_number` -> `creditor_account_number_invalid` > * `blocked_account` -> `account_blocked` > * `inconsistent_end_customer` -> `creditor_name_mismatch` > * `missing_or_incorrect_creditor_address` -> `creditor_address_incorrect` > * `invalid_creditor_identification` -> `creditor_identification_invalid` > * `duplicate` -> `duplication` > * `regulatory` -> `regulatory_reason` > * `account_number_not_active` -> `account_number_incorrect` > * `unexpected_routing_number` -> `routing_number_format_incorrect` > * `unexpected_participant_routing_number` -> `participant_not_on_network` > * `disallowed_counterparty` -> `restricted_by_account_number_controls` > > **Deprecated values** > > * `per_transaction_limit_exceeded` and `ofac_rejection` > > ### Return Reasons > > **New values** > > * `customer_requested` (both directions), `regulatory_reason` (incoming), and `amount_too_low` (incoming) > > **Updated values** > > * `following_return_request` -> `honor_return_request` > * `duplicate` -> `duplication` > * `unknown_sender` -> `initiating_party_unrecognized` > * `fraudulent` -> `fraud_suspected` > * `not_justified` -> `undue_payment` > > **Deprecated values** > > * `other`(now incoming only) > > ### Return Request Reasons > > **New values** > > * `per_agent_request`(incoming) > > **Updated values** > > * `invalid_creditor_account_number` -> `creditor_account_number_invalid` > * `requested_by_customer` -> `customer_requested` > * `duplicate` -> `duplication` > * `fraudulent` -> `fraud_suspected` > * `not_justified` -> `undue_payment` > > **Deprecated values** > > * `other`(now incoming only) > > ### Return Request Rejection Reasons > > **New values** > > * `per_agent_request`(incoming) > > **Updated values** > > * `closed_account` -> `account_closed` > * `insufficient_funds` -> `non_sufficient_funds` > * `customer_decision` -> `customer_requested` > * `no_answer_from_customer` -> `customer_no_response` > * `already_returned` -> `returned_previously` > > **Deprecated values** > > * `other`(now incoming only), and `awaiting_reply` > [!NOTE] > > For questions or to start using the API, contact your Technical Account Manager. **Learn More** * [Instant Payments API Guide](/products/instant-payments/overview) * [Instant Payments API Reference](/api-reference/endpoint/instant-payment/create-an-instant-payment) **3/17/2026** ✨ New ## Accounts API Now In Beta The Accounts API is now available in Beta, supporting real-time workflows for credit, deposit, and overdraft products. It lets you submit end-customer account details in real time, as an alternative to the file-based Accounts workflow, while remaining compatible with existing file-based flows. **Why this matters** The API returns validation errors **inline and synchronously**, so you immediately know whether your data is valid. It works with the Funding API for lending use cases and supports debit and credit flows — previously only available via file submissions. **Debit and credit workflows will be fully available via API in Q2 2026.** Successfully submitted accounts return an **account\_id**, which can be used for Balance and Subledger Balance creation. **Functionality** * Report account records to Lead, specifying supported capabilities (credit/deposit) * Retrieve accounts by ID * Retrieve all account holders, authorized signers, and authorized users * Update account details throughout its lifecycle **Getting Started** The Accounts API is available in **Sandbox** for new partners immediately. Existing partners using the Accounts file workflow will need to coordinate with the Lead team before switching to API-based submission. > [!NOTE] > > For questions or to start using the API, contact your Technical Account Manager. **Learn More** * [Accounts API Guide](/products/accounts/overview) * [Accounts API Reference](https://docs.lead.bank/api-reference/endpoint/account/create-an-account) **3/12/2026** ✨ New ## Wires API Now Supports International Wires We've updated the Wires API to support **international outgoing wires** and added additional fields to the `wire` object for richer incoming wire data. > [!NOTE] > > Review the [USD International Wires guide](/products/wire/international-wires) for full details. ### **New request fields for outgoing wires** You can now provide additional payment details when creating a wire. **Transfer purpose enums** Additional values are now supported for `remittance_details.transfer_purpose.type`, allowing you to describe the purpose of a payment more precisely. This is especially important for international wires, where some countries require detailed purpose codes. New supported values: `tax_payment`, `government_payment`, `benefits_payment`, `pension_payment`, `rent_payment`, `utilities_payment`, `education_payment`, `healthcare_payment`, `charitable_payment`, `refund`, `fee_payment`, `intercompany_transfer`, `investment_payment`, `fx_or_treasury`, `derivatives_payment`, `card_network_settlement` These values are supported for both **domestic** and **international** outgoing wires. **Creditor agent BIC** For outgoing international wires, you can now provide `creditor_agent.business_identifier_code` to identify the beneficiary bank. For domestic wires, continue using `creditor_agent.routing_number.` **Creditor agent local routing identifier** For some international wires, the creditor bank requires a local routing code in addition to the BIC to identify the correct branch. For example, banks in India may require an IFSC, and banks in the UK may require a sort code. You can now provide this information using `creditor_agent.local_routing_identifier.value`. **Instructed agent** You can provide either a BIC (`instructed_agent.business_identifier_code`) or routing number (`instructed_agent.routing_number`) for the `instructed_agent`. This is optional and most commonly used to specify an intermediary bank for international wires. If a BIC is provided, we map it to the corresponding routing number for Fedwire processing. Both values may be stored and returned in the API, but only the routing number is sent in the Fedwire. ### **New response fields on the** `wire` **object** Additional fields may now appear on wire objects, primarily for **incoming wires**. **Creditor agent identifiers** Wire objects may now include additional fields under `creditor_agent`, including: * `business_identifier_code`: BIC identifying the beneficiary bank * `local_routing_identifier`: Country-specific routing code used by some banks to identify the correct branch (for example, a UK sort code or India IFSC) These fields may appear on both incoming and outgoing wires when this information is available. **Ultimate debtor and ultimate creditor** Incoming wire objects may now include: * `ultimate_debtor` * `ultimate_creditor` These fields provide additional visibility into the underlying parties involved in complex payment chains. When available, they may also appear on domestic incoming wires. **Charges** Incoming wire objects may now include a `charges` block when charge details are provided upstream. This may include: * `charge_bearer` * an optional breakdown of individual charges, including: * amount * currency * charging agent details ### What this means for you These updates allow you to: * Send [international wires ](/products/wire/international-wires)with the required bank identifier details * Provide **more specific payment purpose information** * Receive **richer incoming wire data** for investigation, reconciliation, and downstream processing *** ## Account Number Controls for International Wires You can now configure [controls](/api-integrations/account-number/controls) for **outgoing international wires** at the account number level. A new field, `wire_controls.outgoing_international`, is available when creating or updating an account number. This field determines whether international wires are allowed from that account. ### Supported configurations The control supports the following modes: * **Allow all**: Permit all outgoing international wires * **Reject all**: Block all outgoing international wires * **Allowlist only**: Permit international wires only to approved counterparties When using `allowlist_only`, counterparties must be specified using: * **BIC** * **Account identifier** ### Scope These controls apply **only to outgoing international wires**. Domestic wires continue to follow the existing configuration defined by: `wire_controls.outgoing` **3/3/2026** ✨ New ## Applications API Now In Beta The Applications API is now available in beta to support real-time workflows for lending and overdraft products. This API lets you submit underwriting decisions — approved, declined, or canceled — in real time, as an alternative to the file-based application workflow. It's also compatible with existing credit use-cases. For example, you can submit Applications via API even if you plan to use files to report Balances and Transactions. **Why this matters** The file-based workflow surfaces validation errors via Slack notification, 5–10 minutes after submission. The Applications API returns errors synchronously — you know immediately whether your data is valid. For lending use-cases, it also works in tandem with the Subledger Balances and Funding APIs: Lead wants to ensure you are capturing loan application data compliantly before you instruct Lead to originate a loan. The API is also compatible with credit use-cases (e.g., credit cards) more broadly. Approved applications return an `application_id`, which you'll use to create an Account. Accounts are the next step in the lending sequence and an Account API is coming soon. **Functionality** * Submit approved, declined, or canceled applications * Retrieve applications by ID * Retrieve all account holders and authorized signers associated with an application **Getting Started** The Applications API is available in Sandbox for new partners starting today. For existing partners submitting the Applications file, there is coordination required with our team to prepare your program before you can switch to the API. > [!NOTE] > > Please reach out to your Technical Account Manager if you have interest in switching to an API-based flow for submission of Application data. **Learn More** * [Applications API Guide](/api-integrations/applications/overview) * [Applications API Reference](/api-reference/endpoint/application/create-an-application) **2/26/2026** ✨ New ## Instant Payments & International Wires Here's what you need to plan for to take advantage of these **new** products. ### **Instant Payments** Our first offering of instant payments will be **FedNow** — giving you the ability to send and receive payments in \~20 seconds, 24x7x365. **Available Now** * [API Guide](/products/instant-payments/overview) * [API Preview](/api-reference/endpoint/instant-payment/create-an-instant-payment) **Timeline** * API GA: End of April > [!TIP] > > Testing > > * **Sandbox:** Our Sandbox environment will be ready by the end of March. We strongly recommend using this window to prioritize and test receiving instant payments first. > * **Controls:** You will have full control over incoming and outgoing instant payments via "accept," "reject," and "allowlist" settings at the account number level, identical to our current wire controls. > [!NOTE] > > Notes > > * **Critical Deadline of April 30**: When we enable instant payments at the end of April, incoming payments that previously used other rails may "rail hop" to FedNow. > * **Important**: Lead will auto-reject incoming instant payments if a partner is not yet configured to receive them.  > * **Recommendation:** To avoid these missed payments and business disruptions, we strongly recommend all partners be prepared to receive incoming instant payments by this date. ### International Wires **Outgoing USD wires (via intermediaries)** We’ll support the ability to send USD wires to foreign financial institutions (reach depends on correspondent relationships). **Two workflow options:** * Provide your own intermediary by including it directly in the wire request * Use our intermediary lookup and we'll populate the appropriate U.S. correspondent for you **Incoming Wires** We'll be publishing a BIC (Bank Identifier Code) so foreign institutions can send wires using standard correspondent banking details (no U.S.-specific routing required). **Timeline** * Updated API Preview: March * Sandbox: Early April * API GA: End of April **1/20/2026** ✨ New ## **Refreshed Documentation** We've made a significant investment in improving our documentation — and this refresh is just the first step. Our goal is to deliver clearer, more comprehensive, and more useful docs that continue to evolve alongside our products. **What's new in this release:** * **AI-powered search:** Ask questions in plain English and get relevant answers instantly — going beyond simple keyword matches. * **Changelog RSS feed**: Subscribe once and stay up to date on product and documentation changes. * **Faster load times:** Pages now load significantly quicker, so you can get what you need without waiting. * **Improved navigation and structure:** Find the right guide or reference with fewer clicks. This update lays a stronger foundation, but it's not the finish line. We're actively investing in expanding coverage, improving clarity, and keeping documentation in lockstep with new features and releases. We have many more updates planned throughout the year and your feedback plays a key role in how we think about documentation. Please share your suggestions for this site with your Technical Account Manager and they'll pass them along to our product team. **1/05/2026** 🛠 Improvement ## **Updated Slack Alerts for File Validations** We're improving the format and clarity of our file validation alerts in Slack to make issues easier to understand and resolve. This update affects **message content only** — there are no changes to validation logic or alert timing. **What's new** * **Standardized Format:** Alerts now include clear *Error Code*, *Detail*, and *Action* sections. * **Program Visibility:** Each alert specifies the affected program, helping you manage multiple programs. * **Actionable Guidance:** Messages provide concrete steps to fix the issue and resubmit the file. * **Documentation Links:** Alerts include links to relevant docs for faster troubleshooting. > [!NOTE] > > This change will roll out gradually throughout January. Your Technical Account Manager will confirm the timeline for your program. **12/09/2025** ✨ New ## **New Payment Controls at the Account Number Level** You should be able to fully manage ACH, Wires, and Internal Transfers without contacting your bank partner. That's why we've built powerful payment controls directly into our API — giving you the precision to block or allow transactions at the account number level. **Here's how it works** Configure the controls through the create or update [Account number API](/api-reference/endpoint/account-number/create-an-account-number). > [!TIP] > > Reaching out to Lead to block account numbers is no longer required. **Example** * To determine if incoming ACH credit is accepted, use `accept_credit`. * To determine if incoming ACH debit is accepted, use `accept_debit`. The `counterparty_filter` (`accept_all`, `reject_all`, `allowlist_only`) and `counterparty_account_numbers_allowlist` determine which counterparties are allowed to send or receive payments. **Default behavior** If no controls are configured, we default to `accept_credit=true`, `accept_debit=true`, and `counterparty_filter=accept_all`, maintaining the current permissive behavior. > [!TIP] > > The API will automatically prevent contradictory configurations, such as `accept_credit=false` combined with `counterparty_filter=accept_all`. **Start using the new controls today** If you're currently relying on our team to return unexpected payments, it's time to make the switch. By integrating with our APIs, you can automatically block transactions on specific accounts, reducing operational friction and ensuring funds don’t land where they shouldn’t. Save time, reduce risk, and streamline your payment operations — all while avoiding manual returns. Get started with the [Account Number API](/api-reference/endpoint/account-number/create-an-account-number) today. **12/08/2025** ✨ New ## New Originator Endpoint for ACH Transactions We’ve introduced a new `originator` endpoint that gives you more control and flexibility when originating ACH payments. You can now manage multiple ACH Company IDs under a single bank account, making payments more clearly identifiable to your end users. **What’s new** * Configure ACH Company IDs, names, and other Nacha details directly through the new endpoint * Send payments from a single bank account while using multiple company IDs * Improve brand visibility and transparency for end users **What this means for you** * If you originate under a single Company ID: * No changes are required. Lead will automatically handle setup. The only difference you’ll see is that an `originator_id` will now appear on the `account_number` object in API responses. * If you originate under multiple Company IDs: * You’ll be granted access to the new originator APIs. Once enabled, you can create and manage originators and associate them with your end users’ account numbers as needed. > [!NOTE] > > **Further Reading** > > Check out the [Originator API](/api-integrations/originators/overview) and reach out to your Technical Account Manager to discuss if this functionality is right for you. **10/27/2025** ✨ New ## Removal of Single-Character Last Name Validation for Entity API and Customer Files Lead will no longer reject entities with single-character last names at the point of entry. There will no longer be a manual review process for Lead's team to conduct additional due diligence on all individuals with single character last names. This change removes a validation restriction to improve the onboarding experience for legitimate users. This update is particularly beneficial for partners serving international customer bases where single-character last names are more common. **What this means for API and file-based workflows** API Requests (POST and PATCH) and Customer File Uploads for entities with single-character last names will no longer be rejected by this specific validation. Requests that would have previously failed will now be accepted. No manual review submissions via file uploads for entities with single character last names will be required. This is a nonbreaking change as it removes a restriction; it does not introduce a new requirement. **Validation Behavior** | **Previous Validation** | **New Validation** | | :- | :- | | Entities with single-character last names were rejected at the point of entry. | Entities with single-character last names are accepted at the point of entry. *Note: Partners continue to have the business expectation to provide valid last names that match KYC / identification documents.* | **12/16/2025** 🛠 Improvement ## Settlement Amount Calculations We've clarified our documentation and examples in [Settlement Amount guide](/products/funding-and-receivables/sales-settlement-amount) to accurately reflect how Lead has been calculating the SOFR rate for receivables during the hold period by adding the following note: * When applicable, the SOFR rate is set based on the rate published on the last business day of the month prior to the loan’s origination date. This rate remains fixed for the entire hold period, even if the hold period spans multiple months. > [!TIP] > > Settlement Amount only applies to credit programs where imputed interest is charged. **10/15/2025** 🛠 Improvement ## Updates to the Outstanding Credit Balance Payment Attribution We’ve improved how payments are attributed to outstanding credit balances to ensure greater accuracy and consistency. This new method can help reduce your imputed interest charges. **What’s changed** * Refunds and disputes are now applied directly to the original transaction on a first-in, first-out (FIFO) basis. * This clears the oldest outstanding balances first, leading to a more precise calculation of your credit balance and potential interest savings. For more information, see our updated [Settlement Amount guide](/products/funding-and-receivables/sales-settlement-amount). > [!TIP] > > This change only affects credit programs where imputed interest is charged. **09/16/2025** 🛠 Improvement ## KYC Data Requirements For Non-US Authorized Users Lead no longer requires full KYC to be complete for Non-US Authorized Users. Non-US Authorized User data requirements now match those of US entities. **What this means for API and file-based workflows** * API Requests ([POST](/api-reference/endpoint/entity/create-an-entity) and [PATCH](/api-reference/endpoint/entity/update-an-entity)) and [Customer File Uploads](/file-reference/customer/overview) that specify the intended role of `authorized user` will succeed as long as first name, last name, and contact information for the `individual` entity is provided in the request. * You may now use an Entity ID for all [Authorized User use-cases](/products/entity/roles) as long as you have provided a first name, last name, and contact information for the `individual` entity. **What this means for API-only workflows** You may now expect to see `status: active` for the `authorized_user` role in the `role_details` property of a Lead Entity, in POST and PATCH responses as well as GET entity requests. **Requirements** | **Previous Requirements** | **New Requirements** | | :- | :- | | - First name - Last name - Contact method (email or phone number) - If not a US entity1, require full KYC21. An entity is a US entity if they have a US tax identification number 2. Full KYC: Name, date of birth (applies to individual entity only), physical address, and government verified ID | - First name - Last name - Contact method (email or phone number) | **09/07/2025** 🐛 Fix ## Slack Integration Maintenance Completed The scheduled maintenance for our Slack integration has been successfully completed, and all related services have been restored. The maintenance window occurred today, Sunday, September 7, 2025, from 7:00am to 9:00am ET. Our integration is now fully operational. * **Team Availability:** Our team is once again available and reachable via our shared Slack channels. * **Automated Alerts:** Automated Slack alerts indicating successful or failed file processing outcomes are now generating as normal for all files uploaded after 9:00am ET. As mentioned in the initial notice, any files processed during the maintenance window did not generate a Slack alert, and these alerts will not be sent retroactively. File processing itself was not impacted. We appreciate your patience and understanding as we completed this necessary work. If you encounter any issues, please don't hesitate to reach out to our support team. **08/27/2025** 🛠 Improvement ## Entity & Customers File Timestamp Precision Previously, Lead's Entity API and Customers' file truncated timestamps to rounded-down second-precision. For example, a request with the timestamp of `2025-02-10T17:22:34.0001Z`was stored by Lead, returned in GET requests, and used for Lead's business validations, with a value of `2025-02-10T17:22:34.0000Z`. Moving forward, all timestamps submitted by partners for customer/entity records will be persisted with the precision up to nanosecond. Existing timestamps stored in Lead will remain truncated. **Before this change** * POST/upload entity 1: * Request: `2025-02-10T17:22:34.0001Z` * Response:`2025-02-10T17:22:34.0000Z` * GET entity 1 * Response: `2025-02-10T17:22:34.0000Z` **After this change** * GET entity 1 * Response: `2025-02-10T17:22:34.0000Z` * POST/upload entity 2: * Request: `2025-03-10T17:22:34.0001Z` * Response:`2025-03-10T17:22:34.0001Z` * GET entity 2: * Response:`2025-03-10T17:22:34.0001Z` > [!TIP] > > Timestamps may be submitted with less-than-nanosecond precision without issue. For instance, `2025-03-10T17:22:34Z` is a valid timestamp submission, that Lead will treat as `2025-03-10T17:22:34.0000Z` **08/27/2025** 🛠 Improvement ## Documentation Updates We've made a few clarifications to our documentation: * [Transactions Update File Schema](/file-reference/balances-and-transactions/transactions-schema) * Clarified which combinations of transaction and transfer types are permitted to have an updated settlement date * Added additional description to clarify the purpose of the file and when it should be used **08/25/2025** 🛠 Improvement ## Updated Iconography for Slack Alerts We’re changing our iconography for Slack alerts to ensure consistency and make it easier to quickly recognize the type of message you’re receiving. * 🔴 **Error**: a required file or action failed and needs your attention * 🟡 **Warning**: something looks off, but may not block processing * 🟢 **Success**: the file successfully processed or action completed **08/21/2025** 🛠 Improvement ## Documentation Updates We've made a few updates and clarifications to our documentation: * [Accepted Currencies](/file-reference/delivery/currencies) * Removed ANG as an accepted currency. Please use XCG as the currency going forward * Removed SLL as an accepted currency. Please use SLE as the currency going forward * [File Naming Convention](/file-reference/sftp-setup) * Clarified that the file naming convention must be either a generation time (must be an epoch timestamp and not ISO 8601) or version number (v1, v2, etc.). * Validation messages for Sales Request and Sales Response files * We’ve improved Slack validation messages for financial file submissions. You’ll now get clearer step-by-step alerts that make it easier to track progress, spot issues, and follow up as needed. * Here’s what’s new: * **Balance and Transaction File Submission:** You’ll receive a success alert as soon as these files are received and pass initial validation. * **Sales Request Generation:** Once we generate the expected sales for your submitted data, you’ll get a dedicated alert confirming this step. * **Sales Response Submission:** After your sales response file is received and validated, you’ll see a final alert confirming its acceptance. **8/16/2025** ✨ New ## Platform Upgrades FAQs **Why we’re upgrading**\ As part of our continued investment in banking infrastructure, we’re upgrading our systems to improve performance, reliability, and scalability for our clients. This migration is a key component of that effort. **Timeline** * October 15, 2025: Redirect all incoming ACH and Wires to the account numbers and routing numbers listed in the List of Accounts file sent to your Signatories and Trusted Points of Contact. * October 15, 2025 - February 28, 2026: In this phase, we’ll move you to the new platform with a transition and execution plan tailored to your program. Although we don’t anticipate using the full window, we’ve provided a clear timeframe to guide expectations. * March 2026: Upgrade complete. > [accordion] How do I raise questions or concerns? > > Please raise them in Slack. As we move through the project, we’ll provide updates on timelines, milestones, and any required actions there. > [accordion] What happens if we don’t update the routing number by October 15, 2025? > > After this date, any incoming payments to your account using the legacy routing number will be flagged, and we’ll notify you before returning the funds. To ensure a smooth transition, please redirect all incoming payments before then. > [accordion] Who do we contact if we accidentally sent a payment to the old routing number after October 15, 2025? > > Please notify us via Slack if you are aware of any items scheduled to post to your account via the legacy routing number. Refer to the List of Accounts file for your new account details. > [accordion] Will outgoing wires, ACH, or check processing be affected? > > Outgoing wires, outgoing ACH transfers, and check processing will remain unaffected through March 2026. > [accordion] Will we need to redirect the account and routing numbers again? > > The account and routing numbers in the List of Accounts file will be your designated account and number going forward. We do not anticipate any additional redirects for the foreseeable future. > [accordion] Do we need to notify our counterparties about this change? > > If you are currently instructing your counterparties to send payments to an account number with the legacy routing number, you will need to notify them of the change. Please begin directing them to use your new account and routing number details listed in the List of Accounts file. > [accordion] Do we need to notify our end users about this change? > > No direct notification to your end users is required. Your existing account and routing number details will remain accessible, and we'll work with you on any program-specific communications during the transition. > [accordion] What’s different about the new platform? > > No changes will take effect immediately as the upgrade isn’t scheduled to complete until March 2026; however, we’re anticipating a significantly improved experience, including: > > * Increased uptime with minimal to no maintenance-related downtime > * A modernized online banking interface with enhanced controls and expanded functionality > * A streamlined account opening experience designed for speed and ease of use > [accordion] Will I be able to turn on Positive Pay on the new platform? > > No. Currently Positive Pay is not supported. You will be responsible for monitoring all payments and initiating a return when appropriate. If you are integrated with the API, you will receive notifications via webhooks for incoming payments. If you are currently not receiving webhooks, and would like to turn this on - please reach out and we can help with this. > [accordion] Will I still receive emails for incoming wires? > > No. If you are integrated with the API, you will receive notifications via webhooks for incoming payments. If you are currently not receiving webhooks, and would like to turn this on - please reach out and we can help with this. > [accordion] What work will be required between October 15, 2025 - February 28, 2026? > > We’re reviewing your program and will contact you with next steps when it’s time to move you to the new platform. > [accordion] Will there be changes to reporting? > > Yes, to the bank statements. Previously, each individual ACH transaction posted as its own line item. When you transition to your new account and routing number, this behavior will change. Instead of posting individually, incoming ACH will post as an aggregate amount per ACH settlement window just as you see with your BaaS programs. If you use the API, individual ACH transaction details will be supplied in your supplemental reports. **08/15/2025** ✨ New ## Enforcement of ACH & Wire Limits **Effective date: September 15th** We’re transitioning from soft to hard limits for ACH and Wire payments. Payments that exceed configured limits will be rejected immediately at submission - rather than being flagged for manual review. **What’s changing:** Previously, payments that exceeded per-transaction or aggregate limits were allowed to proceed and were routed to our team for manual review. This often caused processing delays and required follow-up with your team to confirm next steps. **Why this helps:** This update gives you faster, more actionable feedback and reduces uncertainty: * Faster feedback: You’ll know instantly if a payment exceeds your limits - no more waiting for a manual review. * Fewer delays: Immediate rejection lets you adjust and resubmit right away, keeping payment flows moving. * More control: Limit issues are surfaced at the point of submission, so you can troubleshoot and resolve them without relying on intervention from Lead’s support team. **Error behavior:** | **Submission Method** | **Format** | **Details** | | :- | :- | :- | | API | API response body | ACH or wire payments that exceed the outgoing per-transaction limit will return a synchronous error in the API response body: JSON `{ "title": "Validation Error", "code": "per_transaction_limit_exceeded", "detail": "Entry would exceed per transaction limit. Current limit value: [LIMITVALUE].", "status": "422" }` | | API | `ach.rejected` or `wire.rejected` webhooks | ACH or wire payments that exceed the outgoing daily or rolling 30 day aggregate limit will trigger an asynchronous webhook containing the rejection reason `aggregate_limit_exceeded`. Full rejection details are available in the rejection hash: JSON `"rejection": { "reason": "aggregate_limit_exceeded", "details": "Entry would exceed the aggregate limit. Current limit value [LIMITVALUE].", }` | | File upload | Full file rejection | If a submitted file contains entries that exceed ACH limits, the entire file will be rejected. An alert will be sent to your dedicated alerting Slack channel: Text `Error Code: "aggregate_limit_exceeded" Description: "Entry would exceed the aggregate limit. Current limit value: [LIMITVALUE]."` | **Next steps:** Review your current ACH and wire limits and ensure they are sufficient to support your payment daily and rolling 30 day payment volumes. Contact our Business Banking team if you need to make updates. Monitor your limits regularly to allow for proactive limit increase requests when necessary to avoid failed transactions and ensure uninterrupted payment activity. **07/14/2025** 🛠 Improvement ## Documentation Updates We've made a few updates and clarifications to our documentation: * [Balances](/products/balances-and-transactions/overview) * For deposit programs with interest, `interest_accrued_balance` and `interest_accrued_balance_in_usd` must be at least the minimum number of decimal places required by the currency. For example, if the `currency` is USD, value must be at least 2 decimals `11.500`. * [Transactions](/products/balances-and-transactions/overview) * When the `transaction.type` = `interest_accrued`, `amount` and `amount_in_usd` must be at least the minimum number of decimal places required by the currency. For example, if the `currency` is USD, value must be at least 2 decimals `11.500`. * Clarified definitions for some [transfer types](/products/balances-and-transactions/transaction-types) * no\_money\_movement * out\_of\_bank\_settlement * [Bank Reporting Overview](/file-reference/reports/overview) * Added clarification that daily balance and activity reports are comma delimited, while ACH cash recon reports are pipe delimited **07/03/2025** 🛠 Improvement ## Documentation Updates We've made a few clarifications to our documentation: * [Accepted Currencies](/file-reference/delivery/currencies) * Corrected MGA to have 2 decimals * Added the following currencies: XCG, KPW, UYW, ZWG, SYP, IRR, VES, STD, CUP, CUC, LYD, MRU, CNH **06/26/2025** ✨ New ## Upcoming Validations & Adoption Deadlines **We’ve made a one-time adjustment to the rollout timeline for upcoming account number and entity validations.** To give customers more implementation time, we’ve shifted our original enforcement dates slightly. This delay is not part of a broader trend - you should continue to expect that future deadlines for breaking changes will be firm. Your systems should be fully prepared to handle the new validations by the adoption deadlines listed below. After those dates, Lead will begin our own rollout, with at least 7 days’ notice before enforcement begins on our side. Each phase below outlines what’s changing, how to prepare, and what to expect when enforcement starts. > [accordion] Enforce Account Number Creation Rules > > **Adoption Deadline: July 17th, 2025** > > * **What’s changing:** > * New account numbers must be associated with the `account_holder` role. > * **How to prepare:** > * Use the Entity API to create all customer records. > * (Optional but recommended) Set `intended_roles: [“account_holder”]` when creating the entity. This ensures the entity can create Account Numbers. > * **What happens after:**\ > Lead will begin rejecting: > * Requests to link account numbers to entities without the `account_holder` role (returns a 422 Unprocessable Entity error). > [accordion] Deactivate Account Numbers Linked to Invalid Entities > > **Adoption Deadline: August 14th, 2025** > > * **What’s changing:** > * All *existing* account numbers must be linked to an entity that holds the `account_holder` role. > * **How to prepare:** > * If not already shared, Lead will provide a list of entities who don’t pass current data validations or whose records Lead is unable to retrieve from an Account Number > * Use the PATCH endpoint to update these entities. > * (Optional but recommended) Set `intended_roles: [“account_holder”]` when creating the entity. This ensures the entity can create Account Numbers. > * **What happens after:**\ > Lead will run a migration to deactivate account numbers that: > * Aren’t linked to an entity > * Are linked to entities not eligible for the `account_holder` role > [accordion] Incoming Wire Name Validation > > **Adoption Deadline: September 4th, 2025** > > * **What’s changing:**\ > We’ll validate that the creditor name on incoming wires matches the name of the entity linked to the receiving account number. > * **How to prepare:** > * Lead will share a list of incoming wires that would fail under the new validation. > * Review the list and notify end customers if needed. > * **What happens after:**\ > We’ll begin rejecting incoming wires if: > * The linked entity is missing or invalid > * The beneficiary name doesn't reasonably match the entity name **06/23/2025** 🛠 Improvement ## Examples Added to Accounts File Schema We've added an example and clarified the description of the expected contents of the `documents` field in the [Accounts File Schema](/file-reference/account/schema) | **Field** | **Description** | **Required** | **Data Type** | | :- | :- | :- | :- | | documents | An array of JSON hashes of customer-facing documents. The JSON hash should reference any dynamic document that has been uploaded to the Documents folder or the consented version of a static document approved by Lead compliance, and include the document name/type, its client\_document\_name or document\_id, its version, and its consent date. The required docs will be defined between the client and Lead bank during setup. | Required | Example- `[{"document_id": "client_document_123", "type": "xyz_firm_privacy_notice", "consented_at": "2025-02-12T15:38:34.101-06:00", "version": "20220202"}]` Note: JSON strings embedded in CSV fields must be enclosed in double quotes, with internal double quotes escaped by doubling them (""). **Original:**`[{"id":1,"name":"Alice"},{"id":2,"name":"Bob"}]`**CSV-escaped:**`"[\{""id"":1,""name"":""Alice""},{""id"":2,""name"":""Bob""}]"` For documents uploaded via SFTP, please input the full file name as document\_id. The suggested naming convention is: `__.` | \ **Changes** * Updated and clarified the `type` of [transactions accepted for Deposit and Credit](/products/balances-and-transactions/transaction-types) * Deposit: * Added `Reversed` as a supported `action` for the following `type`: `charge_off`, `charge_off_recovery` * Removed `Reversed` as a supported `action` for the type `disbursement` * Removed the following as a `type` of transaction: * `Cancelled` * `Fee` with `fee_type` of `atm`, `overdraft`, `periodic_maintenance`, `other` * Credit: * Added `Reversed` as a supported `action` for the following `type`: `charge_off`, `charge_off_recovery` **06/11/2025** 🛠 Improvement ## Documentation Updates We've made a few clarifications to our documentation to enable a more seamless onboarding experience for partners, specifically: * [Accepted Currencies](/file-reference/delivery/currencies): Added an Accepted Currencies to show which currencies and their corresponding number of decimals are accepted by Lead * [Balances File Schema](/file-reference/balances-and-transactions/balances-schema): Clarified enum options for `repayment_details` * [Transactions File Schema](/file-reference/balances-and-transactions/transactions-schema): Clarified requirements for `merchant_state` and `original_transaction_id` **06/04/2025** ✨ New ## New Payments Functionality We’re making important updates to our payment infrastructure based on your feedback. These changes are designed to improve predictability and reduce manual effort - especially around ACH, wires, and file-based processing. Some of the updates will require action on your end. Without these changes, certain payment workflows may fail or behave unexpectedly. We know updates like these take time and effort. Thank you in advance for adapting - we’re confident the improvements will result in faster feedback, easier troubleshooting, and a more reliable developer experience. This update includes the following key elements: 1. **Synchronous ACH API validation errors**\ Starting June 18, more validation failures will now return real time HTTP 422 error responses instead of asynchronous webhooks. 2. **File-Based ACH validations**\ Starting June 18, Nacha files containing validation failures will be rejected in full. 3. **Fixed cutoff times for ACH processing windows**\ Starting August 11, all ACH submission cutoffs will be enforced as hard deadlines (no best-effort processing). Additionally, the final same-day and next-day ACH submission cutoffs are moving earlier. 4. **ISO 20022 Fedwire migration**\ Fedwire is transitioning to ISO 20022 format. Partners must be ready for new message structures and can transition to Wires V1 between July 3rd and July 10th. July 10th onwards all partners must be on Wires V1. 5. **Previously announced: upcoming Q2 feature deadlines**\ Reminders for previously announced changes taking effect July 1st, including Entity requirements, Wire validation, and Internal Transfers V1. > [accordion] Synchronous ACH API validation errors > > **Effective date:** Jun 18, 2025 > > ACH origination and return submissions via API that fail certain semantic validations will now return real-time validation errors (HTTP 422) instead of triggering asynchronous error notifications via webhook. Some validations may still fall back to asynchronous handling for exceptions and trigger a webhook. The full list of validations run by Lead can be found [here](/api-integrations/ach/validations). > > **What’s changing:** You’ll now receive synchronous error responses on initial submission, enabling faster debugging and reduced turnaround time. > > **Next steps:** > > * Ensure your systems are prepared to handle synchronous responses. > * Update error handling logic as needed based on the validations list [here](/api-integrations/ach/validations). > [accordion] File-Based ACH validations > > **Effective date:** Jun 18, 2025 > > We are updating our Nacha file processing logic to strictly enforce entry-level validation rules. Starting June 18, any file containing one or more invalid ACH entries will be rejected in full. > > **What’s changing:** Each entry contained in a Nacha file will be validated, and if any entry fails validation, the entire file will be rejected — no entries will be processed. > > A Slack alert will be posted to your designated ‘alerts’ channel detailing the reason for the rejection. > > **Why this helps:** Catching issues at submission helps prevent downstream errors, unexpected return files, or delays in processing. This change reduces operational friction by surfacing problems before they reach the network. > > **Next steps:** > > * Review the list of possible validation failures [here](/api-integrations/ach/validations) and update your file generation process to avoid common errors. > * Ensure your team monitors your Slack channel and is prepared to correct and resubmit rejected files promptly. > [accordion] Extended ACH processing windows and fixed cutoff times > > **Effective date:** Aug 11, 2025 > > To better support our clients’ businesses, we are formally expanding support for all six FedACH windows for ACH submission—three same-day and six next-day windows. This provides greater flexibility in when you can submit payments and improves your ability to meet time-sensitive disbursement needs. > > Additionally, we are updating cutoff times for the final ACH processing windows to ensure consistent, predictable delivery to FedACH. These cutoff changes affect only the last windows for same-day and next-day ACH submissions. > > **What’s changing:** > > Lead will support submission into: > > * All three same-day ACH windows > * All six next-day ACH windows > > Updated cutoff times for final windows: > > * Same-day ACH cutoff: shifting from 3:15 PM CT to 2:00 PM CT > * Next-day ACH cutoff: shifting from 12:45 AM CT to 10:00 PM CT (prior day) > * Next-day returns cutoff: shifting from 12:45 AM CT to 10:00 PM CT (prior day) > > ### Same-day ACH > > | **Lead’s Cutoff Deadline** | **Corresponding Fed Window Deadline** | **Settlement Time (at Counterparty’s Bank)** | **Effective Date** | > | :- | :- | :- | :- | > | 09:00 AM CT | 09:30 AM CT | 12:00 PM CT (Same Business Day) | current day | > | 01:15 PM CT | 01:45 PM CT | 04:00 PM CT (Same Business Day) | current day | > | 02:00 PM CT | 03:45 PM CT | 05:00 PM CT (Same Business Day) | current day | > > ### Next-day ACH > > | **Lead’s Cutoff Deadline** | **Corresponding Fed Window Deadline** | **Settlement Time (at Counterparty’s Bank)** | **Effective Date** | > | :- | :- | :- | :- | > | 09:00 AM CT | 09:30 AM CT | 07:30 AM CT (Next Business Day) | next business day | > | 01:15 PM CT | 01:45 PM CT | 07:30 AM CT (Next Business Day) | next business day | > | 03:15 PM CT | 03:45 PM CT | 07:30 AM CT (Next Business Day) | next business day | > | 06:30 PM CT | 07:00 PM CT | 07:30 AM CT (Next Business Day) | next business day | > | 09:15 PM CT | 09:45 PM CT | 07:30 AM CT (Next Business Day) | next business day | > | 10:00 PM CT | 01:15 AM CT | 07:30 AM CT (Next Business Day) | next business day | > > Submissions after these Lead cutoff times will no longer be processed on a best-effort basis. Instead, they’ll be automatically queued for the next available window, ensuring consistent outcomes. > > **Why this helps:** > > * Access more FedACH processing windows, giving you additional flexibility to meet customer needs > * Eliminate uncertainty from “best-effort” processing - align your submission workflows to a clear, reliable schedule, which is easier to manage and automate > > **Next steps:** > > * Review your submission schedules to ensure alignment with the new cutoffs. > [accordion] ISO 20022 Fedwire migration > > **Effective date:** July 3, 2025 > > Fedwire is migrating to the ISO 20022 message format. This is a mandatory, industry-wide change, and all Lead partners using our Wire APIs must migrate to Wires V1 to remain compatible. As a follow-up to our previous announcement, we’re providing more details on what’s changing and outlining the required actions for our partners. > > **What’s changing:** Fedwire is retiring the FAIM format and adopting ISO 20022, which introduces structured fields for originator and beneficiary details, BICs, remittance info, and more. > > Lead’s current Wires V0 implementation is not compatible with ISO 20022 and will be deprecated. The Wires V1 sandbox will be available for testing starting on June 13, 2025. All partners must migrate from Wires V0 to Wires V1 by July 10, 2025. > > **Rollout plan:** > > | **Date** | **Release milestone** | **Required Action(s)** | > | :- | :- | :- | > | June 13, 2025 | Wires V1 Sandbox go-live | Begin testing against the Wires V1 Sandbox APIs and webhooks. | > | July 3, 2025 | Wires V1 Production APIs and webhooks go-live | Partners are now able to begin migrating from V0 to V1 APIs in production. Please reach out to Lead when you’d like to migrate. | > | July 10, 2025 | Deadline for V0 to V1 migration | Partners must complete the migration from V0 to V1 by this date. | > | July 11, 2025 | Wires V0 Production APIs and webhooks deprecated | No required action. | > > **Next steps:** > > * Review and test in the Wires V1 sandbox in accordance with the updated API documentation and sample payloads (coming soon). > * Migrate to Wires V1 in production between July 3rd and July 10th. This version includes updated request formats and response fields designed to support ISO 20022 structure. > * Validate any internal systems that process webhook data or depend on wire message structure. > [accordion] Previously Announced: upcoming Q2 feature deadlines > > | **Announcement** | **Summary** | **Effective Date** | > | - | :- | :- | > | Entity Association Requirement for Account Number Activation | Active Account Numbers must be linked to an Entity with the account\_holder role, or they will be deactivated. | July 1, 2025 | > | Validation of Beneficiary on Incoming Wires | The beneficiary name on incoming wires must match the name on the Entity that owns the Account Number to meet FinCrimes compliance. | July 1, 2025 | > | Internal Transfer v1 Release; Removal of v0 | V0 will be deprecated. Migrate to internal\_transfer V1 for improved async behavior. | July 1, 2025 | > | New Controls Available on Account Numbers | You will be able to set optional ACH permissions on account numbers, including flags for credits, debits, and allowed counterparties. | Early Q3 | **05/30/2025** 🛠 Improvement ## Documentation Improvements We've made a few clarifications to our documentation to enable a more seamless onboarding experience for partners, specifically: * [SFTP Connectivity](/file-reference/sftp-setup): * Clarified that SFTP folders are auto-created upon initial upload of a file to the desired path. * [File Delivery Overview](/file-reference/delivery/overview): * Clarified that CSV files should be formatted with a pipe delimiter, and not with a comma or semicolon delimiter. * Added recommendation that partners use an open source CSV parser to confirm that a CSV file is valid before submitting it to Lead for more streamlined processing. * Clarified that all file header values are case-sensitive, and partners should refer to specific file schemas to ensure they are formatted accordingly. * [Customer File Schema](/file-reference/customer/customer-schema): * Added in an example E.123-formatted phone number that will pass Lead's validation for easy reference. * [Applications File Schema](/file-integrations/application/schema): * Clarified the requirements for the credit bureau data-related fields (`credit_pulled_at`, `credit_score`, and `credit_report_source`). These fields are only required if your program's underwriting policy requires credit bureau data on all applications. This will be agreed upon with Lead's Legal team during your implementation process. * [Accounts File Schema](/file-reference/account/schema): * Clarified the requirements for the credit bureau data-related fields (`credit_pulled_at`, `credit_score`, and `credit_report_source`). These fields are only required if your program's underwriting policy requires credit bureau data on all accounts. This will be agreed upon with Lead's Legal team during your implementation process. * Added `other` as a valid enum for `status_reason` * [Transactions File Schema](/file-reference/balances-and-transactions/transactions-schema): * Clarified that `card_transaction_effective_at` must be excluded if the `transfer_type` is not card * Clarified that `card_network` must be excluded if the `transfer_type` is not card. Added `tabapay` as a valid enum * [Balances File Schema](/file-integrations/balances-and-transactions/balances-schema) * Clarified the data type requirements for `interest_rate` across deposit and credit products * [Cards File Schema](/file-reference/card/schema) * Clarified that the `activated_at` datetime must also be before the `expiry_date` if the `expiry_date` field is present * [Non Posted Transactions File Schema](/file-reference/balances-and-transactions/non-posted-transactions-schema) * Clarified that `amount` is Currency decimal field * Updated the hyperlink for `transfer_type` **05/23/2025** ✨ New ## Open API Spec Now Available Our Open API spec is now fully available: * [JSON Open API Spec](https://docs.lead.bank/openapi.json) * [API Reference](https://docs.lead.bank/api-reference) **05/22/2025** 🛠 Improvement ## Improvements to Transactions File Requirements We've clarified in our documentation the requirements for including transfer types (`transfer_type`) in the Transactions File, specifically: * Which transaction types require an associated transfer type to be submitted * For transaction types that require a transfer type, which transfer types are valid enums to be submitted * For transaction types that do not require a transfer type, which transfer types are valid enums to be optionally submitted Please refer to the following for more details: * [Transactions File Schema](/file-reference/balances-and-transactions/transactions-schema) * [Transaction Types](/products/balances-and-transactions/transaction-types) **04/03/2025** 🐛 Fix ## Updated Data Schema Examples In the Lead Data Schemas for [Applications](/file-integrations/application/schema) and [Accounts](/file-reference/account/schema), the `documents` property correctly had the description: "An array of JSON hash of customer-facing documents." However, in the `Data Type` column, the table included an erroneous outer nested JSON that does not match Lead's implementation. We've updated the examples in both data schemas to correctly reflect the expected object structure. **Expected** `[]` **Unexpected** `{"documents":[]}` This change was exclusively to the documentation and does not reflect any change in the system behavior. **04/01/2025** ✨ New ## Q2 2025 Product Announcements > [accordion] Action Recommended: Migrate to the New Entity API for Better Efficiency > > ### Summary > > Lead has historically only supported file-based methods for partners to submit entity records (i.e., data about your end-users) that are required for program oversight. The most common way that this was done was by submitting daily “customer files”. > > In December 2024, we released an [Entity API](/api-reference/endpoint/entity/create-an-entity) that is an improvement over file-based submission process with support for: > > * Real-time entity record creation, meaning downstream workflows (e.g., account number creation) that require the existence of an entity record are immediately enabled > * Error handling for issues such as formatting that can be surfaced for individual records instead of for large batches of records > * Robust role types, with an immediate response for whether submitted entity data meets the requirements for a given role > > As we expand our products and services, we highly recommend that partners using Lead API products utilize the Entity API on a go-forward basis. Lead will continue to support file-based submission for use cases where real-time validation of entity records is not required. > > ### What’s changing > > To provide you with the best experience and streamline onboarding to future product enhancements (e.g., real-time payments), we are focusing our development efforts for entity data submission on the Entity API. While we will continue to support file-based submissions, this channel will not be a focus area for further development. > > ### Who is impacted > > All partners not yet taking advantage of the Entity API are strongly recommended to take the following actions. > > * For creating new `entity` records: We recommend you begin using the Entity API. > * For existing `entity` records: > * Depending on the customer file version and type of data you have been uploading, many of your existing records may already be accessible through the Entity API. Please use the [Retrieve an Entity by Entity ID](/api-reference/endpoint/entity/retrieve-an-entity-by-entity-id) or [Retrieve an Entity by Client Customer ID](/api-reference/endpoint/entity/retrieve-an-entity-by-client-customer-id) endpoints to check. > * If your records are not yet available via the API, you will need to resubmit them using the Entity API. To simplify this process, please include the original `client_customer_id` in your API requests so that we can help track which `entity` records have been successfully resubmitted. > * Once resubmitted, use the [Retrieve an Entity by Entity ID](/api-reference/endpoint/entity/retrieve-an-entity-by-entity-id) endpoint to confirm that the `role_details` (e.g., account holder, authorized signer) are correct. If necessary, use the [Update an Entity](/api-reference/endpoint/entity/update-an-entity) endpoint to resubmit data as needed. > * Your Implementation Manager can provide a list of records that require resubmission. > > ### When this will be released > > The Entity API is available now. We advise reviewing our documentation and working with your Implementation Manager to plan your migration. Please note that migrating to the API will be required to utilize future features. > [accordion] New ACH Controls Available on Account Numbers > > ### Summary > > We are enhancing the utility of our `account_number` object to give you greater control over how money moves in and out of your accounts. With this update, you can programmatically set permissions that automatically allow or reject different types of incoming and outgoing transfers. This ensures that only authorized transactions occur, reducing operational risk and providing a more seamless way to manage funds. Whether you want to prevent unauthorized deposits, restrict outgoing payments, or fine-tune which counterparties can interact with your accounts, these new controls put you in charge of your money flows. > > ### What's changing > > *Note that Lead considers the addition of optional fields to the*`account number`*object a backwards-compatible change.* > > Once released, you will be able to create `account_number` objects with the following new controls. If these controls are set to `false`, Lead will automatically return transfers. For outgoing, you will receive a failure response via API. > > **For Incoming and Outgoing ACH:** > > * Allow ACH Credits – `true`/`false` > * Allow ACH Debits – `true`/`false` > * Allowed ACH counterparties > > Each of these controls will have default values that mirror existing `account_number` functionality. > > **ACH Defaults:** > > * Allow incoming ACH (both credit and debit) – `true` > * Allow outgoing ACH (both credit and debit) – `false` (unless your current program allows this behavior, in which case, we will map the controls to match your existing configuration) > * Allowed ACH counterparties – permissive of all counterparties > > ### Who is impacted > > Any partner that is utilizing the [Account Number API](/api-reference/endpoint/account-number/create-an-account-number) will have access to this enhanced functionality. > > ### When this will be released > > Development is currently in progress for these features with a target release of end of Q2 2025. We will provide additional clarity on release date and a finalized `account_number` object specification and updated documentation at least a month before the release. > [accordion] Entity Association Requirement for Account Number Activation (Effective July 1, 2025) > > ### Summary > > To enhance compliance and improve operational efficiency, we are implementing a new requirement for `account number` activation. Effective **July 1, 2025**, an active account number must have a properly associated `entity` object with an `account_holder` role set. > > ### What's changing > > Starting **July 1, 2025 (Tuesday)**, account numbers that do not meet the entity association requirements will be automatically deactivated. This will prevent any payments (ACH, wires, etc.) from being processed for these accounts. > > `Account number` objects with a status of: > > * `Unassigned` will not be impacted. > * `Active` and associated entities that meet account\_holder role requirements will remain active. > * `Active` but do not have associated entities that meet account\_holder role requirements will be moved to an inactive status. > * `Inactive` will not be impacted. > * `Canceled` will not be impacted. > > ### Who is impacted > > This change affects partners who use `account number` objects for ACH and wire payments. > > If you are already using the Entity API to create `entities` and the [Account Number API](/api-reference/endpoint/account-number/create-an-account-number) to associate `entities` with `account numbers`, your `account numbers` are likely already compliant. However, if you are creating `entities` using file submissions, you will need to verify compliance. > > To verify compliance, use the [Retrieve an Entity by Entity ID](/api-reference/endpoint/entity/retrieve-an-entity-by-entity-id) or [Retrieve an Entity by Client Customer ID](/api-reference/endpoint/entity/retrieve-an-entity-by-client-customer-id) endpoints and check the `role_details` for the `account_holder` role. If your `entity` objects do not have the `account_holder` role enabled, refer to the [data requirements](/products/entity/roles) for additional data needed. Use the [Update an Entity](/api-reference/endpoint/entity/update-an-entity) endpoint to resubmit any required data. > > ### When this will be released > > * Monitoring: Throughout **June**, we will monitor account number compliance and reach out to partners with a significant number of non-compliant accounts. Early verification and remediation are strongly encouraged to avoid disruptions. > * Production: Account number deactivation will begin on **July 1, 2025 (Tuesday)**. > > ### Learn more > > * To learn more about whether there is an `entity_id` or `client_customer_id` associated with an `account number`, use the [Retrieve an Account Number](/api-reference/endpoint/account-number/retrieve-an-account-number) endpoint. > * To learn more about whether an `entity` has the `account_holder` role enabled, use the [Retrieve an Entity by Entity ID](/api-reference/endpoint/entity/retrieve-an-entity-by-entity-id) or [Retrieve an Entity by Client Customer ID](/api-reference/endpoint/entity/retrieve-an-entity-by-client-customer-id) endpoints. > * To assign an `account number` to an `entity_id` or `client_customer_id`, use the [Assign an Account Number](/api-reference/endpoint/account-number/assign-an-account-number) endpoint. > * To update an `entity` and modify the roles it has access to, use the [Update an Entity](/api-reference/endpoint/entity/update-an-entity) endpoint. > [accordion] Validation of Beneficiary on Incoming Wires (Effective July 1, 2025) > > ### Summary > > In order to ensure compliance with FinCrimes and risk requirements, the beneficiary name stated on an incoming wire transfer (i.e., the individual or business that the wire sender says the funds are intended for) must match Lead’s records of the entity or customer associated with the account number to which the wire is sent. This is to ensure that inbound wires are only posted to the account of an intended recipient, and flagged for review in cases where the intended recipient differs from the account number’s associated entity. Typically, wire transfers with a name mismatch will be returned. > > ### What's changing > > On **July 1, 2025 (Tuesday)**, Lead will begin enforcement of beneficiary names matching with the name of the individual or business associated with the account number. > > As an example, let’s say a counterparty financial institution sends an incoming wire to Lead account number `123412341234` and the beneficiary name on the wire is `Jane Smith`. Lead will do a lookup of the `entity_id` or `client_customer_id` associated with that account number. > > * If the entity type is an individual, we will look for approximate matches to the first name and last name on file. > * If the entity type is a business or sole proprietorship, we will look for approximate matches to the business name, the "doing business as" name of the entity, beneficial owner(s) name, and/or the sole proprietor's name > > If the names are mismatched, Lead will return the wire with a `rejection.reason` of `beneficiary_name_mismatch`, and you will receive a webhook notifying you of the `wire.rejected` event. In certain cases where the names are close, the Lead team may reach out to you for more information. > > ### Who is impacted > > All partners using `account number` objects to receive wires will be impacted by this change, and should ensure that customer data (specifically names) are fully up to date and complete. We strongly recommend the use of the [Entity API](/api-reference/endpoint/entity/create-an-entity) for this purpose. > > ### When this will be released > > * Monitoring: We will begin monitoring the impact of this enforcement in shadow mode in **June** to evaluate impact to rejection rates. We will reach out to individual partners with high match failures to partner on how to improve on match rates. > * Production: We will begin enforcing this validation on **July 1, 2025 (Tuesday)**. > > ### Learn more > > * To learn more about which `entity_id` or `client_customer_id` is associated with an account number (and therefore which name we will check against), use the [Retrieve an Account Number](/api-reference/endpoint/account-number/retrieve-an-account-number) endpoint. > * *If you are an Entity API user:* To learn more about the name-related data associated with an `entity_id`, use the [Retrieve an Entity by Entity ID](/api-reference/endpoint/entity/retrieve-an-entity-by-entity-id) endpoint. > * *If you are a partner uploading Customer Files:* To learn more about the name-related data associated with a `client_customer_id`, use the [Retrieve an Entity by Client Customer ID](/api-reference/endpoint/entity/retrieve-an-entity-by-client-customer-id) endpoint. > [accordion] ISO 20022 Wire v1 Preparation > > ### Summary > > On the **July 14, 2025 (Monday)** business day, Fedwire is planning on executing a one-time migration in message formats. Its current Fedwire Application Interface Manual (FAIM) spec will be deprecated in favor of the ISO 20022 spec (more information on its website [here](https://www.frbservices.org/resources/financial-services/wires/iso-20022-implementation-center)). This migration date was previously slated for March 10, 2025, but was pushed back to allow Fedwire participants more time to prepare. There is work required for both Lead and our partners to be prepared for this change. > > We recognize that this will require considerable bandwidth from your teams between early June and mid-July, and appreciate your understanding as we work together to navigate this one-time transition. In addition to the below, we will follow up with additional details closer to date. > > ### What's changing > > In preparation for this message format migration, we are planning to up-version the Wire API from v0 to v1. The core workflows for the wire product are not changing (i.e., retrieve, create, update, return, and cancel operations will remain the same), but we will be up-versioning the `wire` object to enable a seamless transition. Existing `wire` objects will continue to be available via the v1 API endpoints (retrieve, return, and cancel), and we will publish clear documentation to support you in mapping any data fields where changes have been made. > > ### Who is impacted > > All live partners currently sending or receiving wires in production, and currently implementing partners that plan to use Lead to send or receive wires. > > ### When this will be released > > * **Early June**: Lead will release v1 endpoints in Sandbox, allowing you to simulate wire workflows end-to-end utilizing the new v1 `wire` object > * By **June 27, 2025 (Friday)**: Fedwire will make a go or no-go decision on whether the ISO 20022 migration will proceed on July 14 > * If it is a “no-go” decision: Lead will continue to use the v0 `wire` object in production until further notice. We may decide to release v1 on an opt-in basis depending on when Fedwire’s plans to execute on the migration. > * If it is a “go” decision, by **June 30, 2025 (Monday)**: Lead will release v1 endpoints in Production, allowing you to start working with the v1 `wire` object in production on an opt-in basis. We will begin sending v1 webhooks after the first time you call a v1 endpoint. The v0 API endpoints will no longer be available after the July 14 Fedwire migration. > > ### Learn more > > We are working on a specific guide to support our partners’ migration efforts – what you need to know about ISO, key dates, and v1 wire object documentation. These will be shared by early June. > [accordion] Internal Transfer v1 Release; Removal of v0 (Effective July 1, 2025) > > ### Summary > > We have received feedback from Lead Partners that the current behavior of the `internal_transfer` functionality is confusing. Transfers can be processed synchronously or asynchronously depending on different factors that are not easily predictable. > > To address this, we have released a new v1 version of our Internal Transfers API to ensure that the behavior is fully asynchronous and predictable. We are requesting that all partners using the Internal Transfers API migrate to v1 before **July 1, 2025 (Tuesday)**. > > ### What's changing > > The new v1 version introduces two key enhancements over the existing functionality: > > * **Fully Asynchronous Processing** > * In v1, all internal transfer requests will be processed asynchronously, ensuring a consistent and predictable response pattern for our Partners. > * **Detailed Rejection Information** > * If a transfer is rejected, the response will include a `rejection` hash with details on the reason for rejection, allowing for easier troubleshooting and resubmission. > * For example, if an `internal_transfer` is attempted with an amount greater than the available balance, the rejection response will indicate `non_sufficient_funds` and provide the available balance at the time of the request. > > When you submit a request to create an Internal Transfer, you will receive a 200 response and the status of the transfer will be set to `processing`. As we process the transfer, we will update you on the status change events via webhooks. > > Note that events and webhooks are changing between v0 (`processing`, `succeeded`, and `failed`) and /v1 (`processing`, `posted`, and `rejected`). > > Please see below to view the different webhooks you should expect between v0 and v1: > > | **Version** | **Event** | **Description** | **Webhook** | > | :- | :- | :- | :- | > | v0 | internal\_transfer.processing | The Internal Transfer is being executed. | N | > | v0 | internal\_transfer.succeeded | The Internal Transfer has succeeded. | Y | > | v0 | internal\_transfer.failed | The Internal Transfer has failed. | Y | > | v1 | internal\_transfer.processing | The Internal Transfer is being executed. | N | > | v1 | internal\_transfer.posted | The Internal Transfer was completed and money has successfully moved from the `sender_account_number_id` to the `receiver_account_number_id`. | Y | > | v1 | internal\_transfer.rejected | The Internal Transfer was not completed and will not be retried. Please see `rejection.reason` and `rejection.details` for more information. | Y | > > Most of the time, these requests are completed successfully within seconds, but there are some instances where additional processing is required. If an issue is encountered in processing the request, Lead will continue to retry until we inform you of a terminal status (`posted` or `rejected`). > > ### Who is impacted > > This change impacts all partners using the Internal Transfers API. If you are currently using v0, you will need to migrate to v1 before the deprecation deadline and will begin receiving webhooks for v1 once you call the endpoints. > > ### When this will be released > > Beginning **July 1, 2025 (Tuesday)**, calls to the v0 Internal Transfers API endpoints will be rejected. > > The v1 Internal Transfers API is now available for adoption. You can review the v1 Internal Transfer API endpoints below: > > * [Create an asynchronous Internal Transfer](/api-reference/endpoint/internal-transfer/create-an-internal-transfer-v1) > * [List all Internal Transfers](/api-reference/endpoint/internal-transfer/list-all-internal-transfers-v1) > * [Retrieve an Internal Transfer](/api-reference/endpoint/internal-transfer/retrieve-an-internal-transfer-v1) **02/24/2025** 🛠 Improvement ## Updates to File Schemas Lead released a **Draft Data Schema** on February 9, 2025. This Data Schema is now **Stable**. The Changelog below reflects all changes made between the **Draft** publication and the current **Stable** Data Schema. * Applications * removal of `available_credit_limit` * removal of `interest_rate` and `over_draft_limit` * Accounts * removal of `status_updated_at` * removal of `interest_rate` and `over_draft_limit` * removal of `is_exception_approval` and `exception_reason` * change `scra_ended_at` validation to be optional and may not be present if `is_scra` is false * change `decision_reason` to `status_reason` * change `client_application_id` to `application_id` * change `user_closed` to `entity_closed` under `status_reason` * addition of `paid_off`, `charged_off` and `canceled` under `status_reason` * update of `account_holder` min size of 1 * enhanced validation where `authorized users` files are required if `authorized_user` is greater than max size 10 * enhanced validation where `available_credit` = `credit_limit` - sum of `balances` * Cards * update to `expiry_date` format to `YYYY-MM-DD` from `datetime` * update to `entity_id` accepting either `client_customer_id` or `entity_id` * change `client_account_id` to `account_id` * change `client_customer_id` to `entity_id` * enhanced validation where `activated_at` must be prior to `expires_at` * removal of `updated_at` * Authorized Users * update to `entity_id` accepting either `client_customer_id` or `entity_id` * change `client_customer_id` to `entity_id` * Collaterals * change `client_account_id` to `account_id` * change `client_application_id` to `application_id` * change `client_balance_id` to `balance_id` * Balances * removal of `status_updated_at` * removal of `is_revolving` * removal of `non_finance_charge_amount` * removal of `is_autopay` * addition of `paid_off`, `charged_off` and `canceled` under `status_reason` * addition of `dispute_balance` and `charge_off_balance` as required fields for deposit balance. * change `client_settlement_bank_id` to `client_settlement_bank_account_id` * change `client_account_id` to `account_id` * change `user_closed` to `entity_closed` under `status_reason` * enhancement of `required` validations (e.g. `expected_finance_charge_amount` and `repayment_details` are required if `expected_maturity_date` is present) * enhancement of examples on Balance Reconciliation and Examples * `amount` will affect all of `balance`, `interest_accrued_amount`,`dispute_balance`,`charge_off_balance` * `rewards_amount` will affect `rewards_balance` * `past_due_balance` does not reconcile against amount but just tracking credit balance that are past due * Transactions * removal of `client_funding_ids` * addition of `interest_amount` for deposit programs. * updated `type` across `type`, `fee_type`, `action`, `transfer_type`. * updated `rewards_amount` and `rewards_unit` to be applicable to non-card programs * change `client_settlement_bank_id` to `client_settlement_bank_account_id` * change `client_balance_id` to `balance_id` * change `client_card_id` to `card_id` * enhancement of `required` validations (e.g. (i) for card transactions related fields, required if `card_id` is provided, (ii) for credit balances, required if balance\_id type = credit) * Sales Request * change `client_balance_id` to `balance_id` **10/29/2024** 🛠 Improvement ## Upcoming API Enhancements 1. **ACH** - we are enhancing how we communicate details about rejected ACHs. Beginning on 11/12/2024, Lead will include a new object named *rejection* in our ACH object. This field will contain a *reason* and corresponding *details*. This will allow clients to understand why an ACH was rejected without having to contact Lead. More details are below. 2. **Internal Transfers** - we are developing a new version of our Internal Transfers API to make the behavior asynchronous. You will no longer have to manage retries on your own system, and we will also provide additional details about rejections should they happen. We will send an additional communication once we are closer to a release date. ### **ACH Rejections** ***rejection object*** | **Field Name** | **Type** | **Description** | | :- | :- | :- | | reason | *enum* | Provides the reason code if this ACH is in rejected status. | | details | *string* | A short, human-readable string with more details about why the ACH was rejected. | ### Mapping | account\_number\_not\_active | Account number \[ACCOUNTNUMBER] has non-active status: \[STATUS]. | | :- | :- | | aggregate\_limit\_exceeded | Entry would exceed the aggregate limit. Current limit value \[LIMITVALUE]. | | beneficiary\_account\_number\_unrecognized | Account number \[ACCOUNTNUMBER] not recognized. | | client\_customer\_not\_present | Account number \[ACCOUNTNUMBER] does not have a client customer ID or entity ID. | | client\_request | Please contact Lead for further details. | | disallowed\_counterparty | Counterparty is not allowed. | | disallowed\_sec\_code | SEC code \[SECCODE] is not permitted. | | duplicate\_entry | A duplicate entry was found \[ACHID]. | | entry\_link\_failed | Entry is a return or correction, but the associated parent entry could not be found. | | invalid\_format | Invalid format. Please contact Lead for details. | | non\_sufficient\_funds | Insufficient funds. Balance result: \[BALANCERESULT]. | | ofac\_rejection | Please contact Lead for further details. | | per\_transaction\_limit\_exceeded | Entry would exceed per transaction limit. Current limit value \[LIMITVALUE]. | | previously\_corrected | A previous ACH to the same counterparty was corrected (correction id = \[ACHID]). | | processor\_discretionary\_decision | Please contact Lead for further details. | | related\_prenote\_exception | ACH entry cannot be created within 3 banking days of a prenote's settlement date. (prenote id = \[ACHID]). | | related\_prenote\_exception | Previous prenote to this counterparty (id = \[ACHID]) was not accepted. | | return\_untimely | Return is not within the proper return timeframe. | | reversal\_rejection | Reversal rejected upon review. | | unexpected\_change\_code | Unexpected change code: \[CHANGECODE]. | | unexpected\_return\_code | Unexpected return code: \[RETURNCODE]. | | unexpected\_routing\_number | Invalid routing number provided. | **12/16/2023** 🛠 Improvement ## API Changes * We now enforce the NACHA same-day limit of \$1,000,000 USD. For transactions above \$1,000,000 USD you will need to set the `delivery_type` to `next_business_day`. * We have removed the `account{}` hash from the ACH object. It's been replaced by two new fields, `account_id`, and `account_number_id`. * The maximum length of the `idempotency-key` header across the API has been set at 255 characters. * We have renamed `individual_identification` on the ACH object to `individual_id`. This field is optional and, if set, contains any relevant ID number to allow the ACH counterparty to verify the sender. * We have renamed `related_information` to `additional_information`. This field is optional and, if set, will contain any additional information provided by the counterparty. *Note: For outgoing ACHes, the counterparties bank is not required to share this information with the ACH recipient.* # Account Files: Reporting Accounts via SFTP Source: https://docs.lead.bank/file-reference/account/overview Overview of account files. > [!WARNING] > > **Legacy schema — superseded by the Accounts API.** New programs integrate via the [Accounts API](/products/accounts/overview). This schema remains the supported path for file-integrated programs that have not yet migrated. > [!TIP] > > **An account must be created for all approved applications.** > > Deposit details are only relevant for deposit products and credit details are only relevant for credit products Accounts files are used for daily updates on accounts. Accounts contain non-balance information for Depository and Credit programs. Lead considers Accounts a container around Balances, Transactions, Cards, and Collateral. If your program exclusively provides users with a single financial product, such as a Line of Credit, your Account objects should map 1:1 with `Balance` objects created through the [Balance file](/file-reference/balances-and-transactions/balances-schema). For programs offering multiple financial products, your `Account` object may have a 1:many relationship with [Balances](/file-reference/balances-and-transactions/balances-schema). For example, if you offer the same consumer a Depository Account and a Line of Credit. All new accounts, as well as updates to existing accounts, are received through this file. # Account File Schema Source: https://docs.lead.bank/file-reference/account/schema Field-level reference for the Account file, covering identifiers, account holders, authorized parties, deposit details, credit details, and documents. > [!WARNING] > > **Legacy schema — superseded by the Accounts API.** New programs integrate via the [Accounts API](/products/accounts/overview). This schema remains the supported path for file-integrated programs that have not yet migrated. > [!TIP] > > **An account must be created for all approved applications.**\ > Deposit details are only relevant for deposit products and credit details are only relevant for credit products. > [!TIP] > > For all optional fields where you do not plan to pass through data, please include the header and an empty value. ## IDs and details | **Field** | **Description** | **Required** | **Data Type** | | - | - | - | - | | client\_account\_id | Unique ID of the account. Cannot start with `account_`, `subledgered_account_`, `partner_ledgered_account_`, or `user_account_` (reserved for Lead-generated account IDs). | Required | string | | application\_id | Unique ID of the application in your system. | Required if a [Credit Balance](/products/balances-and-transactions/balance-reconciliation) will be linked to the account. Not required for deposit products. | string | | account\_holder\_type | Type of account holder. | Required | enum: `consumer` `commercial` | | account\_holders | IDs of any account holders and co-holders. | Required with a `min_size` of 1 | An array of account holder IDs. **Example** "entity\_123", "entity\_456" Can be either `entity_id` or `client_customer_id`. | | authorized\_signers | A list of authorized signers. These are persons who can access, control, and change products and services on the account. | Required if `account_holder_type` = `commercial` and min size >=1 for commercial | An array of authorized signer IDs. **Example** "entity\_123", "entity\_456" Can be either `entity_id` or `client_customer_id`. | | authorized\_users1 | A list of authorized users. These are persons who do not own the account but have restricted, authorized use on the account. Optionally, the Authorized Users file may be used instead if max items > 10. | Optional. May not be used if your program delivers `authorized_users` in the [Authorized Users file](/file-reference/authorized-users/schema). | An array of authorized user IDs. **Example** "entity\_123", "entity\_456" Can be either `entity_id` or `client_customer_id`. | | currency | [Account currency](/file-reference/delivery/currencies). This signals to Lead which currency you are using to report available\_credit and credit\_limit in the Accounts file. This may be different `currency` reported in Balance Daily files if your end-users hold Balances in multiple currencies. 3 letter code, e.g. USD | Required | [ISO4217](https://www.iso.org/iso-4217-currency-codes.html) | | client\_product\_name | Name of the product offered by the partner. | Required | string | | is\_secured | Indicate if the product is a secured credit or secured deposit product. | Required | boolean | | capabilities | Optional per-account product capabilities. When omitted, the account receives your program's configured default capability, so a single file can mix credit and deposit accounts — untagged rows receive the default, and you tag other rows with the capability they need. Each declared value must be within your program's allowed capabilities, and capabilities are append-only across updates — an update row must re-declare every capability the account already has (see [Validations](/file-reference/account/validations)). See [Account Capabilities](/products/accounts/overview#key-concepts) for what each value means. | Optional | array of enum: `deposit` `credit_with_underwriting` `credit_without_underwriting` Encoded as a JSON array inside a single CSV cell, with internal double quotes escaped by doubling them (""). **Examples** "\[""credit\_with\_underwriting""]" "\[""deposit"",""credit\_with\_underwriting""]" | 1. If your program will have large volumes of authorized users per account, speak to your Technical Account Manager to utilize the Standalone Authorized Users file instead of this parameter. Once this configuration is set, the `authorized_users`parameter will no longer be supported on the Accounts file. ## Status and timing | **Field** | **Description** | **Required** | **Data Type** | | :- | :- | :- | :- | | created\_at | Datetime account initiated. | Required | datetime [ISO8601](https://www.iso.org/iso-8601-date-and-time-format.html) | | status | `active`: Account is active `inactive`: Account with no activity `closed`: Account is closed | Required | enum: `active` `inactive` `closed` | | status\_reason | The reason for the decision on the status. | Required | enum: `fraudulent` `client_closed` `user_closed` `entity_closed` `frozen` `dormant` `active` `paid_off` `charged_off` `other` Note `user_closed` will eventually be deprecated in favor of `entity_closed` | ## Adverse action notice and exception approval | **Field** | **Description** | **Required** | **Data Type** | | :- | :- | :- | :- | | aan\_delivered\_at | The datetime the adverse action notice (AAN) was delivered. | Required if `status_reason` = `client_closed` | datetime [ISO8601](https://www.iso.org/iso-8601-date-and-time-format.html) | | aan\_reason | Reason an AAN was sent to the customer. | Required if `status_reason` = `client_closed` | string | | aan\_delivery\_method | AAN delivery method. | Required if `status_reason` = `client_closed` | enum: `email` `text` `other` | ## Compliance | **Field** | **Description** | **Required** | **Data Type** | | :- | :- | :- | :- | | documents | An array of JSON hashes of customer-facing documents. The JSON hash should reference any dynamic document that has been uploaded to the Documents folder or the version of a static document approved by Lead compliance, and include the document name/type, its client\_document\_name or document\_id, its version, and its consent date. The required docs will be defined between the partner and Lead during setup. | Required | **Example** "document\_id": "client\_document\_123", "type": "esign\_agreement", "consented\_at": "2025-12-31T15:38:34.101-06:00", "version": "20220202" Note: JSON strings embedded in CSV fields must be enclosed in double quotes, with internal double quotes escaped by doubling them (""). For documents uploaded via SFTP, please input the full file name as document\_id. The suggested naming convention is: \`\\_\_\*\*\.\\` | ## Credit Details | **Field** | **Description** | **Required** | **Data Type** | | :- | :- | :- | :- | | is\_scra | Does the Servicemembers Civil Relief Act (SCRA) apply to this account. | Required if a [Credit Balance](/file-reference/balances-and-transactions/balances-schema) will be linked to this account. AND `status` != `closed` | boolean | | scra\_started\_at | The datetime when SCRA starts. | Required if `is_scra` = `true` | date `YYYY-MM-DD` | | scra\_ended\_at | The datetime when SCRA ends. | Optional. Expected if `is_scra` = `true` and the SCRA end date is known. Disallowed if `is_scra` is false | date `YYYY-MM-DD` | | is\_mla | `true` if the customer is subject to the Military Lending Act (MLA); `false` otherwise. | Required if a [Credit Balance](/file-reference/balances-and-transactions/balances-schema) will be linked to the account and `status` != `closed` | boolean | | underwriting\_grade | The grade or score assigned to the customer based on underwriting. | Required if a [Credit Balance ](/file-reference/balances-and-transactions/balances-schema) will be linked to the account and `status` != `closed` | string | | available\_credit | Available credit limit on the customer's account. Lead validates that this value equals Credit Limit minus the sum of the `balance` field for all [Balances](/file-reference/balances-and-transactions/balances-schema) linked to this account | Required if a [Credit Balance ](/file-reference/balances-and-transactions/balances-schema) will be linked to the account and `status` != `closed` | number [currency decimal](/file-reference/delivery/currencies) | | credit\_limit | The maximum amount the customer can draw. This may be different from the max credit limit the customer has been approved for. | Required if a [Credit Balance ](/file-reference/balances-and-transactions/balances-schema) will be linked to the account and `status` != `closed` | number [currency decimal](/file-reference/delivery/currencies) | | max\_credit\_limit | The maximum credit limit the customer has been approved for based on original underwriting and the product. | Required if a [Credit Balance ](/file-reference/balances-and-transactions/balances-schema) will be linked to the account and `status` != `closed` | number [currency decimal](/file-reference/delivery/currencies) | ## Credit Bureau Data | **Field** | **Description** | **Required** | **Data Type** | | :- | :- | :- | :- | | credit\_pulled\_at | The date the credit report is pulled. | Required if your program's underwriting policy requires credit bureau data on all accounts. This will be agreed upon with Lead's Legal team during implementation Required if any of `credit_score`, `credit_report_non_score_value`, or `credit_report_source` are present | datetime [ISO8601](https://www.iso.org/iso-8601-date-and-time-format.html) | | credit\_score | Credit score given by the credit bureau. Cannot be above 850. Mutually exclusive with `credit_report_non_score_value`. | Required if your program's underwriting policy requires credit bureau data on all accounts. This will be agreed upon with Lead's Legal team during implementation Required if credit bureau data is present and `credit_report_non_score_value` is not provided | number | | credit\_report\_non\_score\_value | Indicates the state of a credit file when a numeric score is not available. Mutually exclusive with `credit_score`. | Required if credit bureau data is present and `credit_score` is not provided | enum: `unestablished` `frozen` | | credit\_report\_source | The name of the credit bureau. | Required if your program's underwriting policy requires credit bureau data on all accounts. This will be agreed upon with Lead's Legal team during implementation Required if any of `credit_pulled_at`, `credit_score`, or `credit_report_non_score_value` are present | enum: `equifax` `experian` `transunion` | ## Other | **Field** | **Description** | **Required** | **Data Type** | | :- | :- | :- | :- | | generated\_at | The day this file is generated. This should always be the date the file is sent to Lead Bank. | Required | datetime [ISO8601](https://www.iso.org/iso-8601-date-and-time-format.html) | | effective\_at | The timestamp of when the related object(s) were polled to collect the information for this record. | Required | datetime [ISO8601](https://www.iso.org/iso-8601-date-and-time-format.html) | # Account File Statuses Source: https://docs.lead.bank/file-reference/account/statuses The statuses for account files. > [!WARNING] > > **Legacy schema — superseded by the Accounts API.** New programs integrate via the [Accounts API](/products/accounts/overview). This schema remains the supported path for file-integrated programs that have not yet migrated. ## Overview Accounts contain a **Status** and **Status Reason**, which pair together to define its state. ## Statuses | **Status** | **Description** | **Reason** | | - | - | - | | `active` | Indicates that the account is fully functional and operates as expected. | `active` | | `inactive` | Indicates that the partner has taken action to restrict activity on the account. Lead does not run additional validations on inactive accounts during daily reporting. However, partners are expected to take action on inactive accounts according to their policies. | `dormant` `frozen` `other` | | `closed` | Represents a terminal state for the account, meaning it is no longer active. A closed account cannot be re-opened and Lead's system will reject any additional changes or activity reported once it is reported in a `closed` status. If there is a chance that activity may still occur on the Account, use the `inactive` status until it is confirmed that no further activity will occur. | `entity_closed` `client_closed` `paid_off` `charged_off` `canceled` | # Account File Validations Source: https://docs.lead.bank/file-reference/account/validations Validating account files. > [!WARNING] > > **Legacy schema — superseded by the Accounts API.** New programs integrate via the [Accounts API](/products/accounts/overview). This schema remains the supported path for file-integrated programs that have not yet migrated. Beyond the standard required and optional field checks and data type validations, Lead performs additional validations. The list below is non-exhaustive — we aim to be thoughtful and robust in validations that ensure high data quality to enable us to provide effective oversight. ## Enforced Today | Validation | Description | | - | - | | Missing Status Reason | `status_reason` must be populated and consistent with `status`. Closed accounts must use a closed reason (`entity_closed`, `client_closed`, `paid_off`, `charged_off`, `canceled`). | | Missing Adverse Action Notice | Adverse action notice fields (`aan_delivered_at`, `aan_reason`, `aan_delivery_method`) are required if `status_reason = client_closed`. | | Missing Credit Score Detail | When you provide credit bureau data, include `credit_pulled_at`, `credit_report_source`, and exactly one of `credit_score` or `credit_report_non_score_value`. Provide all applicable fields or none. | | Invalid Entity Reference on Closed Account | References to account holders, authorized signers, and authorized users by `client_customer_id` or `entity_id` must refer to entities that have already been submitted to Lead if the account is in a `closed` state. | | May Not Change Closed Account | Updates may not be made to accounts in a `closed` state. A closed account cannot be re-opened. | | Entity Role Mismatch for Account | Each entity referenced on the account must meet the role requirements for `account_holder`, `authorized_signer`, or `authorized_user` as appropriate. | | Previous Account Has effective\_at >= current Account effective\_at | On account update, `effective_at` must be greater than the previous instance of this record. | | Capability Not Allowed | Each `capabilities` value declared on an account must be within your program's allowed capabilities. | | Capabilities Are Append-Only | An account's `capabilities` cannot be removed once set. An update row must re-declare every capability the account already carries; declaring only a newly added capability and dropping an existing one is rejected. | ## Future Enforcements Lead expects partners to comply with the validations below; however we do not currently enforce them upon daily processing. We will provide you with 60 days notice before enforcing the following validations. | Validation | Description | | - | - | | Invalid Namespace | `client_account_id` cannot start with `account_`, `subledgered_account_`, `partner_ledgered_account_`, or `user_account_` (reserved for Lead-generated account IDs). | | Invalid Entities on Account | Account holders, authorized signers, and authorized users must have a valid `entity_id` or `client_customer_id` if the account is in a `closed` state. | | Credit Limit Cannot Exceed Max Credit Limit | `credit_limit <= max_credit_limit` if both are provided. | | Missing Adverse Action Notice Detail | If `status_reason = client_closed`, either all three adverse action notice fields are provided or none (`aan_delivered_at`, `aan_reason`, `aan_delivery_method`). | | Invalid Account Status Transition | Updates to non-closed accounts must comply with valid status transitions. | # Application Files: Reporting Underwriting Decisions via SFTP Source: https://docs.lead.bank/file-reference/application/overview Overview of application files. > [!WARNING] > > **Legacy schema — superseded by the Applications API.** New programs integrate via the [Applications API](/products/applications/overview). This schema remains the supported path for file-integrated programs that have not yet migrated. Application files capture information related to consumers' applications for partner products sponsored by Lead. > [!TIP] > > Applications are required for credit products and optional for depository products as they include underwriting and decisioning information on how a consumer was evaluated prior to Account creation. Depository products typically only require Applications when there is a credit component. **Example:** In the case of certain credit builder products, this file is used for informing Lead about all applications, as well as updating Lead on the status of applications. > [!TIP] > > A single application should be updated multiple times until the application is in a terminal state: > > * `approved` > * `declined` > * `canceled` # Application File Schema Source: https://docs.lead.bank/file-reference/application/schema Field-level reference for the Application file, covering decisions, adverse action notice fields, and credit details. > [!WARNING] > > **Legacy schema — superseded by the Applications API.** New programs integrate via the [Applications API](/products/applications/overview). This schema remains the supported path for file-integrated programs that have not yet migrated. > [!TIP] > > For all optional fields where you do not plan to pass through data, please include the header and an empty value. ## IDs and details | **Field** | **Description** | **Required** | **Data Type** | | - | - | - | - | | client\_application\_id | A unique ID for the application generated by your system. Cannot start with `application_` (reserved for Lead-generated application IDs). | Required | string | | account\_holder\_type | Type of account holder. | Required | enum: `consumer` `commercial` | | account\_holders | IDs of any account holders and co-holders. | Required | JSON: \ | | authorized\_signers | A list of authorized signers. These are persons who can access, control and change products and services on the account. | Required with `min_size` >= 1 if `account_holder_type` = `commercial` and `status = approved` | An array of authorized signer IDs JSON: \ | | currency | Application currency code. 3 letter code, e.g. USD | Required | [ISO4217](https://www.iso.org/iso-4217-currency-codes.html) | | client\_product\_name | Name of the product offered by the partner | Required | string | | is\_secured | Indicate if the product is a secured credit or secured deposit product - e.g. will have collateral attached. | Required | boolean | ## Status and timing | **Field** | **Description** | **Required** | **Data Type** | | :- | :- | :- | :- | | created\_at | Datetime application initiated. | Required | datetime [ISO8601](https://www.iso.org/iso-8601-date-and-time-format.html) | | submitted\_at | Datetime the application was submitted. | Required | datetime [ISO8601](https://www.iso.org/iso-8601-date-and-time-format.html) | | status | See [Application Statuses](/file-reference/application/statuses) | Required | enum: `submitted` `under_review` `approved` `declined` `canceled` | | decided\_at | Datetime a final decision (`approved`, `declined`, `canceled`) was made on the application. | Required if `status` = `approved`, `declined`, `canceled` | datetime [ISO8601](https://www.iso.org/iso-8601-date-and-time-format.html) | | decision\_reason | The reason for the final status of `approved`, `declined`, `canceled` | Required if `status` = `approved`, `declined`, `canceled` | String | ## Adverse action notice and exception approval | **Field** | **Description** | **Required** | **Data Type** | | :- | :- | :- | :- | | aan\_delivered\_at | The datetime the AAN was delivered. | Required if `status` = `declined` | datetime [ISO8601](https://www.iso.org/iso-8601-date-and-time-format.html) | | aan\_reason | Reason an adverse action notice (AAN) was sent to the customer. | Required if `status` = `declined` | string | | aan\_delivery\_method | AAN delivery method. | Required if `status` = `declined` | enum: `email` `text` `other` | | is\_exception\_approval | `true` if the application would not have been accepted without some kind of exception, such as a credit limit decision override; `false` otherwise. | Required | boolean | | exception\_reason | The reason this application was approved as an exception, such as an overridden credit limit decision. | Required if `is_exception_approval` = `true` | string | ## Compliance | **Field** | **Description** | **Required** | **Data Type** | | :- | :- | :- | :- | | documents | An array of JSON hash of customer-facing documents. The JSON hash should include the name of the document, and client\_document\_name or document\_id that's been uploaded to Documents folder. This will be defined between the partner and Lead during setup. | Required | **Example** "document\_id": "client\_document\_123", "type":"esign\_agreement","consented\_at":"2025-12-31T15:38:34.101-06:00","version":"20220202" For documents uploaded via SFTP, please input the full file name as document\_id. The suggested naming convention is: `___.` Note: JSON strings embedded in CSV fields must be enclosed in double quotes, with internal double quotes escaped by doubling them (""). | ## Credit Details | **Field** | **Description** | **Required** | **Data Type** | | :- | :- | :- | :- | | is\_mla | `true` if the customer is subject to the Military Lending Act; `false` otherwise | Required for credit products | boolean | | underwriting\_grade | The grade or score given to the customer based on underwriting. | Required for credit products AND `status` in (`approved`, `declined`) | string | | credit\_limit | The maximum amount the customer can draw. This may be different from the max credit limit the customer has been approved for. | Required for credit products AND `status` = `approved` | number [currency decimal ](/file-reference/delivery/currencies) | | max\_credit\_limit | The maximum credit limit the customer has been approved for based on original underwriting and the product. | Required for credit products AND `status` = `approved` | number [currency decimal](/file-reference/delivery/currencies) | ## Credit Bureau Data | **Field** | **Description** | **Required** | **Data Type** | | :- | :- | :- | :- | | credit\_pulled\_at | The date the credit report is pulled. | Required if your program's underwriting policy requires credit bureau data on all applications. This will be agreed upon with Lead's Legal team during implementation. Required if any of `credit_score`, `credit_report_non_score_value`, or `credit_report_source` are present. | datetime [ISO8601](https://www.iso.org/iso-8601-date-and-time-format.html) | | credit\_score | Credit score given by the credit bureau. Supported range is 300 to 850. Mutually exclusive with `credit_report_non_score_value`. | Required if your program's underwriting policy requires credit bureau data on all applications. This will be agreed upon with Lead's Legal team during implementation Required if credit bureau data is present and `credit_report_non_score_value` is not provided. | number | | credit\_report\_non\_score\_value | Indicates the state of a credit file when a numeric score is not available. Mutually exclusive with `credit_score`. | Required if credit bureau data is present and `credit_score` is not provided. | enum: `unestablished` `frozen` | | credit\_report\_source | The name of the credit bureau. | Required if your program's underwriting policy requires credit bureau data on all applications. This will be agreed upon with Lead's Legal team during implementation Required if any of `credit_pulled_at`, `credit_score`, or `credit_report_non_score_value` are present. | enum: `equifax` `experian` `transunion` | ## Other | **Field** | **Description** | **Required** | **Data Type** | | :- | :- | :- | :- | | generated\_at | The day this file is generated. This should always be the date the file is sent to Lead Bank. | Required | datetime [ISO8601](https://www.iso.org/iso-8601-date-and-time-format.html) | | effective\_at | The timestamp of when the related object(s) were polled to collect the information for this record. | Required | datetime [ISO8601](https://www.iso.org/iso-8601-date-and-time-format.html) | # Application File Statuses Source: https://docs.lead.bank/file-reference/application/statuses The statuses for application files. > [!WARNING] > > **Legacy schema — superseded by the Applications API.** New programs integrate via the [Applications API](/products/applications/overview). This schema remains the supported path for file-integrated programs that have not yet migrated. ## Statuses | **Status** | **Description** | | - | - | | `submitted` | Application has been submitted by end consumer | | `under_review` | Application has been submitted and is under review, and a final decision has not been made yet. | | `approved` | You have approved a consumer's application. | | `declined` | You have declined a consumer's application. | | `canceled` | End consumer has canceled the application or application has expired. | ## Transitions | **Status** | **Can transition to** | | - | - | | `submitted` | `under_review` `approved` `declined` `canceled` | | `under_review` | `approved` `declined` `canceled` | | `approved` | Is a terminal state. | | `declined` | Is a terminal state. | | `canceled` | Is a terminal state. | # Application File Validations Source: https://docs.lead.bank/file-reference/application/validations Validating application files. > [!WARNING] > > **Legacy schema — superseded by the Applications API.** New programs integrate via the [Applications API](/products/applications/overview). This schema remains the supported path for file-integrated programs that have not yet migrated. Beyond the standard required and optional field checks and data type validations, Lead performs additional validations. > [!NOTE] > > The below list is non-exhaustive — we aim to be thoughtful and robust in validations that ensure high data quality to enable us to provide effective oversight. ## Enforced Today | **Validation** | **Description** | | - | - | | Missing Decision Reason | Status is `approved`, `declined`, or `canceled` without `decision_reason` field also populated. | | Missing Adverse Action Notice | Adverse action notices are required if `status = declined`. | | Missing Credit Score Detail | When you provide credit bureau data, include `credit_pulled_at`, `credit_report_source`, and exactly one of `credit_score` or `credit_report_non_score_value`. Provide all applicable fields or none. | | Invalid Entity Reference on Terminal Application | References to Account holders, Authorized Signers, and Authorized Users by `client_customer_id` or `entity_id` must refer to entities that have already been submitted to Lead if the application is in a [terminal state ](/file-reference/application/statuses). | | May Not Change Terminal Application | Updates may not be made to applications in a [terminal state](/file-reference/application/statuses). | | Entity Role Mismatch For Approved Application | If the application is approved, role requirements for each entity must meet account holder / authorized signer / authorized user corresponding role requirements. | | Previous Application Has `effective_at` >= current application `effective_at` | On Application Update, effective at must be greater than the previous instance of this record. | ## Future Enforcements > [!WARNING] > > Lead expects partners to comply with the below validations; however we do not currently enforce them upon daily processing. We will provide you with 60 days notice before enforcing the following validations. | **Validation** | **Description** | | - | - | | Invalid Namespace | `client_application_id` cannot start with `application_` | | Invalid Entities on Application | Account holders, Authorized Signers, and Authorized Users must have valid `entity_id` or `client_customer_id` if the application is in any [terminal state](/file-reference/application/statuses). | | Credit Limit Cannot Exceed Max Credit Limit | `credit_limit <= max_credit_limit` if both are provided | | Missing Adverse Action Notice Detail | If status is in a [terminal state](/file-reference/application/statuses), either all three adverse action fields are provided or none are `(aan_delivered_at, aan_reason, aan_delivery_method)`. | | Invalid Application status transition | Updates to nonterminal applications must comply with valid [status transitions](/file-reference/application/statuses). | # Authorized Users Schema Source: https://docs.lead.bank/file-reference/authorized-users/schema Field-level reference for the Authorized Users file. > [!NOTE] > > **File-era companion schema.** This file accompanies the legacy file-based workflows above and remains the active path for programs that use it — it has no API successor yet. > [!NOTE] > > Daily updates to users on the accounts that are active or made inactive on corresponding accounts. > [!TIP] > > For all optional fields where you do not plan to pass through data, please include the header and an empty value. ## IDs | **Field** | **Description** | **Required** | **Data Type** | | - | - | - | - | | entity\_id | The unique customer ID of the authorized user on this account. | Required | string | | account\_id | The ID of the account associated with this authorized user. | Required | string | ## Status | **Field** | **Description** | **Required** | **Data Type** | | :- | :- | :- | :- | | status | `active`: a new user that has been added to the account `inactive`: a previously sent user that has deactivated from the account | Required | enum | ## Other | **Field** | **Description** | **Required** | **Data Type** | | :- | :- | :- | :- | | generated\_at | The day this file is generated. This should always be the date the file is sent to Lead Bank. | Required | ISO8601 | | effective\_at | The timestamp of when the related object(s) were polled to collect the information for this record. | Required | datetime ISO8601 | # Authorized Users Validations Source: https://docs.lead.bank/file-reference/authorized-users/validations Validating authorized users. > [!NOTE] > > **File-era companion schema.** This file accompanies the legacy file-based workflows above and remains the active path for programs that use it — it has no API successor yet. > [!NOTE] > > Beyond the standard required and optional field checks and data type validations, Lead performs additional validations. ## Enforced Today | **Validation** | **Description** | | - | - | | Invalid Account Reference | `account_id` must reference a valid account within Lead's system. | | Invalid Entity Reference | `entity_id` must reference a valid entity within Lead's system. | | Effective At Outdated | `effective_at` must be more recent than the previous instance in which an `account_id`, `entity_id` pairing was provided in the Authorized Users File (if the same pairing was previously provided) | ## Future Enforcements > [!WARNING] > > Lead expects partners to comply with the below validations; however we do not currently enforce them upon daily processing. We will provide you with 60 days notice before enforcing the following validations. | **Validation** | **Description** | | - | - | | Nonterminating Update to Authorized User on Closed Account | Updates to existing authorized users *must* include an `invalid` status if the account is closed. | # Balance & Transaction Validations Source: https://docs.lead.bank/file-reference/balances-and-transactions/balance-validations Reference for Balance and Transaction file validations, including daily reporting rules, account_id matching, and balance reconciliation checks. ## Balances File ### All Balances | **Validation** | **Description** | | - | - | | All Balances with a non-terminal status must be reported daily | All Balances that exist in a non-terminal status on T-1 must be reported in the Balance file submitted on day T. The Subledger Balance object created via the API and the Balance record in the file represent the same underlying object — meaning this validation applies to any Subledger Balance objects. Subledger Balance objects created on T-1 must be included in day T's Balance file. A newly created Subledger Balance with a zero-dollar balance must still appear in the next day's file. Terminal statuses are `closed` and `receivable_transferred`. | | New Balances can only be created either via API or files, but not both | For programs that use the Subledger Balance API to create Balances, only the API can be used to create new Balances. Lead validates that no new, unrecognized balances appear in a Balance file. For programs that use the Balance file to create Balances, only the file can be used to create new Balances. For these use cases, unrecognized balances can appear in a Balance file, and we treat these as new Balance objects to be created in Lead's system. | | Balance file `account_id` must match the API record | Because they represent the same underlying object, Lead validates that the `account_id` associated with a given Balance in a Balance file matches the `account_id` that was used to create the Balance via the Subledger Balance API. | | New Balances must reference a valid parent Account | Lead validates that the `account_id` on a new Balance record matches an Account that exists and belongs to your program. You may submit either the API-generated `account_id` or your own `client_account_id` — both resolve to the same Account. The Account record must be submitted and processed successfully before the Balance file that references it. A failure returns `account_not_found`. | | The parent Account must be in a permitted status | Lead validates that the Account referenced by a new Balance record is in `active` or `inactive` status. Accounts in any other status, including `closed`, are rejected. This check runs only at Balance creation — Lead does not re-validate Account status when subsequent activity is reported against an existing Balance. A failure returns `account_status_invalid`. | | The parent Account must support the Balance `type` | If the referenced Account has a `capabilities` array, Lead validates that it supports the `type` of Balance being created: `deposit` Balances require the `deposit` capability, and `credit` Balances require either `credit_with_underwriting` or `credit_without_underwriting`. Accounts with no `capabilities` array — including all Accounts created via the Account file — bypass this check. A failure returns `account_capability_missing`. | ### Deposit Balance > [!NOTE] > > See [Balance Reconciliation and Examples](/products/balances-and-transactions/balance-reconciliation) for specific examples. | **Validation** | **Description** | | - | - | | `balance` on t = `balance` on t-1 + `daily_activity` on t | `daily_activity` on t = sum(`transactions.amount`) where `transactions.type` not in (`interest_accrued`,`charge_off_recovery`,`dispute_won`) | | `rewards_balance` on t = `rewards_balance` on t-1 + `daily_rewards_activity` on t | `daily_rewards_activity` on t = sum(`transactions.rewards_amount`) where `transactions.type` in (`rewards_earned`, `rewards_spent`, `rewards_redeemed`,`debit`, `refund`,`credit`) | | `interest_accrued_balance` on t = `interest_accrued_balance` on t-1 + `daily_interest_activity` on t | `daily_interest_activity` on t = `transactions.amount` where `transactions.type`=`interest_accrued` - `transactions.amount` where `transactions.type`= `interest_paid` | | `dispute_balance` on t = `dispute_balance` on t-1 + `daily_dispute_activity` on t | `daily_dispute_activity` on t = sum (`amount`) where `transactions.type` in (`dispute_provisional`, `dispute_won`, `dispute_lost`) | | `charge_off_balance` on t = `charge_off_balance` on t-1 + `daily_charge_off_activity` on t | `daily_charge_off_activity` on t = sum (`transactions.amount`) where `transactions.type`in (`charge_off`, `charge_off_recovery`) | ### Credit Balance > [!NOTE] > > See [Balance Reconciliation and Examples](/products/balances-and-transactions/balance-reconciliation) for specific examples. | **Validation** | **Description** | | - | - | | `balance` on t = `balance` on t-1 + `daily_activity` on t | `daily_activity` on t = sum(`transactions.amount`) where `transactions.type` not in (`charge_off_recovery`,`dispute_won`) | | any `balance` across `balance`, `dispute_balance`, `past_due_balance`, `charge_off_balance` will have the following validations: | `*balance` = `*principal` + `*interest` + `*fees` | | `outstanding_principal` on t = `outstanding_principal` on t-1 + `daily_principal_activity` on t | `daily_principal_activity` on t = sum (`transactions.principal_amount`) where `transactions.type` not in (`fee`,`interest_accrued`,`charge_off_recovery`,`dispute_won`) | | `outstanding_fees` on t = `outstanding_fees` on t-1 + `daily_fees_activity` on t | `daily_fees_activity` on t = sum(`transactions.fee_amount`) where transactions.type not in (`disbursement`,`interest_accrued`,`charge_off_recovery`,`dispute_won`) | | `outstanding_interest` on t = `outstanding_interest` on t-1 + `daily_interest_activity` on t | `daily_interest_activity` on t = sum(`transactions.interest_amount`) where transactions.type not in (`disbursement`,`fee`,`charge_off_recovery`,`dispute_won`) | | `rewards_balance` on t = `rewards_balance` on t-1 + `daily_rewards_activity` on t | `daily_rewards_activity` on t = sum(`transactions.rewards_amount`) where `transactions.type` in (`rewards_earned`, `rewards_spent`, `rewards_redeemed`,`disbursement`, `refund`,`client_credit`) | | `dispute_balance` on t = `dispute_balance` on t-1 + `daily_dispute_activity` on t | `daily_dispute_activity` on t = -`transactions.amount` where `transactions.type` = `dispute_provisional`+ `transactions.amount` where `transactions.type` = `dispute_won` - `transactions.amount` where `transactions.type` = `dispute_lost` (the same logic applies for `dispute_principal`, `dispute_fees`, `dispute_interest`) | | `charge_off_balance` on t = `charge_off_balance` on t-1 + `daily_charge_off_activity` on t | `daily_charge_off_activity` on t = - `transactions.amount` where `transactions.type` = `charge_off` + `transactions.amount` where `transactions.type` = `charge_off_recovery` (the same logic applies for `charge_off_principal`, `charge_off_fees`, `charge_off_interest`) | | `past_due_balance<=balance` | `past_due_principal<=outstanding_principal`; `past_due_fees<=outstanding_fees` ; `past_due_interest<=outstanding_interest` If a credit balance is both past due and charged off, the amount should only be included in `charge_off_balance` and not in `past_due_balance`. | | Balances with processing Funding objects cannot be closed | Lead validates that any Balance being reported as closed in a Balance file does not have associated Funding objects in a processing status. This ensures that Funding objects that eventually post can be reported as disbursement transactions, which would not be possible if the Balance has a closed status. | | No transactions can be reported after `receivable_transferred` | Lead validates that no transactions are reported on a balance after its status has been set to `receivable_transferred`. | | Only credit balances can be set to `receivable_transferred` | The `receivable_transferred` status is not valid for deposit balances. | ## Transactions File | **Validation** | **Description** | | - | - | | All transaction IDs must be unique | All transaction IDs in this file are unique and have never been seen in a Transactions file before. This validation is how Lead ensures that no duplicate transactions are accidentally reported. | | All posted Fundings from T-1 must be reported | Lead validates that any Funding objects that transitioned to a posted status during T-1 (as measured by your program's definition of a 24-hour period) are reported in the Transaction file. | | Reported Funding objects must be in a posted status | Lead validates that any Funding object reported in a Transaction file (represented as a Transaction record with `type` = `disbursement`) is in a posted status. This prevents a case where a pending Funding object is reported prematurely. | | `balance_id` on the Transaction and Funding object must match | Lead validates that any disbursement transaction reported with a `funding_id` has a `balance_id` that matches the `subledger_balance_id` on the Funding object. | | Funding `effective_at` must match the posted timestamp | Lead validates that all Funding objects reported have an `effective_at` date that matches when the Funding object transitioned to a posted status. For example, if a Funding object transitioned to a posted status anytime during the 2025-12-31 24-hour period, the reported `effective_at` date must be set to 2025-12-31. | | No duplicate `funding_id` values | Lead validates that any `funding_id` reported in a Transaction file has not previously been reported and successfully processed. This prevents a case where a duplicate receivable is created for a single Funding request. | | `fee_amount` on the disbursement transaction must match Funding `borrower_origination_fee_amount` | For funding disbursement transactions, Lead validates that `fee_amount` equals `other_fees.borrower_origination_fee_amount` on the associated Funding object. A mismatch returns a `funding_fee_amount_mismatch` error. | # Balances Schema Source: https://docs.lead.bank/file-reference/balances-and-transactions/balances-schema Field-by-field reference for the daily Balances file, including credit and deposit balances, rewards, repayment details, and autopay configuration. > [!NOTE] > > **API successor in flight.** Balances are moving from this daily file to the User Deposit Balance and User Credit Balance objects in the API. This schema is authoritative until the successor is Released. > [!TIP] > > For all optional fields where you do not plan to pass through data, please include the header and an empty value. Balances can be type `credit` or `deposit`. ## IDs and details | **Field** | **Description** | **Required** | **Data Type** | | - | - | - | - | | account\_id | Unique ID of the Account this balance belongs to. If you create Accounts via the API, use the Lead-generated `account_id`; if you create Accounts via the Accounts File, use the `client_account_id` that you specified. The referenced Account must be recognized by Lead, be in `active` or `inactive` status, and support this balance's `type`. See [Balance Validations](/file-reference/balances-and-transactions/balance-validations#all-balances). | Required | string | | client\_balance\_id | Partner-generated unique ID of the balance. Populate this field only if the balance was initially created via a file workflow. If the balance was created via API, leave this field blank. Lead uses this ID to reconcile day-over-day changes to balance, and each balance has a single ID across its lifecycle. | Required if the balance was created via a file workflow | string | | id | Lead-generated unique ID of the balance. Populate this field with the server-generated ID returned from a [Create Subledger Balance API](https://docs.lead.bank/api-reference/endpoint/subledger-balance/create-a-subledger-balance) call. If the balance was not created via API, leave this field blank. Lead uses this ID to reconcile day-over-day changes to balance, and each balance has a single ID across its lifecycle. | Required if the balance was created via an API workflow | string | | client\_balance\_name | A name that is used to identify the product or balance being reported (e.g., Rainy Day Fund). | Required | string | | client\_settlement\_bank\_account\_id | ID of the underlying settlement bank account where funds for the balance\_id are held. | Required for programs with balances held across multiple FBOs and Banks | enum (these will be provided by Lead during your implementation) | ## Status and timing | **Field** | **Description** | **Required** | **Data Type** | | :- | :- | :- | :- | | created\_at | Datetime the Balance was initiated. | Required | datetime [ISO8601](https://www.iso.org/iso-8601-date-and-time-format.html) | | status | See [Balance Statuses](/products/balances-and-transactions/balance-statuses) for more detail. | Required | enum | | status\_reason | See [Balance Statuses](/products/balances-and-transactions/balance-statuses) for more detail. | Required | enum | | type | Possible enums: `deposit`, `credit`. If the referenced Account has a [`capabilities`](/products/accounts/validations#capability-driven-validations) array, it must support this type — `deposit` requires the `deposit` capability and `credit` requires `credit_with_underwriting` or `credit_without_underwriting`. See [Balance Validations](/products/accounts/validations#all-balances). | Required | enum | ## Balance Activity | **Field** | **Description** | **Required** | **Data Type** | | :- | :- | :- | :- | | balance | End customer's available balance as of the report's effective date/time. For credit products, Lead validates that `balance` = `outstanding_principal` + `outstanding_interest` + `outstanding_fees`. | Required | number [currency decimals](/file-reference/delivery/currencies) | | currency | The currency in which the `balance` is denoted. | Required | [ISO4217](https://www.iso.org/iso-4217-currency-codes.html) | | balance\_in\_usd | Balance in USD | Required if the program can have non-USD balances | number | | outstanding\_principal | The outstanding balance allocated to principal. | Required if `type` = `credit` | number [currency decimals](/file-reference/delivery/currencies) | | outstanding\_interest | The outstanding balance allocated to interest. | Required if `type` = `credit` | number [currency decimals](/file-reference/delivery/currencies) | | outstanding\_fees | The outstanding balance allocated to fees. | Required if `type` = `credit` | number [currency decimals](/file-reference/delivery/currencies) | ## Rewards Balance > [!NOTE] > > See [Rewards Balance example](/products/balances-and-transactions/balance-reconciliation#examples). | **Field** | **Description** | **Required** | **Data Type** | | :- | :- | :- | :- | | rewards\_balance | The cumulative rewards accrued that have not been paid out on this account. | Required for reward-offering products | number decimal(M, 2) E.g., `11.50` | | rewards\_unit | The unit of the rewards accrued. Possible enums: `usd`, `points`. | Required for reward-offering products | enum `usd` `points` | ## Dispute Balance > [!NOTE] > > See [Dispute Balance example](/products/balances-and-transactions/balance-reconciliation#examples). | **Field** | **Description** | **Required** | **Data Type** | | :- | :- | :- | :- | | dispute\_balance | The cumulative amount that is under dispute. Do not include this amount in `balance`. For credit products, Lead validates that `dispute_balance` = `dispute_principal` + `dispute_interest` + `dispute_fees`. | Required | [currency decimals](/file-reference/delivery/currencies); amount should be 0 or positive | | dispute\_principal | The dispute balance allocated to principal. This amount is cumulative. | Required if `type` = `credit` | [currency decimals](/file-reference/delivery/currencies); amount should be 0 or positive | | dispute\_interest | The dispute balance allocated to interest. This amount is cumulative. | Required if `type` = `credit` | [currency decimals](/file-reference/delivery/currencies); amount should be 0 or positive | | dispute\_fees | The dispute balance allocated to fees. This amount is cumulative. | Required if `type` = `credit` | [currency decimals](/file-reference/delivery/currencies); amount should be 0 or positive | ## Charge Off Balance > [!NOTE] > > See [Charge Off Balance example](/products/balances-and-transactions/balance-reconciliation#examples). | **Field** | **Description** | **Required** | **Data Type** | | :- | :- | :- | :- | | charge\_off\_balance | The cumulative amount charged off. Do not include this amount in `balance`. For credit products, Lead validates that `charge_off_balance` = `charge_off_principal` + `charge_off_interest` + `charge_off_fees`. | Required | [currency decimals](/file-reference/delivery/currencies); amount should be 0 or positive | | charge\_off\_principal | The charge-off balance allocated to principal. This amount is cumulative. | Required if `type` = `credit` | [currency decimals](/file-reference/delivery/currencies); amount should be 0 or positive | | charge\_off\_interest | The charge-off balance allocated to interest. This amount is cumulative. | Required if `type` = `credit` | [currency decimals](/file-reference/delivery/currencies); amount should be 0 or positive | | charge\_off\_fees | The charge-off balance allocated to fees. This amount is cumulative. | Required if `type` = `credit` | [currency decimals](/file-reference/delivery/currencies); amount should be 0 or positive | ## Past Due Balance > [!NOTE] > > See [Past Due Balance example](/products/balances-and-transactions/balance-reconciliation#examples). | **Field** | **Description** | **Required** | **Data Type** | | :- | :- | :- | :- | | past\_due\_balance | Applicable to credit products only: balance past due. This amount is cumulative and must always be equal to or less than `balance`. If a credit balance is both past due and charged off, include the amount only in `charge_off_balance`, not in `past_due_balance`. Note `past_due_balance` = `past_due_principal` + `past_due_interest` + `past_due_fees`. | Required if `type` = `credit` | [currency decimals](/file-reference/delivery/currencies); amount should be 0 or positive | | past\_due\_days | Applicable to credit products only: The number of days the balance is past due. Must be greater than 0 if `past_due_balance` is greater than 0; report `0` when `past_due_balance` is `0`. | Required if `type` = `credit` | integer | | past\_due\_principal | Applicable to credit products only: The past due balance allocated to principal. This amount is cumulative. Report `0` when `past_due_balance` is `0`. | Required if `type` = `credit` | [currency decimals](/file-reference/delivery/currencies); amount should be 0 or positive | | past\_due\_interest | Applicable to credit products only: The past due balance allocated to interest. This amount is cumulative. Report `0` when `past_due_balance` is `0`. | Required if `type` = `credit` | [currency decimals](/file-reference/delivery/currencies); amount should be 0 or positive | | past\_due\_fees | Applicable to credit products only: The past due balance allocated to fees. This amount is cumulative. Report `0` when `past_due_balance` is `0`. | Required if `type` = `credit` | [currency decimals](/file-reference/delivery/currencies); amount should be 0 or positive | ## Interest Rate | **Field** | **Description** | **Required** | **Data Type** | | :- | :- | :- | :- | | interest\_rate | For deposit products, this field represents the annualized interest rate offered to customers on this balance. For credit products, this field represents the interest rate disclosed to the borrower for this balance. | For deposit products, required if the product accrues interest. For credit products, required if `type` = `credit` AND `is_interest_based` = `true` | decimal(M, 6). E.g., 11.500000% interest rate reported as `11.500000`. *Previously, decimal(M, 3) was supported for credit products.* | ## Interest Accrued Balance | **Field** | **Description** | **Required** | **Data Type** | | :- | :- | :- | :- | | interest\_accrued\_balance | Applicable to deposit products only: The cumulative interest accrued that has not been paid out on this balance. This must be in the same currency as the deposit balance. | Required for deposit programs with interest | For deposit programs with interest, value is a number with minimum [currency decimals](/file-reference/delivery/currencies) (e.g., if currency is USD, value must be at least 2 decimal places, `11.500`) | | interest\_accrued\_balance\_in\_usd | Applicable to deposit products only: The cumulative interest accrued balance (in USD) that has not been paid out on this account. | Required for deposit programs with interest and if your customers can hold non USD balances | number Minimum 2 decimals, `11.50` or `11.500` | ## Credit Details | **Field** | **Description** | **Required** | **Data Type** | | :- | :- | :- | :- | | structure | Indicates whether the credit product represented by this balance allows funds to be redrawn after repayment. | Required if the balance was created via an API workflow | enum: - `revolving`: Used for products where the available credit replenishes as the borrower makes repayments. Common examples include credit cards and revolving lines of credit. Borrowers can draw, repay, and draw again, up to the credit limit. - `non_revolving`: Used for products where funds can only be drawn once (or up to a pre-set number of draws) and repayments do not increase available credit. A common example is a term loan product. | | expected\_maturity\_date | The expected maturity date of the loan. | Required for non-revolving credit products | date YYYY-MM-DD | | repayment\_details | Repayment details for the credit balance. Array of JSON objects — see [field reference](#repayment-details) below. | Required if `expected_maturity_date` is present and the balance was created via a file workflow. Required if `type` = `credit` and the balance was created via an API workflow. | Array of JSON objects | | is\_interest\_based | Indicates whether the credit balance is interest-based. | Required if `type` = `credit` | boolean | | effective\_apr | The APR as disclosed to the borrower. If the product is fee-based, please include the fee amount in your calculation of this field. | Required if `type` = `credit` | number decimal(M,3). E.g., 11.520% APR reported as `11.520` | | effective\_interest\_rate | The true annualized cost of borrowing to the borrower, taking into account the interest rate and impact of compounding. This is the actual annualized accrual rate you apply to the balance for interest accrual during a period. | Required if `type` = `credit` and the balance was created via an API workflow | number decimal(M,6). E.g., 9.123456% effective interest rate reported as `9.123456` | | expected\_finance\_charge\_amount | The total expected finance charge if the customer pays according to the loan schedule. | Required if `expected_maturity_date` is present and the balance was created via a file workflow. Required if `type` = `credit`, `structure` = `non_revolving`, and the balance was created via an API workflow. | number [currency decimals](/file-reference/delivery/currencies) | | autopay\_method | The payment rail used to collect scheduled autopay repayments for this credit balance. Set to `none` if the borrower has not enrolled in autopay. Autopay is configured at the balance level — individual autopay repayments appear in the Transactions file as `payment` transactions whose `transfer_type` matches the rail used (e.g., `ach`, `card`). There is no separate autopay flag on the transaction record. | Required if `type` = `credit` | enum (`ach`, `debit_card`, `wire`, `virtual_wallet`, `credit_card`,`none`) | | max\_funding\_amount | The maximum amount of funding that will be requested for this non-revolving credit product (e.g., term loan). This amount can be requested via a single draw or via multiple draws. | Required if `type` = `credit`, `structure` = `non_revolving`, and the balance was created via an API workflow | number [currency decimals](/file-reference/delivery/currencies) | | term\_value | The number of units in the contractual term length for this non-revolving credit product (e.g., term loan). E.g., if the term length for the term loan is 6 months, set this value to `6`. | Required if `type` = `credit`, `structure` = `non_revolving`, and the balance was created via an API workflow | integer, >0 | | term\_unit | The unit of the contractual term length for this non-revolving credit product (e.g., term loan). E.g., if the term length for the term loan is 6 months, set this value to `months`. Possible enums: `days`, `weeks`, `months`, `years`. | Required if `type` = `credit`, `structure` = `non_revolving`, and the balance was created via an API workflow | enum | ### Repayment Details Each object in the `repayment_details` array contains the following fields: | **Field** | **Description** | **Required** | **Data Type** | | :- | :- | :- | :- | | expected\_payment\_frequency | The cadence at which the borrower is expected to make payments. | Required | enum: - `business_daily`: Once per business day - `weekly`: Once per week - `biweekly`: Once every two weeks (26 payments/year) - `semi_monthly`: Twice per month on fixed calendar days (24 payments/year) - `monthly`: Once per calendar month - `quarterly`: Once every calendar quarter (4 payments/year) - `semi_annually`: Once every 6 months (2 payments/year) - `annually`: Once per calendar year - `fixed_interval`: Payments occur after a fixed number of elapsed days; pair with `expected_payment_frequency_interval_days` - `maturity`: A single payment at loan maturity - `variable`: Repayment does not follow a predictable time-based cadence (e.g., event-driven repayment) | | expected\_payment\_frequency\_interval\_days | The number of days between expected payments when the schedule follows a fixed interval rather than a calendar period. | Required when `expected_payment_frequency` = `fixed_interval`. Must not be present otherwise. | integer (1–730) | | expected\_number\_of\_payments | Expected total number of payments if the customer pays according to the loan schedule. | Optional | integer | | expected\_first\_payment\_date | Expected date of the first repayment. Also use this field for products with a single repayment. | Optional | date YYYY-MM-DD | | expected\_first\_payment\_amount | Expected amount of the first repayment. Also use this field for products with a single repayment. | Optional | [currency decimals](/file-reference/delivery/currencies) | | expected\_last\_payment\_date | Expected date of the final repayment. | Optional | date YYYY-MM-DD | | expected\_last\_payment\_amount | Expected amount of the final repayment. | Optional | [currency decimals](/file-reference/delivery/currencies) | | expected\_payment\_amount | Anticipated amount for each repayment installment. | Optional | [currency decimals](/file-reference/delivery/currencies) | > [!NOTE] > > JSON strings embedded in CSV fields must be enclosed in double quotes, with internal double quotes escaped by doubling them (""). > > Example value: `"{""repayment_details"":[{""expected_payment_frequency"":""monthly"",""expected_number_of_payments"":12,""expected_payment_amount"":""1000.00""}]}"` ## Deposit Details (if applicable) | **Field** | **Description** | **Required** | **Data Type** | | :- | :- | :- | :- | | overdraft\_limit | The overdraft amount offered to customers. | Required for products with overdraft | number [currency decimals](/file-reference/delivery/currencies) | | federal\_withholdings | The funds withheld due to federal requirements. | Required for products with overdraft | number [currency decimals](/file-reference/delivery/currencies) | | state\_withholdings | The funds withheld due to state requirements. | Required for products with overdraft | number [currency decimals](/file-reference/delivery/currencies) | | nra\_withholdings | The funds withheld due to NRA requirements. | Required for products with overdraft | number [currency decimals](/file-reference/delivery/currencies) | ## Other | **Field** | **Description** | **Required** | **Data Type** | | :- | :- | :- | :- | | metadata | Additional metadata associated with the balance that needs to be provided. E.g., in a lending case we may request that both standard APRs and promo APRs be included for additional Lead oversight. JSON strings embedded in CSV fields must be enclosed in double quotes, with internal double quotes escaped by doubling them (""). | Optional | JSON | | generated\_at | The timestamp when this file was generated. This should always be the date the file is sent to Lead Bank. | Required | datetime [ISO8601](https://www.iso.org/iso-8601-date-and-time-format.html) | | effective\_at | The timestamp when the related object(s) were polled to collect the information for this record. This is typically an EOD timestamp on one day prior to the `generated_at` timestamp, since T-1 EOD balances (`effective_at`) are reported on T (`generated_at`). | Required | datetime [ISO8601](https://www.iso.org/iso-8601-date-and-time-format.html) | # Non-Posted Transactions Schema Source: https://docs.lead.bank/file-reference/balances-and-transactions/non-posted-transactions-schema Field-level reference for the Non-Posted (pending) Transactions file. > [!NOTE] > > **API successor in flight.** Non-posted transactions are moving from this daily file to the User Deposit Transaction object in the API. This schema is authoritative until the successor is Released. > [!NOTE] > > Used when funds have settled to your FBO account but not yet posted to your end-user accounts. > [!TIP] > > **Applicable to Balance Type = Deposit Only**\ > This file lists transactions where funds have settled to your FBO account but not yet posted to individual end-user accounts. Transactions remain in this file for N days until posted. Inaccurate data may risk proper account funding and disrupt program operations. > [!TIP] > > For all optional fields where you do not plan to pass through data, please include the header and a null value. ## IDs and details | **Field** | **Description** | **Required** | **Data Type** | | - | - | - | - | | transaction\_id | The unique ID for the transaction. | Required | string | | balance\_id | Unique ID of the balance. | Optional | string | | settlement\_group\_id | If this transaction is net settled, a unique ID to group all transactions in the net settlement. | Optional | string | ## Transaction Information | **Field** | **Description** | **Required** | **Data Type** | | :- | :- | :- | :- | | amount | Transaction amount | Required | number [currency decimals](/file-reference/delivery/currencies) | | currency | The [currency code](/file-reference/delivery/currencies) for the transaction. 3 letter code, e.g. USD | Required | [ISO4217](https://www.iso.org/iso-4217-currency-codes.html) | | amount\_in\_usd | Transaction amount in USD. Only required if `currency` is not USD. | Required if the program can have non-USD balances | number decimal(M,2) | | type | Transaction type. | Required | enum | | transfer\_type | Type of transfer rail. | Required | enum | | reconciliation\_note | Details to explain why the transaction is unsettled. | Required | string | | settlement\_date | The settlement date of this transaction. | Required | date `YYYY-MM-DD` | | transfer\_id | The unique ID for the related transfer object, if applicable (e.g. the ACH ID or Internal Transfer ID generated by Lead) | Optional | string | | statement\_description | The description on the customers statement for this transaction. | Optional | string | ## Other | **Field** | **Description** | **Required** | **Data Type** | | :- | :- | :- | :- | | generated\_at | The day this file is generated. This should always be the date the file is sent to Lead Bank. | Required | datetime [ISO8601](https://www.iso.org/iso-8601-date-and-time-format.html) | | effective\_at | The timestamp of when the related object(s) were polled to collect the information for this record. | Required | datetime [ISO8601](https://www.iso.org/iso-8601-date-and-time-format.html) | # Transactions File Schema Source: https://docs.lead.bank/file-reference/balances-and-transactions/transactions-schema Field-level reference for the Transactions file used in Lead's financial reconciliation, including IDs, amounts, types, and posting details. > [!NOTE] > > **API successor in flight.** Transactions are moving from this daily file to the User Deposit Transaction and User Credit Transaction objects in the API. This schema is authoritative until the successor is Released. > [!NOTE] > > This file is used as part of Lead's financial reconciliation. If the data is inaccurate, then funding the appropriate accounts is at risk, and the program will run into issues. > [!TIP] > > For all optional fields where you do not plan to pass through data, please include the header and an empty value. **Non Posted Transactions** = This file lists transactions where funds have been posted to the Customer FBO account but not yet to customer accounts. In this case, `balances` will not have been affected. Lead will do FBO account reconciliation based on the following: * FBO account balance = sum of `amount` from `Non Posted Transactions`+ sum of `balance` from `Balances` ## IDs and details | **Field** | **Description** | **Required** | **Data Type** | | - | - | - | - | | client\_transaction\_id | The unique ID for the transaction. | Required | string | | balance\_id | ID of the balance. Balances need to exist and be uploaded to Lead. | Required | string | | card\_id | The unique ID for this card if the transaction is a card swipe. Cards need to exist and be uploaded to Lead. | Required for `transfer_type` = `card` | string | | client\_settlement\_group\_id | If this transaction is net settled, a unique ID to group all transactions in the net settlement. | Optional | string | | client\_settlement\_bank\_account\_id | ID of the underlying settlement bank account where funds for the balance\_id are held. Please reach out to Lead to align on enum | Required for programs with balances held across multiple FBOs (with Lead) and Banks (external to Lead) | enum | | bin | The BIN for the card associated with this transaction. Please reach out to Lead to align on enum. | Required for `transfer_type` = `card`, `oct`, and `aft` | enum | ## Transaction Information > [!NOTE] > > See [Transaction Types](/products/balances-and-transactions/transaction-types) for more details on correct signage and value. | **Field** | **Description** | **Required** | **Data Type** | | :- | :- | :- | :- | | amount | Total amount for the transaction. Positive polarity means an increase in balance, and negative polarity means a decrease in balance. When reporting transactions for Credit Balances, this field must equal`principal_amount` + `fee_amount`+ `interest_amount`. | Required | For deposit programs, number with a minimum [currency decimals](/file-reference/delivery/currencies) (e.g., if currency is USD, value must be at least 2 decimals, `11.500`) For credit programs, number [currency decimals](/file-reference/delivery/currencies) | | amount\_in\_usd | Transaction amount in USD. Polarity should match `amount` | Required if the program can have non-USD balances | number Minimum 2 decimals, `11.50` or `11.500` | | currency | [currency code](/file-reference/delivery/currencies) for the transaction. 3 letter code, e.g. USD | Required | [ISO4217](https://www.iso.org/iso-4217-currency-codes.html) | | principal\_amount | Applicable to credit products only: Amount for the transaction that affects the principal. When reporting a transaction that originated from a [Funding object](https://docs.lead.bank/api-reference/endpoint/funding/create-a-funding), this field must equal the sum of all `principal.*` fields. | Required if `balance_id` type = `credit` | number [currency decimals](/file-reference/delivery/currencies) | | fee\_amount | Applicable to credit products only: Amount for the transaction that affects the fees. For transactions with `type` = `disbursement`, `transfer_type` = `internal_transfer`, and `funding_id` is populated, this value must equal `other_fees.borrower_origination_fee_amount` on the associated Funding object. | Required if `balance_id` type = `credit` | number [currency decimals](/file-reference/delivery/currencies) | | interest\_amount | Applicable to credit products only: Amount for the transaction that affects the interest. | Required if `balance_id` type = `credit` | number [currency decimals](/file-reference/delivery/currencies) | | rewards\_amount | Rewards amount. Positive polarity means an increase in rewards balance, and negative polarity means a decrease in rewards balance. | Required if rewards is offered | number decimal(M, 2) e.g. `11.50` | | rewards\_unit | The unit of the rewards. | Required if `rewards_amount` is present | enum `usd` `points` | | type | Transaction type. | Required | enum | | transfer\_type | Type of transfer rail. | Required for certain transaction types (`type`) and optional for remainder. See [Transaction Types](/products/balances-and-transactions/transaction-types) for details. | enum | | fee\_type | Fee type. | Required if `type` = `fee` | enum | | action | Action. | Required | enum `applied` `reversed` | | description | The description on the customers statement for this transaction. | Required | string | | transfer\_ids | The unique IDs for the related transfer object, if applicable (e.g. the ACH ID or Wire ID or Internal Transfer ID generated by Lead). This is an array of transfer IDs (e.g., the ID for an ACH object generated via the Lead API). If >1 transfer\_id, separate using a comma. | Required if `transfer_type` = `ach`, `wire`, `international_wire`, `instant_payment`, or `internal_transfer` and the transaction was initiated via a Lead API. | string `["ach_123", "ach_456"]` | | settlement\_date | The expected settlement date of this transaction. - For `type` = `fee`, this must be set to T-1. - For `type` = `disbursement` and `transfer_type` = `internal_transfer`, this must be set to the date when the Funding object transitioned to a `posted` status (available via the `updated_at` timestamp on the Funding object). - For `transfer_type` = `card`, this must be set to either T or T-1 if the program's timezone is CT or UTC. If the program's file window aligns with the card network settlement window, then it must be T. Please provide the date the transaction was included in the raw settlement file (e.g. VSS-115 for Visa or T\* files for Mastercard). - For all other `types`, this can be set to T-7 or future periods. Please use `Transactions Updates` file if `settlement_date` has been updated from what was submitted via `Transactions`. | Required | date `YYYY-MM-DD` | | original\_transaction\_id | The unique ID for the related transaction (if present). This may be relevant for refunds, disputes or returns with original transaction id. | Highly recommended where programs can attribute refunds and disputes to the original transaction | string | | funding\_id | The unique ID of the Funding object that this transaction represents. See [Lending and Overdraft](/guides/lend/lending-and-overdraft-data-flow) page for more details on how and when Funding objects should be reported in the Transactions file. | Required when the transaction record is intended to report a funding object that was posted. In these scenarios, `type` = `disbursement` and `transfer_type` = `internal_transfer.` | string | ## Card Information | **Field** | **Description** | **Required** | **Data Type** | | :- | :- | :- | :- | | card\_authorization\_amount | Amount authorized at point of sale. Polarity should match `amount` | Optional (transfer\_type must be `card` if provided) | number [currency decimals](/file-reference/delivery/currencies) | | card\_authorization\_currency | Currency at point of sale. | Required if `card_authorization_amount` is present | string | | card\_transaction\_effective\_at | The posted datetime of the transaction. | Required if 1) transfer\_type = `card`  or 2) type = `disbursement` and transfer\_type = `no_money_movement` and client\_settlement\_bank\_account\_id is held at Lead. Must be empty for all other scenarios. | datetime [ISO8601](https://www.iso.org/iso-8601-date-and-time-format.html) | | settlement\_amount | Amount settled with the card network. Polarity should match `amount` | Required for `transfer_type` = `card` and if network settlement can occur in non-USD currencies | number [currency decimals](/file-reference/delivery/currencies) | | settlement\_currency | Card transaction settlement currency. | `card` and if network settlement can occur in non-USD currencies | string | | interchange\_fee\_amount | Amount for the interchange fee of the transaction. | Optional | number [currency decimals](/file-reference/delivery/currencies) | | transaction\_fee\_amount | Amount for the fee of the transaction. | Optional | number [currency decimals](/file-reference/delivery/currencies) | | acquirer\_fee\_amount | Amount for the acquirer fee of the transaction. | Optional | number [currency decimals](/file-reference/delivery/currencies) | | card\_network | Code identifying the network. | Required for `transfer_type` = `card`, `oct`, and `aft`. Must be empty for all other transfer\_type | enum `visa` `mastercard` `pulse` `amex` `star` `accel` `maestro` `interlink` `tabapay` | ## Merchant Information | **Field** | **Description** | **Required** | **Data Type** | | :- | :- | :- | :- | | merchant\_name | Merchant name. | Required for `transfer_type` = `card` | string | | merchant\_address\_line\_1 | Merchant address line 1. | Optional | string | | merchant\_city | Merchant city. | Required for `transfer_type` = `card` | string | | merchant\_state | Merchant state. | Highly Recommended for `transfer_type` = `card` and merchant\_country\_code = `US` | string | | merchant\_country\_code | Merchant country code. | Required for `transfer_type` = `card` | string ISO3166-1 alpha2 | | merchant\_zip\_code | Merchant zip code. | Optional | string | | mcc | Merchant mcc. | Required for `transfer_type` = `card` | string | ## Other | **Field** | **Description** | **Required** | **Data Type** | | :- | :- | :- | :- | | generated\_at | The day this file is generated. This should always be the date the file is sent to Lead Bank. | Required | datetime [ISO8601](https://www.iso.org/iso-8601-date-and-time-format.html) | | effective\_at | The timestamp of when the related object(s) were polled to collect the information for this record. This is typically a timestamp on one day prior to the `generated_at` timestamp, since T-1 transactions (`effective_at`) are reported on T (`generated_at`). Please provide the date that the transaction affected the end-user's balance and their available balance has changed (it does not have to have settled yet). | Required | datetime [ISO8601](https://www.iso.org/iso-8601-date-and-time-format.html) | # Transactions Update Schema Source: https://docs.lead.bank/file-reference/balances-and-transactions/transactions-update-schema Field-level reference for the Transactions Update file used to correct or amend previously reported transactions. > [!NOTE] > > **API successor in flight.** Transaction updates are moving from this daily file to the User Deposit Transaction object in the API. This schema is authoritative until the successor is Released. > [!NOTE] > > Used when the settlement date differs from the one submitted in the Transactions files. > [!TIP] > > **Applicable to Balance Type = Deposit Only**\ > This file captures transactions where the actual settlement date differs from the one submitted in the Transactions file. It provides the updated `settlement_date` and supports financial reconciliation by ensuring accurate alignment of transaction timing.\ > \ > Inaccurate data may risk proper account funding and disrupt program operations. ## Overview The purpose of this file is so that you can report when the `settlement_date` of a transaction previously reported in a Transaction file was different than initially forecasted. As an example, an ACH or Wire transaction can be initiated and reported as a transaction, but actual money movement may not always be deterministic (e.g., it may be held in manual review and not posted at the time you initially predicted). By reporting an updated `settlement_date`, this allows Lead to run reconciliation of bank accounts (typically an FBO) with the latest information of when funds should have been sitting in the account. In contrast, `effective_at` dates reported in the Transaction file cannot be updated. `effective_at` represents when the available balance for an end-user was updated. This is a deterministic timestamp and is independent of when underlying funds settle, which cannot always be accurately forecasted. > [!TIP] > > For all optional fields where you do not plan to pass through data, please include the header and an empty value. **Transactions Updates** = This file captures transactions where the actual settlement date differs from the one in `Transactions` file. Example may be where a transaction was expected to be posted on January 1st, 2025 per `Transactions` and ended up posting on January 2nd, 2025. In this case, partners use `Transactions Updates` to update `settlement_date` for the `transaction_id`. ## Schema ### IDs and details | **Field** | **Description** | **Required** | **Data Type** | | - | - | - | - | | transaction\_id | The unique ID for the transaction. Before including an ID in this file, please ensure that it has previously been submitted in the Transactions File so that Lead has an existing awareness of the ID. | Required | string | ### Transaction Information | **Field** | **Description** | **Required** | **Data Type** | | :- | :- | :- | :- | | settlement\_date | The updated settlement date of this transaction. | Required | date `YYYY-MM-DD` | | transfer\_id | The unique IDs for the related transfer object, if applicable (e.g. the ACH ID or Wire ID or Internal Transfer ID generated by Lead). | Required if `transfer_type` = `ach` `wire` `internal_transfer` at Lead | string | ### Other | **Field** | **Description** | **Required** | **Data Type** | | :- | :- | :- | :- | | generated\_at | The day this file is generated. This should always be the date the file is sent to Lead Bank. | Required | datetime [ISO8601](https://www.iso.org/iso-8601-date-and-time-format.html) | | effective\_at | The timestamp of when the related object(s) were polled to collect the information for this record. | Required | datetime [ISO8601](https://www.iso.org/iso-8601-date-and-time-format.html) | ## Transaction Type > [!WARNING] > > Since the timing of certain transaction and transfer types are more deterministic than others, only the below combinations of transaction and transfer types should be included in this file. Any other combinations not listed below are not permitted or supported. | **Transaction Type** | **Transfer Type** | | - | - | | debit | `ach`, `wire`, `check`, `internal_transfer`, `external_transfer`, `out_of_bank_settlement` | | credit | `ach`, `wire`, `check`, `internal_transfer`, `external_transfer`, `out_of_bank_settlement` | | dispute\_provisional | `internal_transfer`, `external_transfer`, `out_of_bank_settlement` | | dispute\_lost | All available transfer types | | escheatment | `ach`, `wire`, `check`, `internal_transfer`, `external_transfer`, `out_of_bank_settlement` | | charge\_off\_recovery | All available transfer types | | rewards\_redeemed | All available transfer types | | fee (overdraft) | All available transfer types | | fee (periodic maintenance) | All available transfer types | | fee (card) | All available transfer types | | fee (international transaction) | All available transfer types | | fee (other) | All available transfer types | | interest\_paid | All available transfer types | | adjustment | All available transfer types | # Balances & Transactions Files Troubleshooting Source: https://docs.lead.bank/file-reference/balances-and-transactions/troubleshooting Symptom-first guide to the most common Balance and Transaction file rejections — reconciliation breaks, missing balances, type-specific amount rules, and cadence failures — and how to fix and resubmit. When a Balance or Transaction file fails validation, the 🔴 [Slack alert](/file-reference/delivery/slack-alerts) names the error code, the failing detail, and the action to take. This page covers the most common failures symptom-first; the complete catalog is [File Submission Validation Errors](/file-reference/delivery/errors). **The universal recovery loop:** fix the flagged records, upload a new version of the corrected file (same batch), and Lead re-validates the latest version of each file in the batch. Resubmit before the next cycle where possible so one bad day doesn't cascade into the next day's T−1 checks. > [!NOTE] > > **Error code renames effective August 4, 2026.** Several balance-related codes dropped the legacy `account_balance` term (e.g., `transaction_missing_account_balance` → `transaction_missing_balance`; `balance_cannot_be_closed_with_processing_funding` → `balance_cannot_be_terminal_with_processing_funding`). If your automation keys off code strings, use the new codes — the [changelog entry](/changelog) has the full mapping. > [accordion] Balance mismatch: reported balance doesn't equal its components or yesterday-plus-activity > > **Symptom:** errors like `unexpected_balance`, `unexpected_past_due_balance`, `unexpected_dispute_balance`, or `unexpected_charge_off_balance`. The alert detail shows the expected sum, your submitted value, the delta, and the Sample ID of a failing record — e.g., *`balance` (316125.78) was expected to be 316124.78 (delta: 1.00), the sum of `outstanding_principal`, `outstanding_interest`, and `outstanding_fee`.* > > **Likely causes:** a component field out of sync with the total (rounding, a fee booked to the wrong bucket); or the day's transactions don't account for the balance movement, breaking the invariant **balance(T) = balance(T−1) + T's transactions**. > > **How to confirm:** pull the Sample ID's record from your file, recompute the named components, then recompute the invariant against yesterday's submitted balance and today's transactions for that `balance_id`. > > **Fix:** correct the component or add the missing transaction, resubmit the file version. Prevention: assert both identities in your pipeline before submission ([Balance Reconciliation](/products/balances-and-transactions/balance-reconciliation)). > [accordion] Transaction references a balance that doesn't exist > > **Symptom:** `transaction_missing_balance` / `transaction_missing_card_balance` (pre-Aug-4: `…_account_balance`), or — for card programs — `previous_active_card_balance_missing`. > > **Likely causes:** the transaction's `balance_id` was never established in a Balance file (or, for credit, never created via the Subledger Balance API); files arrived out of order so the transaction landed before its balance; or a card balance active yesterday is absent from today's file. > > **How to confirm:** search your Balance submissions for the `balance_id`; check whether today's Balance file includes every balance that was active on T−1. > > **Fix:** establish or re-include the balance, then resubmit the transaction file. Balances don't disappear when quiet — an active balance is reported every day until you transition it per [Balance Statuses](/products/balances-and-transactions/balance-statuses). > [accordion] Balance references an account that doesn't validate > > **Symptom:** account-linkage validation failure on new Balance creation. > > **Cause:** every Balance must reference a valid parent [Account](/products/accounts/overview); enforcement begins **October 6, 2026** ([Upcoming Changes](/upcoming-changes#account-validation-during-new-balance-creation)). > > **How to confirm:** `GET /v0/accounts/{id}` for the referenced `account_id` — it must exist and its capabilities must permit the balance type (`deposit` capability for deposit balances; a credit capability for credit balances). > > **Fix:** create the account first (Entity → \[Application →] Account), or correct the `account_id` in your file generation, before the balance is submitted. Review your workflows ahead of October 6. > [accordion] Transaction type and amounts disagree > > **Symptom:** `transaction_activity_check` / `transaction_type_invalid_activity_check`. > > **Cause:** each transaction `type` constrains which amount fields may be non-zero: **`disbursement`** — `principal_amount` > 0; `interest_amount` and `fee_amount` = 0 · **`interest_accrued`** — `interest_amount` > 0; others = 0 · **`fee`** — `fee_amount` > 0; others = 0. > > **Fix:** split composite entries into one transaction per type rather than packing principal, interest, and fees into one record. Valid type/action/transfer-type combinations: [Transaction Types](/products/balances-and-transactions/transaction-types). > [accordion] Disbursement fee doesn't match the Funding > > **Symptom:** `funding_fee_amount_mismatch` on a disbursement transaction. > > **Cause:** when a transaction has `type: disbursement`, `transfer_type: internal_transfer`, and a populated `funding_id`, its `fee_amount` must equal `other_fees.borrower_origination_fee_amount` on that Funding. > > **How to confirm:** `GET /v0/fundings/{funding_id}` and compare. > > **Fix:** correct whichever side is wrong — usually the file; the Funding's fee was fixed at creation ([The Funding Object](/products/lending/funding-object)). > [accordion] Balance closed while a Funding is still processing > > **Symptom:** `balance_cannot_be_terminal_with_processing_funding`. > > **Cause:** you reported a balance into a terminal status (`closed`, or `receivable_transferred`) while a Funding against it is still `processing`. > > **Fix:** wait for the Funding to reach `posted` or `rejected` (the `funding.posted` webhook, or [Simulate Advance Funding](/api-reference/endpoint/funding/advance-a-funding) in sandbox), then report the terminal status. > [accordion] No alert at all / file seemingly ignored > > **Symptom:** no 🟢 or 🔴 for a submission. > > **Likely causes:** file delivered after the **6:00 a.m. CT** cutoff, so it missed the day's cycle; wrong SFTP path (alerts now include the full file path — check it matches the expected folder); or a filename outside the convention (epoch-timestamp generation time or `v1`/`v2` version suffix — [SFTP setup](/file-reference/sftp-setup)). > > **Fix:** correct path/naming and resubmit; if the cutoff was missed, coordinate with your Lead team on whether the file can join today's cycle or must roll. Remember empty days still require an empty file. Still stuck? Escalate in your Slack channel with the full file path from the alert, the error code, and the Sample ID — that trio lets Lead locate the exact record immediately. # Card File Schema Source: https://docs.lead.bank/file-reference/card/schema Field-level reference for the Cards file reporting issued cards to Lead. > [!WARNING] > > **Legacy schema — superseded by the Cards API.** New programs integrate via the [Cards API](/products/cards/overview). This schema remains the supported path for file-integrated programs that have not yet migrated. > [!WARNING] > > **Upcoming Change** > > We're introducing support for multiple card products under a single program, including programs with different funds flows and settlement requirements. Partners adopting this functionality will need to update network settlement file processing and transaction file generation before September 30, 2026. > > 👉 [View Details](/changelog#multi-card-program-file-updates) > [!NOTE] > > This file provides information on all issued cards. > [!TIP] > > Card files should include all newly created cards and any cards that have been updated. > > For all optional fields where you do not plan to pass through data, please include the header and an empty value. ## IDs | **Field** | **Description** | **Required** | **Data Type** | | - | - | - | - | | client\_card\_id | Unique ID of the card issued. Cannot start with `card_` (reserved for Lead-generated card IDs). | Required | string | | account\_id | Unique ID of an account created through the [Account](/file-reference/account/schema) file. | Required | string | | entity\_id | Unique ID of a customer created through the [Customer](/file-reference/customer/customer-schema) file or an entity created through the [Entity API](/api-reference/endpoint/entity/create-an-entity). | Required | string | | client\_card\_product\_name | The name of the card product in the partner's system. | Required | string | ## Card Metadata | **Field** | **Description** | **Required** | **Data Type** | | :- | :- | :- | :- | | is\_virtual | True if the card is a virtual card; false if physical. | Required | boolean | | card\_type | enum `hsa` `fsa` `consumer` `commercial` | Required | enum | ## Status and timing | **Field** | **Description** | **Required** | **Data Type** | | :- | :- | :- | :- | | created\_at | Datetime the card was created. | Required | datetime ISO8601 | | card\_status | enum `active` `closed` `inactive` `expired` A closed Card cannot be re-opened and Lead's system will reject any additional changes or activity reported once it is in a `closed` status. If there is a chance that activity may still occur on the Card, use the `inactive` status until it is confirmed that no further activity will occur. | Required | enum | | activated\_at | Datetime the card was activated and able to charge transactions. Must be >= to created\_at and \< expiry\_date, if expiry\_date is present | Required | datetime ISO8601 | | expiry\_date | Date the card expires. | Required | date `YYYY-MM-DD` | | closed\_at | Datetime the card was closed. Must be >= to created\_at | Required if card\_status = closed | datetime ISO8601 | | closed\_reason | The reason for closing the card. | Required if card\_status = closed | string | | replaced\_by | The card ID that replaced this card if expired, lost, or canceled. | Optional | string | ## Other | **Field** | **Description** | **Required** | **Data Type** | | :- | :- | :- | :- | | generated\_at | The day this file is generated. This should always be the date the file is sent to Lead Bank. | Required | datetime ISO8601 | | effective\_at | The timestamp of when the related object(s) were polled to collect the information for this record. | Required | datetime ISO8601 | # Card File Validations Source: https://docs.lead.bank/file-reference/card/validations Validating card files. > [!WARNING] > > **Legacy schema — superseded by the Cards API.** New programs integrate via the [Cards API](/products/cards/overview). This schema remains the supported path for file-integrated programs that have not yet migrated. > [!NOTE] > > Beyond the standard required and optional field checks and data type validations, Lead performs additional validations. ## Enforced Today | **Validation** | **Description** | | - | - | | Missing closure details | `closed_at` and `closed_reason` must be provided for closed accounts | | Invalid Expiration | `expiry_date` may not be before `activated_at` or `created_at` | | Invalid Account Reference | `account_id` must match an account within our system that was previously submitted via Accounts Daily file | | Invalid Entity Reference | `entity_id` must match a `client_customer_id` or `entity_id` within our system | | Disallowed Entity Reference | `entity_id` must match an `account_holder` or `authorized_user` on the linked account. | | Invalid Card Reference | `replaced_by` must match a `client_card_id` within our system (or within the same file) | | Nonterminating Update to Card on Closed Account | Updates to existing cards must include a “closed” or “expired” card status if the account is closed. | ## Future Enforcements > [!WARNING] > > Lead expects partners to comply with the below validations; however we do not currently enforce them upon daily processing. We will provide you with 60 days notice before enforcing the following validations. | **Validation** | **Description** | | - | - | | Invalid Namespace | client\_card\_id may not start with the characters `card_` | | Card with ReplacedBy must be in terminal state | If a card has been replaced, it must not still be active. | | Updates not allowed on Immutable Fields | `account_id`, `entity_id`, `is_virtual`, `card_type`, `created_at`, `activated_at`, `expiry_date`, `closed_at`, `closed_reason`, `replaced_by` | | Card Creation on Closed Account Not Permitted | New cards may not be created when the linked `account_id` has a status of `closed` | # Collateral File Schema Source: https://docs.lead.bank/file-reference/collateral/schema Field-level reference for the Collaterals file used by secured credit programs, including the deposit-collateral balance requirement. > [!NOTE] > > **File-era companion schema.** This file accompanies the legacy file-based workflows above and remains the active path for programs that use it — it has no API successor yet. Use the Collaterals object to describe the relationship between a collateral asset and the secured account (e.g., a secured card account) it supports. Lead uses this information to maintain visibility into how collateral secures each product. > [!NOTE] > > You must submit a collateral file every day. Each file only needs to include new collaterals to create or existing collaterals to update. On days with no new collaterals or updates, submit a file containing only the header row. You must submit a collateral update whenever any field changes (e.g., a change in `value_usd`). > [!TIP] > > For all optional fields where you do not plan to pass through data, include the header and an empty value. ## IDs | **Field** | **Description** | **Required** | **Data Type** | | - | - | - | - | | client\_collateral\_id | A unique identifier for the collateral object. This ID represents the relationship between the collateral asset and the credit product it secures — not the underlying asset itself. A single asset can secure multiple credit products (e.g., a single home securing both a mortgage and a HELOC); in this case, you must create a unique `client_collateral_id` for each asset-to-credit-product relationship. | Required | string | | account\_id | The ID of the account holding the credit balance this collateral secures. Must exist and must not be in a `closed` status at creation. | Required | string | | balance\_id | The ID of the deposit balance pledged as collateral. The Balance must be of `type` deposit, must belong to the same `account_id`, must not be in a `closed` status at creation, and at most one active collateral may exist per `balance_id`. | Required if `type` = `deposit_balance` | string | ## Details | **Field** | **Description** | **Required** | **Data Type** | | :- | :- | :- | :- | | type | The type of asset securing the credit product. Immutable after creation. `deposit_balance`: Fiat currency held at a financial institution. `real_estate`: Any permanent structure or fixture attached to land that you cannot move without causing damage (e.g., single-family homes, apartments, commercial buildings). | Required | enum `deposit_balance` `real_estate` | | value\_usd | The value of the collateral in USD. Must be >= 0 with exactly 2 decimal places. When `type` = `deposit_balance`, the Balance Object captures the collateral value via `balance.amount`. | Required if `balance_id` is not present; must be empty if `balance_id` is present | number decimal (M,2) | | status | The current status of the collateral. `active`: The collateral object and the asset it represents actively secure the credit product. `closed`: The collateral no longer secures the credit product, typically due to account or balance closure. | Required | enum `active` `closed` | ## Address > [!NOTE] > > Address fields apply only to collateral of type `real_estate`. | **Field** | **Description** | **Required** | **Data Type** | | :- | :- | :- | :- | | address\_line\_1 | Address line 1 of the real property. | Required if `type` = `real_estate` | string | | address\_line\_2 | Address line 2 of the real property. | Optional; must be empty if `type` != `real_estate` | string | | address\_city | City of the real property. | Required if `type` = `real_estate` | string | | address\_postal\_code | Postal code of the real property (US format). | Required if `type` = `real_estate` and `address_country` = `us` | string | | address\_state | US state or territory (2-letter code). | Required if `type` = `real_estate` and `address_country` = `us` | string | | address\_country | ISO 3166-1 alpha-2 country code. | Required if `type` = `real_estate` | string | ## Other | **Field** | **Description** | **Required** | **Data Type** | | :- | :- | :- | :- | | generated\_at | The day you generate this file. Always use the date you send the file to Lead Bank. | Required | datetime ISO8601 | | effective\_at | The timestamp of when you polled the related objects to collect the information for this record. Must be T-1 of the file date. | Required | datetime ISO8601 | ## Requirements for `type` = `deposit_balance` > [!WARNING] > > * The `balance_id` must reference a deposit balance that belongs to the same `account_id` specified in this record. > * The deposit balance referenced by `balance_id` must contain only funds designated as collateral. Do not hold any funds that are not serving as collateral in this balance. Report those funds under a separate deposit balance. # Customer Relationship Schema Source: https://docs.lead.bank/file-reference/customer/customer-relationship-schema Field-level reference for the Customer Relationships file linking individuals to businesses as owners, control persons, signers, and users. This schema connects the relationship between individuals and businesses or sole proprietors. > [!WARNING] > > **Legacy schema — superseded by the Entity API.** New programs integrate via [the Entity API](/products/entity/overview). This schema remains the supported path for file-integrated programs that have not yet migrated. > [!WARNING] > > All programs that submit Customer files are required to submit this file daily. Refer to [Customer Files overview](/file-reference/customer/overview) for more details. If you do not onboard commercial customers (or are not onboarding them within a particular batch), simply submit a "headers-only" file conforming to this schema. > [!TIP] > > Submit an empty file if there are no changes. | **Field** | **Description** | **Required** | **Data Type** | | - | - | - | - | | client\_individual\_id | The individual you want to link to the business or sole prop customer. This should be `client_customer_id` of `customer_type` =`individual` from Customer file. All individuals being linked to the business or sole prop customers must meet data requirements of `authorized_signer`. See [Data Requirements for Intended Roles](/products/entity/roles) for more details. | Required | string If `customer_type` = `business`, we require all `control_person` and all applicable `beneficial_owners` under `client_individual_id`. At least one control person is required. If `customer_type` = `sole_prop`, we require one `sole_proprietor` under `client_individual_id`. | | client\_business\_id | The `business` customer you are linking individuals to. This should be `client_customer_id` of `customer_type` = `business` from Customer file. All sole prop customers must meet data requirements of `account_holder`. See [Data Requirements for Intended Roles](/products/entity/roles) for more details. | One of `client_business_id` or `client_sole_prop_id` is required | string | | client\_sole\_prop\_id | The `sole_prop` customer you are linking individuals to. This should be `client_customer_id` of `customer_type` = `sole_prop` from Customer file. All sole prop customers must meet data requirements of `account_holder` | One of `client_business_id` or `client_sole_prop_id` is required | string | | status | Status of associated beneficial owner/control person for business or sole proprietor of sole prop. This is used in the case there are individual relationships added or removed to businesses or sole proprietorships. Possible values are `active` or `deleted.` | Required if `customer_type` = `business`, `sole_prop` | enum `active` `deleted` | | relationship\_type | Possible values are `beneficial_owner`, `control_person`, `sole_proprietor` | Required if `customer_type` = `business`, `sole_prop` | enum: `beneficial_owner` `control_person` `sole_proprietor` | | relationship\_established\_at | The date the relationship was established. Applicable for beneficial owners and control persons. | Optional | date YYYY-MM-DD | | ownership\_percentage | Percentage ownership. Applicable for beneficial owners only sum of all beneficial ownership percentage should be 100 or below. | Optional | number decimal(M, 2) | | title | Title of the Control Person. (e.g., CEO, Owner) | Required if relationship\_type = `control_person` | string | | generated\_at | The day this file is generated. This should always be the date the file is sent to Lead Bank. | Required | datetime ISO8601 | | effective\_at | The timestamp of when the related object(s) were polled to collect the information for this record. | Required | datetime ISO8601 | # Customer File Schema Source: https://docs.lead.bank/file-reference/customer/customer-schema Field-level reference for the Customer file, including individual and business customer identification, tax IDs, addresses, and KYC requirements. > [!WARNING] > > **Legacy schema — superseded by the Entity API.** New programs integrate via [the Entity API](/products/entity/overview). This schema remains the supported path for file-integrated programs that have not yet migrated. > [!WARNING] > > Complete Customer Files are required to be sent for all customers on creation as well as on update. Partial updates are not supported. Please do not submit "no-op" changes to customers. > [!TIP] > > For optional fields where you do not plan to pass through data, please include the header and an empty value. | Field | Description | Required | Data Type | | - | - | - | - | | client\_customer\_id | The unique ID for this customer in your system. Limit of 64 characters. | Required | string | | customer\_type | Type of customer. | Required | enum: `individual` `business` `sole_prop` | | intended\_roles | Intended role(s) of the customer. These can be used to synchronously validate eligibility of customers for specific roles. Refer to [Data Requirements for Intended Roles](/products/entity/roles) for more details. | Optional | array of enum: `authorized_user` `authorized_signer` `account_holder` For customer\_type = individual, all of `authorized_user`, `authorized_signer`, `account_holder` allowed For customer\_type = sole\_prop, only `account_holder` is allowed. For customer\_type = business, only `account_holder` is allowed. | | first\_name | Legal first name. | Required if `customer_type` = `individual` | string | | preferred\_first\_name | Preferred first name. | Optional | string | | middle\_name | Middle name. | Optional | string | | last\_name | Legal last name. Must be at least 2 alphanumeric characters. | Required if `customer_type` = `individual` | string | | date\_of\_birth | Date of birth. | Optional | date `YYYY-MM-DD` | | occupation | Occupation or job. | Optional | string | | business\_type | Business types based on `customer_types` | Required if `customer_type` = `business`, `sole_prop` | enum: `corporation` `partnership` `sole_prop` `llc` `trust` `cooperative` `otherindividual` = N/A `business` = `corporation`, `partnership`, `sole_prop`, `llc`, `trust`, `cooperative`, `other` `sole_prop` = `sole_prop` | | business\_name | Legal name of the business. Must be at least 2 characters. | Required if `customer_type` = `business`, `sole_prop` | string | | doing\_business\_as | Business name if the business operates under a different name. | Optional | string | | website | The website of the business. | Optional | url: `http:// ` `https://` | | business\_gross \_annual\_revenue | Business gross revenue for prior fiscal year. | Optional | decimal(M, 2) | | business\_gross \_annual\_revenue\_currency | A three-letter currency code as defined in ISO 4217. | Optional | ISO 4217 | | industry | [NAICS codes](https://www.census.gov/naics/?58967?yearbck=2022) for the applicable industries. 2-6 digits of NAICS codes are accepted. | Required if `customer_type` = `business`, `sole_prop` | array of enum \[11, 111140] | | email | Primary email address of the customer. | ONE of `email` or `phone_number` is required | string | | phone\_number | Primary phone number of the customer. | ONE of `email` or `phone_number` is required | [E.123](https://en.wikipedia.org/wiki/E.123) phone number format. Example for US: `+1 123 456 7890` | | physical\_address \_line\_1 | Address line 1. Physical addresses must not be P.O. boxes, registered agent addresses or in prohibited countries. | Required if any of the `physical_address` fields are present | string | | physical\_address \_line\_2 | Address line 2. | Optional | string | | physical\_address \_city | City. | Required if any of the `physical_address` fields are present | string | | physical\_address \_postal\_code | Postal Code, required for US addresses. | Required if `physical_address_country` = `us` | string Follow this format: US: ^\d5(?:-\d4)?\$ CN: ^\d6\$, GB: ^\[A-Z]2d\[A-Z0-9]? ?d\[A-Z]2\$ JP: ^\d3-\d4\$ | | physical\_address \_state | State. | Required if `physical_address_country` = `us` | string: 2-letter state code | | physical\_address \_country | ISO3166-1 Alpha-2 country code. | Required if any of the `physical_address` fields are present | string: ISO 3166-1-alpha-2 | | mailing\_address \_line\_1 | Address line 1. | Required if any of the `mailing_address` fields are present | string | | mailing\_address \_line\_2 | Address line 2. | Optional. | string | | mailing\_address \_city | City. | Required if any of the `mailing_address` fields are present | string | | mailing\_address \_postal\_code | Postal Code, required for US addresses. | Required if `mailing_address_country` = `us` | string Follow this format: US: ^\d5(?:-\d4)?\$ CN: ^\d6\$, GB: ^\[A-Z]2d\[A-Z0-9]? ?d\[A-Z]2\$ JP: ^\d3-\d4\$ | | mailing\_address \_state | State. | Required if `mailing_address_country` = `us` | string: 2-letter state code | | mailing\_address \_country | ISO3166-1 Alpha-2 country code. | Required if any of the `mailing_address` fields are present | string: ISO 3166-1-alpha-2 | | other\_addresses | Other addresses for the customer. | Optional. | "line\_1": "string" (required) "line\_2": "string" (optional) "city": "string" (required) "postal\_code": "string" (required if country = us) "state": "string; 2 character code" (required if country= us) "country": "string; ISO3166-1 Alpha-2 country code" (required) | | is\_us\_entity | Customer is considered US entity if they have US tax identification. **For US Entities:** Full KYC, the US tax identification number, and other available government-verified identification documents are required for the Account Holder and Authorized Signer roles (and for beneficial owners, control persons, and sole proprietors). They are not required for a customer who will only be an Authorized User. **For non-US Entities:** Government-verified identification documents are required for the same roles. Submit only the customer's own tax identification, never another person's. | Required | boolean | | us\_tax\_id\_type | The entity's US tax identification type. | Required if any of the `us_tax_id` fields are present | enum: `ssn` `ein` `itin` If customer\_type = individual, use SSN or ITIN. If customer\_type = business, use EIN. If customer\_type = sole\_prop, use SSN, EIN, or ITIN. | | us\_tax\_id\_value | The customer's US tax identification number. Must be 9 digits (e.g. XXXXXXXXX). `ssn` must not start with a 9. `ein` must begin with a number between 00 and 99. `itin` must begin with a 9 | Required if any of the `us_tax_id` fields are present | string | | identification\_documents | **For US Entities** Available government-verified identification documents are required. **For non-US Entities** Government-verified identification documents are required. `client_document_id`: The partner's document ID for the identification document. `type`: Customer's government-verified identification document type. This will apply for identification types other than US tax identification. `description`: Description about the identification document. Required if identification document type is other. `identification_number`: Unique identification number on the identification document. `expiration_date`: Expiration date of the identification document. `issuing_state`: Issuing state of the identification document. Must be 2 character code (e.g. NY). `issuing_country`: Issuing country of the identification document. ISO3166-1 Alpha-2 country code. | Optional | **identification\_documents:** "client\\\_document\\\_id": "string" (optional) "type": "enum" (required) "description": "string" (required if type = other) "identification\\\_number": "string" (required) "expiration\\\_date": "datetime" (optional) "issuing\\\_state": "string" (optional) "issuing\\\_country": "string" (required) Possible `type` for different customers are the following: For `individual` customer, possible `type` are: `drivers_license` `state_or_provincial_id` `passport` `permanent_residency_id` `military_id` `national_id` `matriculate_id` `other` Note that `national_id` and `matriculate_id` are not applicable for us\_entity. For `business` customer, possible `type` are: `tax_certificate` `tax_returns` `partnership_agreement` `certificate_of_good_standing` `formation_document` `proof_of_place_on_stock_exchange` `other` For `sole_prop` customer, possible `type` are: `tax_certificate` `tax_returns` `name_certificate` `drivers_license` `state_or_provincial_id` `passport` `permanent_residency_id` `military_id` `national_id` `matriculate_id` `other` Note that `national_id` and `matriculate_id` are not applicable for us\_entity. **Suggested Document Naming Format:** \*\*\\_\.\ | | additional\_documents | Additional non-government documents being provided to verify customer. `client_document_id:` The partner's document ID for the identification document. This should be the full file name of the document delivered in the SFTP directory. `type`: Customer's type of additional documents (non identification document) for customer verification. `description`: Description about the identification document. Required if additional document type is other. | Optional | **additional\_documents:** "client\_document\_id": "string" (optional) "type": "enum" (required) "description": "string" (required if document\_type = other) Possible values for `type` are: `bank_statement` `utility_bills` `proof_of_address` `investigation_report` `financial_statement` `public_records` `adverse_media` `id_selfie` `other` **Suggested Document Naming Format:** \*\*\\_\.\ | | risk\_score | The customer's risk score, mapped to Lead by the partner. The partner must provide the risk score mapping to Lead during setup. | Optional | enum: `low` `medium` `high` | | rfi\_result | Result of request for information with the end customer. Leave blank if RFI has not been sent to the customer. | Required if any of the RFI fields are present | enum: `requested` `completed` | | rfi\_requested\_at | Date time RFI is requested at. | Required if any of the RFI fields are present | datetime ISO8601 | | ofac\_result | OFAC result. | Required if any of the ofac fields are present | enum `pending` `passed` `failed` | | ofac\_screened\_at | Date time OFAC screen is screened at. | Required if any of the ofac fields are present | datetime ISO8601 | | kyc\_result | KYC result. | Required if any of the kyc fields are present | enum `pending` `passed` `failed` | | kyc\_screened\_at | Datetime KYC screen is performed. | Required if any of the kyc fields are present | datetime ISO8601 | | credit\_pulled\_at | Date time credit is pulled at. | Required if any of the credit fields are present | datetime ISO8601 | | credit\_score | Credit score given by the credit bureau. Cannot be above 850. Mutually exclusive with `credit_report_non_score_value`. | Required if any of the credit fields are present and `credit_report_non_score_value` is not provided | number integer | | credit\_report\_non\_score\_value | Indicates the state of a credit file when a numeric score is not available. Mutually exclusive with `credit_score`. | Required if any of the credit fields are present and `credit_score` is not provided | enum `unestablished` `frozen` | | credit\_report\_source | The name of the credit bureau. | Required if any of the credit fields are present | enum `equifax` `experian` `transunion` | | generated\_at | The day this file is generated. This should always be the date the file is sent to Lead Bank. | Required | datetime ISO8601 | | effective\_at | The timestamp of when the related object(s) were polled to collect the information for this record. | Required | datetime ISO8601 | # Customer files: reporting customers via SFTP Source: https://docs.lead.bank/file-reference/customer/overview Overview of Customers and Customer Relationships files. > [!WARNING] > > **Legacy schema — superseded by the Entity API.** New programs integrate via [the Entity API](/products/entity/overview). This schema remains the supported path for file-integrated programs that have not yet migrated. ## Introduction A **Customer** record in Lead's platform represents a legal entity or organization and defines its rights and roles related to our products. You must create a Customer record for each of your end users in order to provision Lending, Depository, and Card products or to generate account numbers. > [!TIP] > > Each day, submit a Customer file containing all new customer records created the previous day, along with any updates to existing records. Do not include records that have not changed. ## Customer Types * **Individual**: For individual persons. * **Business**: For businesses (excluding sole proprietorships). Requires details on beneficial owners and control persons. * **Sole Proprietorship**: For sole proprietorships. Exempt from beneficial ownership requirements. ### **Example** Customer data requirements vary by the customer's role in relation to Lead products. For example, consider Pete’s Pizza. Pete’s Pizza is an LLC business owned by Pete, a control person, and his wife Amanda, a beneficial owner. Pete’s sister, Sam, is an authorized signer on the business checking account and Daisy, Pete’s employee, is an authorized debit card user with restricted access on the business account. | **Entity** | **Role** | **Created As** | | - | - | - | | Pete (owner of Pete's Pizza LLC) | control person | An **individual customer** with full KYC details: name, date of birth, contact info, physical address, and government verified ID. | | Amanda (Pete's wife) | beneficial owner | An **individual customer** with full KYC details. | | Pete's Pizza | - | A **business customer** with full KYB, your risk assessment on the business, and Pete and Amanda listed as the control person and beneficial owner. | | Sam (Pete's sister) | authorized signer | An **individual customer** with full KYC details and later associated with the business checking account. | | Daisy (employee) | authorized user | An **individual customer** with partial KYC details (name and contact info). | ## Customer Type Examples ### Individual Customers For end customers who are individuals: 1. **Create individual customers** (`customer_type` = `individual`) for the intended roles of `authorized_user`, `authorized_signer`, and/or `account_holder`. * Typically, the individual is the account holder. * Use `authorized_user` or `authorized_signer` roles when the person is not the legal account holder but requires limited access. ### Business Customers For businesses (excluding sole proprietorships), we expect at least one control person and all beneficial owners. 1. **Create individual customers** (`customer_type` = `individual`) for beneficial owners and control persons. * Data requirements for beneficial owners/control persons match those of `authorized_signer` roles. 2. **Create business customers** (`customer_type` = `business`) as `account_holder`s. > [!WARNING] > > **Steps 1 and 2 can be created in any order**\ > On the same day, 1 before 2, 2 before 1 on the same day, or on different days. However, the business customer won't validate until the association is made in step 3. 3. **Associate the relationship of individual customers (from step 1) to business customers (step 2)** under 'Customer Relationship.' #### **Beneficial Ownership Requirements** Lead requires customers to send Beneficial Ownership information that is in line with the CIP program reviewed by Lead Bank during Due Diligence. At a minimum, this should include all Beneficial Owners with ownership percentages 25% or greater. **If your KYB process expressly states a lower percent than 25%** then all beneficial owners who meet your expressly stated percentage must be required. > [!WARNING] > > All Beneficial Owners must reduce to an individual. If a beneficial owner is a Business Entity, then the same requirement applies to the beneficial owners of that Business Entity. **Example** * Create Alan (beneficial owner), Bob (control person), and Charlie (authorized user) as individual customers (`intended_roles` = `authorized_signer`). * Create Bob’s Pizza Company as a business customer (`intended_roles` = `account_holder`). * Assign Alan and Bob's `client_customer_id` to Bob's Pizza Company business `client_customer_id` via 'customer relationship'. * Charlie, as an authorized user, does not need to be linked to the business customer. ### **Sole Proprietorship Customers** For sole proprietorships (exempt from beneficial ownership requirements): 1. **Create individual customers** (`customer_type` = individual) for sole proprietors. * Data requirements for sole proprietors match those of `authorized_signer` roles. 2. **Create a sole prop customer** (`customer_type` = `sole_prop`) as the `account_holder`. > [!WARNING] > > **Steps 1 and 2 can be created in any order** On the same day, 1 before 2, 2 before 1 on the same day, or on different days. However, the sole prop customer won't validate until the association is made in step 3. 3. **Associate the relationship of individual customers (from step 1) to sole prop customer (step 2)** under 'customer relationship.' **Example** * Create Daniel as an individual customer (`intended_roles` = `authorized_signer`). * Create Daniel's Dry Cleaning as a sole\_prop customer (`intended_role` = `account_holder`). * Assign Daniel's `client_customer_id` to his Dry Cleaning business `client_customer_id` via 'customer\_relationship.' ## **Customer Roles** Customer roles indicate requirements for when a customer record will be provisioned a financial product by Lead with the Account Holder, Authorized Signer, or Authorized User roles. > [!TIP] > > Customer roles follow the same pattern and hold the same data requirements as [Entity Roles](/products/entity/roles). # Customer File Validations Source: https://docs.lead.bank/file-reference/customer/validations Validating customer and customer relationship files ## Customer File Requirements > [!WARNING] > > **Legacy schema — superseded by the Entity API.** New programs integrate via [the Entity API](/products/entity/overview). This schema remains the supported path for file-integrated programs that have not yet migrated. > [!TIP] > > Required for all customer types. > > * `Individual` > * `Business` > * `Sole Prop` If submitting `Customer` and / or `Customer Relationship` files multiple times a day, files should use batch-id. The batch ID needs to be a unique string in order for multiple file submissions to go through. If not planning on using multiple submissions per day, you may just use date as the batch ID. BatchID is used to group the `Customer` and `Customer Relationship` files together for each upload. ### Batch ID Naming Convention `__.` ### Examples * `2025-12-31-01-Batch-1_customer_V1.csv` * `2025-12-31-01-batch-1_beneficial_owner_V1.csv` ### Updating Existing Files Lead replaces the existing list with the new list provided. Files exhibit a PUT behavior so please provide the entire record. ## Additional Requirements > [!TIP] > > Only required for: > > * `Business` > * `Sole Prop` If customer\_type = `business` or `sole_prop` is supported in your program, please always provide both `Customer` and `Customer Relationship` files, even during the days with no entries. The two files work as a pair for Lead to perform validations. When creating customer\_type = `business` or `sole_prop`, at the time of `Customer Relationship` creation, Lead will check for the following: * If customer\_type = `business`, * `client_individual_id` and `client_business_id` must exist in `Customer` data submission up until `Customer Relationship` submission. If `client_individual_id` or `client_business_id` are not found in our record, we will raise an error. > [!TIP] > > Lead expects at least one control person and all available beneficial owners. * If customer\_type = `sole_prop`, * `client_individual_id` and `client_sole_prop_id` must exist in `Customer` data submission up until `Customer Relationship` submission. If `client_individual_id` or `client_sole_prop_id` are not found in our record, we will raise an error. > [!TIP] > > Lead expects one sole proprietor. ## Error Handling 1. You will get a success message via [Slack](/file-reference/delivery/slack-alerts) if the batch of files work with the list of files. 2. Upon invalid file upload you will see the error messages in your Slack alert channel 3. You can fix the batch by updating the version of the file that needed to be fixed and upload it again. Lead will kick off validation for the latest version of each file in the batch. # Currencies Source: https://docs.lead.bank/file-reference/delivery/currencies Understand which currencies are accepted in file validations. Lead accepts the following currencies in file validations and follows the [ISO4217 standard](https://www.iso.org/iso-4217-currency-codes.html). | **ISO4217 Currency Code** | **Number of Decimals** | | - | - | | AED | 2 | | AFN | 2 | | ALL | 2 | | AMD | 2 | | AOA | 2 | | ARS | 2 | | AUD | 2 | | AWG | 2 | | AZN | 2 | | BAM | 2 | | BBD | 2 | | BDT | 2 | | BGN | 2 | | BHD | 3 | | BIF | 0 | | BMD | 2 | | BND | 2 | | BOB | 2 | | BRL | 2 | | BSD | 2 | | BTN | 2 | | BWP | 2 | | BYN | 2 | | BZD | 2 | | CAD | 2 | | CDF | 2 | | CHF | 2 | | CLP | 0 | | CNH | 2 | | CNY | 2 | | COP | 2 | | CRC | 2 | | CUC | 2 | | CUP | 2 | | CVE | 2 | | CZK | 2 | | DJF | 0 | | DKK | 2 | | DOP | 2 | | DZD | 2 | | EGP | 2 | | ERN | 2 | | ETB | 2 | | EUR | 2 | | FJD | 2 | | FKP | 2 | | GBP | 2 | | GEL | 2 | | GGP | 2 | | GHS | 2 | | GIP | 2 | | GMD | 2 | | GNF | 0 | | GTQ | 2 | | GYD | 2 | | HKD | 2 | | HNL | 2 | | HTG | 2 | | HUF | 2 | | IDR | 2 | | ILS | 2 | | IMP | 2 | | INR | 2 | | IQD | 3 | | IRR | 2 | | ISK | 0 | | JEP | 2 | | JMD | 2 | | JOD | 3 | | JPY | 0 | | KES | 2 | | KGS | 2 | | KHR | 2 | | KMF | 0 | | KPW | 2 | | KRW | 0 | | KWD | 3 | | KYD | 2 | | KZT | 2 | | LAK | 2 | | LBP | 2 | | LKR | 2 | | LRD | 2 | | LSL | 2 | | LYD | 3 | | MAD | 2 | | MDL | 2 | | MGA | 2 | | MKD | 2 | | MMK | 2 | | MNT | 2 | | MOP | 2 | | MRU | 2 | | MUR | 2 | | MVR | 2 | | MWK | 2 | | MXN | 2 | | MYR | 2 | | MZN | 2 | | NAD | 2 | | NGN | 2 | | NIO | 2 | | NOK | 2 | | NPR | 2 | | NZD | 2 | | OMR | 3 | | PAB | 2 | | PEN | 2 | | PGK | 2 | | PHP | 2 | | PKR | 2 | | PLN | 2 | | PYG | 0 | | QAR | 2 | | RON | 2 | | RSD | 2 | | RUB | 2 | | RWF | 0 | | SAR | 2 | | SBD | 2 | | SCR | 2 | | SDG | 2 | | SEK | 2 | | SGD | 2 | | SHP | 2 | | SLE | 2 | | SOS | 2 | | SRD | 2 | | SSP | 2 | | STD | 2 | | STN | 2 | | SVC | 2 | | SYP | 2 | | SZL | 2 | | THB | 2 | | TJS | 2 | | TMT | 2 | | TND | 3 | | TOP | 2 | | TRY | 2 | | TTD | 2 | | TWD | 2 | | TZS | 2 | | UAH | 2 | | UGX | 0 | | USD | 2 | | UYU | 2 | | UYW | 4 | | UZS | 2 | | VES | 2 | | VND | 0 | | VUV | 0 | | WST | 2 | | XAF | 0 | | XCD | 2 | | XCG | 2 | | XMW | 8 | | XOF | 0 | | XPF | 0 | | YER | 2 | | ZAR | 2 | | ZMW | 2 | | ZWG | 2 | # File Submission Validation Errors Source: https://docs.lead.bank/file-reference/delivery/errors Reference for Lead file validation errors, including field formatting, cross-file reconciliation, error groupings, and troubleshooting guidance. ## **Introduction** When submitting files to Lead, the system validates records across multiple layers — from field formatting to cross-file reconciliation — to ensure data integrity for regulatory reporting and moving funds between accounts. This page breaks down error types and messages so you can quickly identify, troubleshoot, and resolve issues. ## **Overview of File Validation Errors** The system performs validation in sequential groups. If a file fails in an earlier group, the system does not execute validations in later groups — so the absence of errors in a later group does not mean the file passed those validations. For example, if the balances file fails a validation in group two, group three validations do not run. > [accordion] 1. File Integrity > > | Category | Description | Scope | Examples | > | :- | :- | :- | :- | > | File Integrity | Checks ensuring that the file is formatted correctly and fields/records are unique | Within a specific file | Balance IDs must be unique; entire records cannot be duplicated | > [accordion] 2. Record Evaluation in the Same File > > > [!TIP] > > > > The system evaluates the three categories (Field Format, Business Rules, and Program Configuration) at the same time. The table below lists them separately as these are conceptually different types of validation checks. > > | Category | Description | Scope | Examples | > | :- | :- | :- | :- | > | Field Format | Single-field checks ensuring a value is well-formed before any business logic is applied | Single field within a record in a specific file | `card_transaction_effective_at` must be an ISO 8601 date; `amount_in_usd` must have a minimum of 2 decimal places; `account_holder_type` is either `consumer` or `commercial` | > | Business Rules | Rules evaluating the meaning or combination of fields within a single record | Multiple fields within a record in a specific file | `authorized_signers` is required if `account_holder_type` = `commercial` and must be a list of size >= 1; `balance` = `outstanding_principal` + `outstanding_interest` + `outstanding_fees` | > | Program Configuration | Rules verifying that records align with your program's configuration based on your product offerings | One record in a specific file against your program setup *(Reach out to your dedicated Technical Account Manager (TAM) to understand if these apply to you)* | `client_settlement_bank_account_id` must be an eligible enum | > [accordion] 3. Record Evaluation Across Files > > | Category | Description | Scope | Examples | > | :- | :- | :- | :- | > | Cross-File Reconciliation | Checks spanning multiple files across days and objects to ensure accurate data over time | Multiple files — can be the same or different objects for the same or different file dates | Balance on T = Balance on T-1 + Transaction activity on T; every non-closed account from T-1 must be reported in the balances file on T | ## **File Integrity** File Integrity checks run first and validate the structure and uniqueness of the file itself, before any field-level or business logic evaluation begins. The system applies the following checks: * **Duplicate Detection:** Identifies records where every field value in one record is identical to every field value in another record in the same file. * **Duplicate Primary Keys:** Validates that each record's primary key only appears once in the file. For example, in the Accounts schema, the primary key is `client_account_id`. * **Non-empty Files:** Validates that required files are not empty (e.g., network settlement files must have at least one record). * **Single Settlement Date:** All records in a network settlement file must share the identical settlement date. ### **Error Codes** | Error Code | Description | How to Resolve | | :- | :- | :- | | `balance_already_exists_for_date` | A balance record for this account already exists for this file date. Each account may only have one balance record per file date. | Remove the duplicate balance record. | | `csv_file_parse_failure` | The file could not be parsed as a valid CSV. This may be caused by malformed records, unescaped quotes, or incorrect delimiters. | Inspect the file for formatting issues such as unescaped pipe characters, unclosed quotes, or non-standard line endings. Ensure the file uses pipe (\|) delimited formatting. | | `empty_csv_files_with_no_headers` | The CSV file is empty or is missing a header record. | Add a valid header followed by at least one record. | | `empty_network_settlement_file` | The network settlement file contains no records. At least one record is required. | Add at least one valid settlement record. | | `invalid_metadata_json` | The metadata JSON in the file is malformed and cannot be parsed. | Verify the metadata JSON uses valid JSON syntax and conforms to the expected structure. | | `schema_mismatch` | The file columns or structure do not match the expected schema. A required column may be missing, misspelled, or in the wrong order. | Compare the file headers against the required schema for this file type. Ensure all required columns are present and correctly named. | | `settlement_date_error` | The settlement date in the file is invalid or does not match the expected value. | Verify the settlement date matches the file date and is correctly formatted as `YYYY-MM-DD`. | | `settlement_date_mismatch` | The `settlement_date` value in one or more records does not match the date in the filename. All records in a network settlement file must share the same settlement date, which must equal the file date. | Update all `settlement_date` values to match the date in the filename. | ## **Field Format** Field Format checks validate individual field values in isolation — confirming that each value is correctly entered, properly formatted, and within its allowed constraints before any business logic runs. The system applies the following checks: * **Data Type Checks:** Validates that the value meets the criteria for that specific data type (e.g. decimal fields should be a decimal, not a string). * **Format Checks:** Based on the field, additional validation checks for the semantic meaning of that value, such as ISO 8601 date/datetime formats, US ZIP codes, US state codes, ISO 3166 country codes, and [ISO 4217 currency codes](./currencies). * **Data Constraints:** Enforces required field presence, allowed value sets (enums), and maximum string lengths. * **Decimal Place Requirements:** Enforces that a decimal has a specific number of decimal places. Most commonly found with fields that represent currencies (e.g. if the balance is in USD, it has two decimal places). Some common variations are: * Interest/APR rate precision strictly enforced to 3 or 6 decimal places. * `amount_in_usd` must always have exactly 2 decimal places. * Minimum or maximum decimal bounds, including special-case decimals for accrued interest. ### **Error Codes** Field format errors are field-specific and follow predictable patterns tied to each file's schema. This document does not enumerate individual error codes here because they map directly to schema-level field definitions — the error code itself (e.g., `balance_currency_missing`, `transaction_effective_at_invalid_format`) identifies both the file and the field in question. To understand whether a field is required, along with its format, allowed values, and precision, refer to the schema reference for the file type you are validating. ## **Business Rules** Business Rules evaluate the meaning and relationships between fields within a single record — going beyond format to ensure the data is internally consistent and logically valid. The system applies the following checks: * **Polarity:** Validates that the sign of the amount field in the Transactions File is consistent with the transaction type, transfer type, and applied field. * **Component Constraints:** Enforces non-zero amounts only on applicable types for principal, interest, and fee fields. * **Relational Rules:** * **Balance Composition:** Enforce that a top-level amount is fully and correctly broken down into its components. Amount = Principal + Interest + Fee * **Status Pairing:** Ensures valid `status` to `status_reason` pairings (e.g., in the Accounts schema, a "closed" status must pair with `entity_closed`, `client_closed`, etc.). * **Past Due Consistency:** All four past-due fields must be completely present or completely absent. * **Balance Constraints:** Dispute or charge-off balances must be ≤ the main balance. * **Repayment Details:** Type and frequency are strictly required when the program structure demands it. * **Commercial Accounts:** `authorized_signers` are required when `account_holder_type` = commercial * **Timestamp** **Ordering:** Timestamps must follow a logical ordering sequence. For example, a record cannot be updated before it is created ### **Error Codes** #### **Accounts** | Error Code | Description | How to Resolve | | :- | :- | :- | | `account_capabilities_not_allowed` | One or more `capabilities` values declared on this account are not in your program's allowed capabilities list. [Learn More](../account/schema#ids-and-details) | Declare only capabilities permitted by your program configuration, or contact your Technical Account Manager to update the program's allowed capabilities. | | `commercial_account_must_have_authorized_signers` | A commercial account (`account_holder_type` = `commercial`) must have at least one authorized signer. [Learn More](../account/schema) | Add a valid list of authorized signers to the commercial account record. | | `currency_update_not_allowed` | The `currency` field cannot be changed after the record is created. [Learn More](../account/schema#ids-and-details) | Remove the currency update from the record. If the currency was set incorrectly at creation, contact your Technical Account Manager to correct it. | #### **Balances** | Error Code | Description | How to Resolve | | :- | :- | :- | | `balance_cannot_be_closed_with_non_zero_balance` | A balance cannot be moved to `closed` status while it still has a non-zero `balance`. [Learn More](/products/balances-and-transactions/balance-statuses#statuses) | Zero out the balance before marking it closed, or update `status` to reflect the balance's actual state. | | `balance_client_balance_id_not_allowed_for_funding` | `client_balance_id` is not permitted for funding programs. Funding programs must use `id` instead. [Learn More](../balances-and-transactions/balances-schema#ids-and-details) | Remove `client_balance_id` from the record and use the `id` field for funding program balances. | | `balance_currency_must_be_usd_for_funding` | The `currency` value must be `USD` for funding programs. Other currencies are not supported. [Learn More](../balances-and-transactions/balances-schema#ids-and-details) | Update `currency` to `USD` for all funding program balance records. | | `balance_invalid_effective_date` | The `effective_at` value on the balance could not be parsed or is not one day prior to the file date. [Learn More](../balances-and-transactions/balances-schema#status-and-timing) | Ensure `effective_at` is a valid ISO 8601 datetime set to the day before the file date. | | `balance_max_funding_amount_invalid_for_revolving` | `max_funding_amount` must not be populated when `structure` is `revolving`. [Learn More](../balances-and-transactions/balances-schema#credit-details) | Remove `max_funding_amount` from revolving balance records. | | `balance_past_due_balance_invalid_days` | When `past_due_balance` is greater than 0, at least one of `past_due_principal`, `past_due_interest`, or `past_due_fees` must also be greater than 0, and `past_due_days` must be greater than 0. [Learn More](../balances-and-transactions/balances-schema#past-due-balance) | If `past_due_balance` is non-zero, ensure at least one of the breakdown fields and `past_due_days` are also non-zero. | | `balance_receivable_transferred_invalid_status_reason` | When `status` is `receivable_transferred`, `status_reason` must be set to `receivable_sold_to_partner`. No other `status_reason` is valid for this status. [Learn More](/products/balances-and-transactions/balance-statuses#statuses) | Set `status_reason` to `receivable_sold_to_partner` when `status` is `receivable_transferred`. | | `balance_receivable_transferred_only_for_credit` | The `receivable_transferred` status is only valid for balances with `type` = `credit`. [Learn More](/products/balances-and-transactions/balance-statuses#statuses) | Change the `status` of the balance record to an eligible enum. | | `balance_term_unit_invalid_for_revolving` | `term_unit` must not be populated when `structure` is `revolving`. [Learn More](../balances-and-transactions/balances-schema#credit-details) | Remove `term_unit` from revolving balance records. | | `balance_term_value_invalid_for_revolving` | `term_value` must not be populated when `structure` is `revolving`. [Learn More](../balances-and-transactions/balances-schema#credit-details) | Remove `term_value` from revolving balance records. | | `balance_type_funding_program_must_be_credit` | The `type` value must be `credit` for funding programs. Other balance types are not supported. [Learn More](../balances-and-transactions/balances-schema#ids-and-details) | Update `type` to `credit` for all funding program balance records. | | `invalid_balance` | The `balance` value does not match its component fields. For credit balances, `balance` must equal `outstanding_principal` + `outstanding_interest` + `outstanding_fees`. [Learn More](/products/balances-and-transactions/balance-reconciliation) | Recalculate `balance` to equal the sum of its components. | | `invalid_past_due_balance` | The `past_due_balance` exceeds `balance`, or `past_due_balance` must be zero when `balance` is negative. [Learn More](../balances-and-transactions/balances-schema#past-due-balance) | Ensure `past_due_balance` is less than or equal to `balance` and is zero when `balance` is negative. | | `invalid_past_due_fee` | The `past_due_fees` exceeds `outstanding_fees`, or `past_due_fees` must be zero when `balance` is negative. [Learn More](../balances-and-transactions/balances-schema#past-due-balance) | Ensure `past_due_fees` does not exceed `outstanding_fees` and is zero when `balance` is negative. | | `invalid_past_due_interest` | The `past_due_interest` exceeds `outstanding_interest`, or `past_due_interest` must be zero when `balance` is negative. [Learn More](../balances-and-transactions/balances-schema#past-due-balance) | Ensure `past_due_interest` does not exceed `outstanding_interest` and is zero when `balance` is negative. | | `invalid_past_due_principal` | The `past_due_principal` exceeds `outstanding_principal`, or `past_due_principal` must be zero when `balance` is negative. [Learn More](../balances-and-transactions/balances-schema#past-due-balance) | Ensure `past_due_principal` does not exceed `outstanding_principal` and is zero when `balance` is negative. | | `unexpected_balance` | The `balance` does not equal the sum of `outstanding_principal` + `outstanding_interest` + `outstanding_fees`. [Learn More](../balances-and-transactions/balances-schema#balance-activity) | Recalculate `balance` to equal the sum of its component fields. | | `unexpected_past_due_balance` | The `past_due_balance` does not equal the sum of `past_due_principal` + `past_due_interest` + `past_due_fees`. [Learn More](../balances-and-transactions/balances-schema#past-due-balance) | Recalculate `past_due_balance` to equal the sum of its component fields. | #### **Transactions** | Error Code | Description | How to Resolve | | :- | :- | :- | | `amount_and_settlement_amount_are_not_same_signage` | The `amount` and `settlement_amount` fields have different signs. Both must be positive or both must be negative. [Learn More](../balances-and-transactions/transactions-schema#transaction-information) | Update `amount` and `settlement_amount` to have matching signs. | | `incorrect_currency_rate` | The `amount` and `amount_in_usd` values on the transaction do not match for a USD-denominated transaction. [Learn More](./currencies) | Verify that `amount` and `amount_in_usd` are consistent. For USD transactions, both values should be equal. | | `transaction_amount_wrong_polarity` | The `amount` value has the wrong sign for the specified `action`. Debit actions require a negative amount; credit actions require a positive amount. [Learn More](/products/balances-and-transactions/transaction-types) | Update `amount` to match the expected sign for the `action` field. | | `transaction_card_authorization_amount_invalid_value` | `card_authorization_amount` is present but must be empty when `transfer_type` is not `card`. [Learn More](../balances-and-transactions/transactions-schema#card-information) | Remove `card_authorization_amount` from records where `transfer_type` is not `card`, or correct `transfer_type`. | | `transaction_invalid_amount` | The transaction `amount` does not equal the sum of `principal_amount`, `interest_amount`, and `fee_amount` for a credit balance transaction. [Learn More](../balances-and-transactions/transactions-schema#transaction-information) | Recalculate `amount` to equal the sum of its component fields (`principal_amount` + `interest_amount` + `fee_amount`). | | `transaction_invalid_effective_date` | The `effective_at` value on the transaction is invalid or is not exactly one day prior to the file date. [Learn More](../balances-and-transactions/transactions-schema#ids-and-details) | Ensure `effective_at` is a valid ISO 8601 datetime set to the day before the file date. For example, if the file date is `2025-12-31`, `effective_at` must be an ISO 8601 datetime starting with `2025-12-30`. | | `transaction_invalid_settlement_date` | The `settlement_date` on the transaction is invalid for the given `type` and `transfer_type`. The expected value varies: • Zero-day hold programs (`transfer_type` = `card`, `aft`, or `oct`): file date (T) • `type = fee`: T-1 • Card refunds with T-3 settlement enabled: between T-3 and T (inclusive) • `transfer_type = card` with `network_code = PULSE`: any value accepted • Most card and AFT/OCT transactions: ≥ T-1 • `type = disbursement` with `transfer_type = internal_transfer` and a `funding_id`: T-1 [Learn More](../balances-and-transactions/transactions-schema#ids-and-details) | Verify `settlement_date` is a valid ISO 8601 date that matches the expected value for this transaction's `type` and `transfer_type`. | | `transaction_invalid_type_and_action_combinations` | The combination of `type` and `action` is invalid. Not all transaction types are compatible with all action values. [Learn More](/products/balances-and-transactions/transaction-types) | Review the allowed type-and-action combinations for your program type and correct the record. | | `transaction_on_non_active_balance` | The transaction references a balance that does not have `active` status. Transactions can only be applied to active balances. [Learn More](/products/balances-and-transactions/balance-statuses#statuses) | Verify the `balance_id` references an `active` balance. If the balance is inactive or closed, correct the `balance_id` or update the balance status. | | `transaction_rewards_amount_invalid_value` | The `rewards_amount` value is invalid. Either the amount should be zero, or the transaction `type` does not support a non-zero rewards amount. [Learn More](/products/balances-and-transactions/transaction-types) | Set `rewards_amount` to `0.00` if no rewards apply, or update `type` to one that accepts rewards. | | `transaction_rewards_amount_wrong_polarity` | The `rewards_amount` value has the wrong sign for the specified `action`. Debit actions require negative amounts; credit actions require positive amounts. [Learn More](/products/balances-and-transactions/transaction-types) | Update `rewards_amount` to match the expected sign for the `action` field. | | `transaction_type_invalid_activity_check` | The `principal_amount`, `interest_amount`, and `fee_amount` values are inconsistent with the transaction `type`. Certain types require specific amount combinations. [Learn More](/products/balances-and-transactions/transaction-types) | Verify that the amount breakdown matches the expected pattern for this transaction `type`. | | `transaction_zero_value` | The transaction `amount` is zero. Zero-value transactions are not allowed. [Learn More](../balances-and-transactions/transactions-schema#transaction-information) | Set `amount` to a non-zero value or remove the transaction record. | | `transactions_funding_id_invalid_transaction` | `funding_id` is populated on a transaction that does not have `type` of `disbursement` and `transfer_type` of `internal_transfer`. This field is not valid for this combination. [Learn More](../balances-and-transactions/transactions-schema#transaction-information) | Remove `funding_id` from transactions where `type` is not `disbursement` or `transfer_type` is not `internal_transfer`. | | `transactions_funding_id_invalid_value` | The `funding_id` value is invalid. It must be present when `type` is `disbursement` and `transfer_type` is `internal_transfer`, and must be empty otherwise. [Learn More](../balances-and-transactions/transactions-schema#transaction-information) | Verify `funding_id` is set correctly for the transaction type and transfer type combination. | #### **Collaterals** | Error Code | Description | How to Resolve | | :- | :- | :- | | `collateral_address_city_not_allowed` | `address_city` must be empty when `type` is not `real_estate`. [Learn More](/file-reference/collateral/schema#address) | Remove `address_city` from non-real\_estate collateral records. | | `collateral_address_country_not_allowed` | `address_country` must be empty when `type` is not `real_estate`. [Learn More](/file-reference/collateral/schema#address) | Remove `address_country` from non-real\_estate collateral records. | | `collateral_address_line_1_not_allowed` | `address_line_1` must be empty when `type` is not `real_estate`. [Learn More](/file-reference/collateral/schema#address) | Remove `address_line_1` from non-real\_estate collateral records. | | `collateral_address_line_2_not_allowed` | `address_line_2` must be empty when `type` is not `real_estate`. [Learn More](/file-reference/collateral/schema#address) | Remove `address_line_2` from non-real\_estate collateral records. | | `collateral_address_postal_code_not_allowed` | `address_postal_code` must be empty when `type` is not `real_estate`. [Learn More](/file-reference/collateral/schema#address) | Remove `address_postal_code` from non-real\_estate collateral records. | | `collateral_address_state_not_allowed` | `address_state` must be empty when `type` is not `real_estate`. [Learn More](/file-reference/collateral/schema#address) | Remove `address_state` from non-real\_estate collateral records. | | `collateral_effective_at_not_t_minus_one` | The `effective_at` value must be exactly T-1 — one calendar day before the file date. [Learn More](/file-reference/collateral/schema#other) | Update `effective_at` to the day immediately preceding the file date. | | `collateral_value_in_usd_not_allowed` | `value_usd` must be empty when `balance_id` is present. Only one of these fields may be populated per record. [Learn More](/file-reference/collateral/schema#ids) | Remove `value_usd` from records where `balance_id` is provided. | ## **Program Configuration** Program Configuration checks verify that submitted records are consistent with your program's specific setup — such as eligible transaction types, supported currencies, and required bank account identifiers. These rules vary by program, so not all of the following checks may apply to you. The following checks are applied: * **Allowed Transactions:** Validates allowed transaction types, transfer types, and fee types per your specific program (credit, deposit, or funding). * **Settlement Accounts:** `client_settlement_bank_account_id` must match one of the bank accounts established in the program's configuration. * **Funding Constraints:** Funding programs must use the Credit balance type, USD currency, and omit the `client_balance_id`. * **Multi-Currency Exceptions:** Multi-currency programs have relaxed settlement currency matching, but `amount_in_usd` is required. * **Settlement Currency:** Must equal the transaction currency, unless the program is configured to support multiple currencies. * **Conditional Fields:** Certain fields are conditionally required depending on if your program is a non-funding type. `funding_id` requirements depend on the transaction type and your program configuration. ### **How to Resolve** Because these validations depend on your specific program configuration managed by Lead, you cannot resolve them independently. > [!NOTE] > > Contact your Technical Account Manager to confirm which validations apply to your program. ## **Cross-File Reconciliation** Cross-File Reconciliation checks run last and compare data across multiple files or against prior successful submissions — ensuring consistency over time and across related records. These checks only run after the file passes all earlier validation categories. The following checks are applied: * **Continuity:** Balances that are not in a closed status from yesterday's file must appear in today's file. * **Existence:** All foreign keys correctly reference an existing object. For example, in the Transactions file, the `balance_id` and `card_id` must be existing Objects. * **Daily Balance Checks:** Ensures that today's balance (T) equals yesterday's balance (T-1) plus today's daily activity. This is verified for the overall balance, and independently for principal, interest, fees, dispute, charge-off, and rewards components. * **Card Network Settlement Matching:** The sum of transaction amounts per network must equal `network_settlement`.TransactionAmount. This applies to refunds as well. * **Duplicate Protection:** Prevents the reuse of transaction IDs across files. ### **Error Codes** #### **Applications** | Error Code | Description | How to Resolve | | :- | :- | :- | | `application_exists_in_terminal_status` | A record for this `client_application_id` has already been processed and is in a terminal status (`approved`, `declined`, or `canceled`). Applications in a terminal status cannot be resubmitted or updated. [Learn More](../application/statuses#statuses) | Remove the duplicate application record. If this is a new application, assign a unique `client_application_id`. | | `entity_does_not_exist` | An entity referenced on this application (`account_holders`, `authorized_signers`, or `authorized_users`) could not be found in the system. Entities must be created before they can be referenced on an application. [Learn More](../../api-integrations/entity/overview) | Verify the entity identifier is correct and that the entity has been successfully created before referencing it on this application. | | `entity_does_not_have_correct_role` | An entity referenced as an account holder or authorized signer on an approved application does not have the required role. The entity exists in the system but has not been assigned the role needed for this position on the application. [Learn More](/products/entity/roles) | Ensure the entity has been assigned the correct account holder or authorized signer role before referencing it on an approved application. | #### **Accounts** | Error Code | Description | How to Resolve | | :- | :- | :- | | `account_already_exists` | An account with this identifier has already been created. Duplicate account submissions are not allowed. [Learn More](../account/schema#ids-and-details) | Remove the duplicate account record. If this is a distinct new account, assign a unique identifier. | | `account_application_already_used` | The referenced application has already been used to create an account. Each application can only be used once. [Learn More](../application/schema#ids-and-details) | Use a different application for this account, or verify the existing account record is correct and remove the duplicate. | | `account_application_does_not_exist` | The referenced application does not exist. The account cannot be created because the application could not be found. [Learn More](../application/schema#ids-and-details) | Verify the application identifier is correct and that the application was successfully submitted and approved before creating the account. | | `account_application_not_approved` | The referenced application has not been approved. Account creation requires an approved application. [Learn More](../application/statuses#statuses) | Ensure the application is in an approved state before submitting an account record that references it. | | `account_capabilities_removed` | The account's `capabilities` are append-only, and one or more previously set capabilities were dropped in this update. [Learn More](../account/validations) | Re-declare the full set of capabilities the account already carries, adding any new ones. Capabilities can be added but never removed. | | `account_field_cannot_be_updated` | One or more immutable fields in the account record have changed from a prior submission. These fields cannot be updated after the account is created. [Learn More](../account/schema) | Restore the immutable field values to match prior submissions. If the field value must be corrected due to an error, contact your Technical Account Manager. | | `account_fields_do_not_match_application_fields` | Fields in the account record do not match the corresponding fields in the referenced application. Account details must be consistent with the application. [Learn More](../application/schema) | Update the account fields (such as entity, name, and address details) to match the application. | | `account_id_already_exists_for_approved_application` | An account ID already exists for the referenced approved application. Each application can only create one account. [Learn More](../account/schema#ids-and-details) | Verify whether an account already exists for this application before attempting to create another. Remove the duplicate. | | `account_with_update_not_approved` | The account is already in a terminal status and cannot be updated. Once an account reaches a terminal status, further updates to the record are not permitted. [Learn More](../account/statuses#statuses) | Remove the update for this account. If the terminal status was applied in error, contact your Technical Account Manager. | | `application_exists_in_terminal_status` | The referenced application is in a terminal status (e.g., declined or canceled) and cannot be used to create an account. [Learn More](../application/statuses#statuses) | Submit a new application before creating the account, or reference a non-terminal application. | | `effective_at_not_greater_than_previous_effective_at` | The `effective_at` value in this account record is not later than the `effective_at` from the prior submission for this account. Records must be submitted in chronological order. [Learn More](../account/schema) | Ensure the `effective_at` is later than the previous record's `effective_at` for this account. | | `entity_does_not_exist` | An entity referenced on this account (`account_holders`, `authorized_signers`, or `authorized_users`) could not be found in the system. Entities must exist before they can be associated with an account. [Learn More](../../api-integrations/entity/overview) | Verify the entity identifier is correct and that the entity was successfully created before submitting this account record. | | `entity_does_not_have_correct_role` | An entity referenced on this account does not have the required role for their listed position. Account holders must have the account holder role, authorized signers must have the authorized signer role, and authorized users must have the authorized user role. [Learn More](/products/entity/roles) | Ensure each entity has been assigned the correct role before referencing them on an account. | | `entity_does_not_have_credit_score` | The entity associated with this account does not have a credit score on record. A credit score is required for this account type. [Learn More](../../api-integrations/entity/overview) | Ensure a credit score has been submitted for this entity before creating the account. | | `unexpected_authorized_user_in_account_file` | Authorized users must be submitted via the dedicated Authorized Users file, not within the Accounts file. One or more `authorized_users` entries were found in this record for a program configured to use the standalone Authorized Users file. [Learn More](../authorized-users/schema) | Remove `authorized_users` from the Accounts file and submit them via the Authorized Users file instead. | #### **Authorized Users** | Error Code | Description | How to Resolve | | :- | :- | :- | | `authorized_user_update_stale` | The authorized user update is based on stale data. A more recent update for this authorized user already exists. [Learn More](../authorized-users/schema) | Retrieve the latest state of the authorized user record and re-submit the update based on current data. | | `authorized_user_without_active_account` | An authorized user is associated with an account that does not have active status. [Learn More](../authorized-users/schema#status) | Ensure the account is active before associating authorized users, or remove the authorized user record. | | `entity_does_not_exist` | The `entity_id` on this authorized user record could not be found in the system. The entity must be created before it can be added as an authorized user. [Learn More](../../api-integrations/entity/overview) | Verify the `entity_id` is correct and that the entity has been successfully created before submitting this authorized user record. | | `entity_does_not_have_correct_role` | The entity referenced in this record does not have the authorized user role assigned. Only entities with the authorized user role can be added as authorized users. [Learn More](/products/entity/roles) | Ensure the entity has been assigned the authorized user role before referencing it in the Authorized Users file. | | `no_account_found_for_account_id` | No account exists for the given `account_id`. The referenced account has not been created or is not associated with this program. [Learn More](../account/schema#ids-and-details) | Verify the `account_id` is correct and corresponds to an existing account. Ensure the Accounts file was successfully processed before referencing it in this file. | | `no_authorized_user_role_found_for_entity_id` | No authorized user role was found for the given entity ID. The entity must have a valid authorized user role to be associated with an account. [Learn More](../authorized-users/schema) | Verify the entity ID is correct and that the entity has been created with the appropriate authorized user role. | | `unexpected_authorized_user_in_account_file` | An authorized user record appears in the account file for an account that does not list them. [Learn More](../authorized-users/schema) | Remove the unexpected authorized user record or verify the account correctly reflects all intended authorized users. | #### **Cards** | Error Code | Description | How to Resolve | | :- | :- | :- | | `account_does_not_exist` | The referenced account does not exist in the system. [Learn More](../account/schema#ids-and-details) | Verify the account identifier is correct and that the account was previously submitted and processed. | | `card_status_not_terminal_on_terminal_account` | The card must be updated to a terminal status because its associated account is in a terminal status. All cards must reach a terminal status when their account does. [Learn More](/file-reference/card/schema#status-and-timing) | Update the card to `closed` or `expired` before or alongside moving the account to a terminal status. | | `card_with_update_not_approved` | The card cannot be updated because it is already in a terminal status. Exception: cards with a `closed` status may transition to `active` or `inactive`. [Learn More](/file-reference/card/schema#status-and-timing) | Remove the update or verify the transition from the card's current terminal status is permitted. | | `customer_not_authorized_on_account` | The card's `entity_id` is not an account holder or authorized user on the linked account. For active cards, the authorized user must also be active; for inactive cards, active or inactive authorized user status is accepted. [Learn More](../account/schema) | Verify the card's `entity_id` is listed as an account holder or authorized user on the associated account. | | `replacement_card_not_found` | The card referenced in `replaced_by` could not be found. Fires when `replaced_by` is populated but the referenced card does not exist in the current file or in the system. [Learn More](/file-reference/card/schema) | Verify the `replaced_by` card identifier is correct and that the referenced card exists in today's file or has been previously submitted. | #### **Balances** > [!WARNING] > > **Error Code Renames — Effective August 4, 2026** > > Several balance-related error codes are being renamed effective August 4, 2026. See the [Changelog](/changelog) for the full list of changes and what action to take. | Error Code | Description | How to Resolve | | :- | :- | :- | | `account_capability_missing` | The Account referenced by this new balance does not have the capability required to support the balance `type`. `credit` balances require `credit_with_underwriting` or `credit_without_underwriting`; `deposit` balances require `deposit`. [Learn More](../balances-and-transactions/balance-validations#all-balances) | Create or update the Account so that it supports the balance type being created, then resubmit the file. | | `account_id_mismatch` | The `account_id` in today's submission does not match the value from prior submissions for this balance. [Learn More](../balances-and-transactions/balances-schema#ids-and-details) | Ensure `account_id` is consistent with prior submissions for this balance. | | `account_not_found` | The `account_id` on this new balance record does not match any known Account in your program. [Learn More](../balances-and-transactions/balances-schema#ids-and-details) | Correct the `account_id` and resubmit the file. Confirm the Account was submitted and processed successfully before the balance that references it. | | `account_status_invalid` | The Account referenced by this new balance record is not in a permitted status (`active` or `inactive`) to support new balance creation. [Learn More](../account/statuses#statuses) | Update the `account_id` to reference an Account in a permitted status, then resubmit the file. | | `balance_cannot_be_terminal_with_processing_funding` | This balance cannot be set to `closed` or `receivable_transferred` because it has associated funding requests in a processing state. [Learn More](/products/balances-and-transactions/balance-statuses#statuses) | Wait until all in-flight funding requests have reached a terminal status before transitioning this balance to `closed` or `receivable_transferred`, then resubmit. | | `balance_created_after_file_date` | The balance was created after the file date. Balances cannot be included in files dated before their creation date. [Learn More](../balances-and-transactions/balances-schema#ids-and-details) | Remove the balance record from this file and submit it starting from the file date on or after the balance's creation date. | | `balance_not_recognized` | The balance record cannot be matched to any known balance in the system. [Learn More](../balances-and-transactions/balances-schema#ids-and-details) | Verify the balance identifier is correct. If this is a new balance, ensure it was properly created before reporting it. | | `balance_receivable_transferred_outstanding_receivables` | The balance cannot be set to `receivable_transferred` because it has outstanding receivables still held by Lead. All associated receivables must be sold from Lead to you before its status can be set to `receivable_transferred`. [Learn More](/products/balances-and-transactions/balance-statuses#statuses) | Remove the `receivable_transferred` status change from the file and resubmit. | | `client_settlement_bank_account_id_mismatch` | The `client_settlement_bank_account_id` does not match the value from a prior submission for this balance. [Learn More](../balances-and-transactions/balances-schema#ids-and-details) | Ensure `client_settlement_bank_account_id` is consistent with prior submissions for this balance. | | `created_at_timestamp_mismatch` | The `created_at` timestamp in today's submission does not match the value recorded from the initial submission for this balance. This field is immutable after creation. [Learn More](../balances-and-transactions/balances-schema#status-and-timing) | Restore the original `created_at` value from the initial balance submission. | | `currency_mismatch` | The `currency` value does not match the value recorded from the initial submission for this balance. Currency is immutable after creation. [Learn More](../balances-and-transactions/balances-schema#ids-and-details) | Restore the original `currency` value for this balance. If the currency was set incorrectly at creation, contact your Technical Account Manager to correct it. | | `currency_update_not_allowed` | The `currency` value for this balance has changed from a prior submission. Currency is immutable after a balance is created. [Learn More](../balances-and-transactions/balances-schema#ids-and-details) | Restore the original `currency` value. If the currency was set incorrectly at creation, contact your Technical Account Manager to correct it. | | `effective_apr_mismatch` | The `effective_apr` value does not match the value from a prior submission for this balance. [Learn More](../balances-and-transactions/balances-schema#interest-rate) | Ensure `effective_apr` is consistent with prior submissions for this balance. | | `effective_at_not_greater_than_previous_effective_at` | The `effective_at` value is not later than the previous record's `effective_at`. Records must be submitted in chronological order. [Learn More](../balances-and-transactions/balances-schema#status-and-timing) | Ensure each record's `effective_at` is later than the preceding record's `effective_at`. | | `expected_finance_charge_amount_mismatch` | The `expected_finance_charge_amount` value does not match the value from a prior submission for this balance. [Learn More](../balances-and-transactions/balances-schema#credit-details) | Ensure `expected_finance_charge_amount` is consistent with prior submissions. | | `invalid_balance` | The `balance` does not match the sum of the prior day's `balance` and the current day's net transaction activity. [Learn More](/products/balances-and-transactions/balance-reconciliation) | Recalculate `balance` to equal the prior day's `balance` plus the sum of all transaction amounts for this reporting period. | | `invalid_outstanding_fee` | The `outstanding_fees` reported does not match the expected value. It must equal the previous reporting day's `outstanding_fees` plus the current reporting day's fee activity. [Learn More](/products/balances-and-transactions/balance-reconciliation) | Recalculate `outstanding_fees` to equal the prior day's value plus net fee transaction activity. | | `invalid_outstanding_interest` | The `outstanding_interest` reported does not match the expected value. It must equal the previous reporting day's `outstanding_interest` plus the current reporting day's interest activity. [Learn More](/products/balances-and-transactions/balance-reconciliation) | Recalculate `outstanding_interest` to equal the prior day's value plus net interest transaction activity. | | `invalid_outstanding_principal` | The `outstanding_principal` reported does not match the expected value. It must equal the previous reporting day's `outstanding_principal` plus the current reporting day's principal activity. [Learn More](/products/balances-and-transactions/balance-reconciliation) | Recalculate `outstanding_principal` to equal the prior day's value plus net principal transaction activity. | | `is_interest_based_mismatch` | The `is_interest_based` value does not match the value from a prior submission for this balance. [Learn More](../balances-and-transactions/balances-schema#credit-details) | Ensure `is_interest_based` is consistent with prior submissions. | | `max_funding_amount_mismatch` | The `max_funding_amount` value does not match the value from a prior submission for this balance. [Learn More](../balances-and-transactions/balances-schema#credit-details) | Ensure `max_funding_amount` is consistent with prior submissions. | | `previous_active_account_balance_missing` | A non-terminal account balance from the prior day is missing from today's submission. All non-terminal balances must be reported every day. [Learn More](/products/balances-and-transactions/balance-statuses#statuses) | Add the missing balance record to today's file. If the balance is no longer active, report it with a terminal status. | | `previous_active_balance_missing` | A balance that was active in the prior day's submission is missing from today's Balances file. Non-closed balances must be reported every day. [Learn More](/products/balances-and-transactions/balance-statuses#statuses) | Add the missing balance record to today's Balances file. All non-closed balances from the prior day must be included. | | `previous_active_card_balance_missing` | A non-terminal card balance from the prior day is missing from today's submission. All non-terminal card balances must be reported every day. [Learn More](/products/balances-and-transactions/balance-statuses#statuses) | Add the missing card balance record to today's file. If the balance is no longer active, report it with a terminal status. | | `rewards_unit_mismatch` | The `rewards_unit` value does not match the value from a prior submission for this balance. [Learn More](../balances-and-transactions/balances-schema#rewards-balance) | Ensure `rewards_unit` is consistent with prior submissions for this balance. | | `structure_mismatch` | The `structure` field value does not match the value from a prior submission for this balance. [Learn More](../balances-and-transactions/balances-schema#ids-and-details) | Ensure `structure` is consistent with all prior submissions for this balance. If a correction is needed, contact your Technical Account Manager. | | `unexpected_charge_off_balance` | The `charge_off_balance` does not match the sum of its components (`charge_off_principal` + `charge_off_interest` + `charge_off_fees`), or does not reconcile with the prior day's `charge_off_balance` plus current charge-off transaction activity. [Learn More](../balances-and-transactions/balances-schema#charge-off-balance) | Verify `charge_off_balance` equals the sum of its component fields and reconciles with the prior day's value plus today's charge-off transactions. | | `unexpected_charge_off_fee` | The `charge_off_fees` does not reconcile with the prior day's `charge_off_fees` plus current charge-off transaction activity affecting fees. [Learn More](../balances-and-transactions/balances-schema#charge-off-balance) | Verify `charge_off_fees` equals the prior day's value plus net charge-off activity for fees. | | `unexpected_charge_off_interest` | The `charge_off_interest` does not reconcile with the prior day's `charge_off_interest` plus current charge-off transaction activity affecting interest. [Learn More](../balances-and-transactions/balances-schema#charge-off-balance) | Verify `charge_off_interest` equals the prior day's value plus net charge-off activity for interest. | | `unexpected_charge_off_principal` | The `charge_off_principal` does not reconcile with the prior day's `charge_off_principal` plus current charge-off transaction activity affecting principal. [Learn More](../balances-and-transactions/balances-schema#charge-off-balance) | Verify `charge_off_principal` equals the prior day's value plus net charge-off activity for principal. | | `unexpected_dispute_balance` | The `dispute_balance` does not match the sum of its components (`dispute_principal` + `dispute_interest` + `dispute_fees`), or does not reconcile with the prior day's `dispute_balance` plus current dispute transaction activity. [Learn More](../balances-and-transactions/balances-schema#dispute-balance) | Verify `dispute_balance` equals the sum of its component fields and reconciles with the prior day's value plus today's dispute transactions. | | `unexpected_dispute_fee` | The `dispute_fees` does not reconcile with the prior day's `dispute_fees` plus current dispute transaction activity affecting fees. [Learn More](../balances-and-transactions/balances-schema#dispute-balance) | Verify `dispute_fees` equals the prior day's value plus net dispute activity for fees. | | `unexpected_dispute_interest` | The `dispute_interest` does not reconcile with the prior day's `dispute_interest` plus current dispute transaction activity affecting interest. [Learn More](../balances-and-transactions/balances-schema#dispute-balance) | Verify `dispute_interest` equals the prior day's value plus net dispute activity for interest. | | `unexpected_dispute_principal` | The `dispute_principal` does not reconcile with the prior day's `dispute_principal` plus current dispute transaction activity affecting principal. [Learn More](../balances-and-transactions/balances-schema#dispute-balance) | Verify `dispute_principal` equals the prior day's value plus net dispute activity for principal. | | `unexpected_interest_balance` | The `interest_accrued_balance` does not reconcile with the prior day's `interest_accrued_balance` plus current interest accrual transaction activity. [Learn More](../balances-and-transactions/balances-schema#balance-activity) | Verify `interest_accrued_balance` equals the prior day's value plus net interest accrual activity from today's transactions. | | `unexpected_reward_balance` | The `rewards_balance` does not reconcile with the prior day's `rewards_balance` plus current rewards transaction activity. [Learn More](../balances-and-transactions/balances-schema#rewards-balance) | Verify `rewards_balance` equals the prior day's value plus net rewards activity from today's transactions. | #### **Transactions** | Error Code | Description | How to Resolve | | :- | :- | :- | | `funding_fee_amount_mismatch` | The `fee_amount` does not match the `other_fees.borrower_origination_fee_amount` on the associated Funding object. Applies to transactions with `type` = `disbursement`, `transfer_type` = `internal_transfer`, and `funding_id` is populated. [Learn More](../balances-and-transactions/transactions-schema#transaction-information) | Verify that `fee_amount` equals `other_fees.borrower_origination_fee_amount` on the associated Funding object. | | `funding_transaction_principal_amount_mismatch` | The `principal_amount` on the transaction does not match the sum of principal amounts on the funding object referenced by `funding_id`. [Learn More](../balances-and-transactions/transactions-schema#transaction-information) | Verify that `principal_amount` equals the total principal amount on the associated funding object. Correct the transaction so it matches the funding record. | | `outstanding_card_balance_activity_mismatch` | The outstanding card balance does not reconcile with transaction activity. Balance (T) must equal Balance (T-1) plus net transaction activity. [Learn More](/products/balances-and-transactions/balance-reconciliation) | Verify the balance reflects all transactions from today's file and reconcile any differences. | | `total_charged_off_amount_mismatch_card_balance` | The total charged-off amount across transactions does not match the `charge_off_balance` in the card balance. [Learn More](../balances-and-transactions/balances-schema#charge-off-balance) | Verify the sum of all charge-off transactions equals the `charge_off_balance` field. Correct either the transactions or the balance. | | `total_interest_transaction_amount_mismatch_card_balance` | The total interest transaction amount does not match the interest component in the card balance. [Learn More](/products/balances-and-transactions/balance-reconciliation) | Verify the sum of interest transactions equals the interest component in the balance. Correct. | | `total_payment_transaction_amount_mismatch_card_balance` | The total payment transaction amount does not match the payment component in the card balance. [Learn More](/products/balances-and-transactions/balance-reconciliation) | Verify the sum of payment transactions equals the payment component in the balance. Correct. | | `total_reward_transaction_amount_mismatch_card_balance` | The total reward transaction amount does not match the rewards component in the card balance. [Learn More](../balances-and-transactions/balances-schema#rewards-balance) | Verify the sum of reward transactions equals the `rewards_balance` in the balance. Correct. | | `total_transaction_amount_mismatch_balance` | The sum of all transaction amounts for this account does not match the balance. [Learn More](/products/balances-and-transactions/balance-reconciliation) | Verify that the net sum of all transactions for this account equals the reported balance change. Correct the balance or transactions. | | `transaction_already_exists` | A transaction with this `client_transaction_id` has already been successfully processed. Duplicate transaction IDs are not allowed across submissions. [Learn More](../balances-and-transactions/transactions-schema#ids-and-details) | Remove the duplicate record. If this is a new transaction, assign a unique `client_transaction_id`. | | `transaction_and_balance_currency_mismatch` | The transaction currency does not match the currency of the associated balance. [Learn More](../balances-and-transactions/transactions-schema#ids-and-details) | Ensure the `currency` field on the transaction matches the `currency` of the balance it references. | | `transaction_balance_credit_amount_mismatch` | The sum of credit transaction amounts for this balance does not match the balance's credit component. [Learn More](/products/balances-and-transactions/balance-reconciliation) | Reconcile the credit transactions against the balance credit component and correct any discrepancies. | | `transaction_balance_fees_amount_mismatch` | The sum of fee transaction amounts for this balance does not match the balance's fees component. [Learn More](/products/balances-and-transactions/balance-reconciliation) | Reconcile the fee transactions against the balance fees component and correct any discrepancies. | | `transaction_balance_interest_amount_mismatch` | The sum of interest transaction amounts for this balance does not match the balance's interest component. [Learn More](/products/balances-and-transactions/balance-reconciliation) | Reconcile the interest transactions against the balance interest component and correct any discrepancies. | | `transaction_balance_payment_amount_mismatch` | The sum of payment transaction amounts for this balance does not match the balance's payment component. [Learn More](/products/balances-and-transactions/balance-reconciliation) | Reconcile the payment transactions against the balance payment component and correct any discrepancies. | | `transaction_balance_reward_amount_mismatch` | The sum of reward transaction amounts for this balance does not match the balance's rewards component. [Learn More](/products/balances-and-transactions/balance-reconciliation) | Reconcile the reward transactions against the balance rewards component and correct any discrepancies. | | `transaction_balance_transaction_amount_mismatch` | The total transaction amount for this balance does not match the expected net balance change. [Learn More](/products/balances-and-transactions/balance-reconciliation) | Reconcile all transaction amounts for this balance and ensure the net change matches the reported balance movement. | | `transaction_missing_balance` | No balance record was found for the transaction's associated account on the file date. [Learn More](../balances-and-transactions/balances-schema#ids-and-details) | Ensure a balance record exists for the account before submitting transactions. | | `transaction_missing_card_balance` | No card balance record was found for this transaction. [Learn More](../balances-and-transactions/balances-schema#ids-and-details) | Ensure a card balance exists for the referenced card before submitting transactions. | | `transaction_on_unknown_balance` | The transaction references a `balance_id` that does not correspond to any known balance. [Learn More](../balances-and-transactions/transactions-schema#ids-and-details) | Verify the `balance_id` on the transaction is correct and that the balance was successfully processed before submitting this transaction. | #### **Transactions Update** | Error Code | Description | How to Resolve | | :- | :- | :- | | `transaction_update_target_is_missing` | The `transaction_id` in the Transactions Update file does not match any previously submitted transaction. A settlement date update can only be applied to a transaction that has already been successfully processed. [Learn More](../balances-and-transactions/transactions-update-schema) | Verify the `transaction_id` is correct and that the original transaction was submitted and processed in a prior Transactions file before submitting an update. | #### **Collaterals** | Error Code | Description | How to Resolve | | :- | :- | :- | | `collateral_account_invalid_status` | The account referenced in the Collateral file does not have a valid status for this operation. [Learn More](../account/statuses#statuses) | Verify the referenced account is in `active` status before submitting collateral. | | `collateral_account_not_found` | The `account_id` in the Collateral file does not match any known account. [Learn More](/file-reference/collateral/schema#ids) | Verify the `account_id` is correct and that the account exists in the system before submitting collateral. | | `collateral_balance_account_id_mismatch` | The `account_id` in the Collateral file does not match the `account_id` on the referenced balance. [Learn More](/file-reference/collateral/schema#ids) | Ensure the collateral record's `account_id` matches the account associated with the referenced balance. | | `collateral_balance_invalid_status` | The collateral's referenced balance does not have a valid status for this operation. [Learn More](/products/balances-and-transactions/balance-statuses#statuses) | Verify the referenced balance has `active` status before submitting collateral. | | `collateral_balance_not_deposit_type` | The referenced balance is not of type `deposit`. Collateral records with `type` of `deposit_balance` must reference a deposit-type balance. [Learn More](/file-reference/collateral/schema) | Ensure the `balance_id` references a balance with `type` of `deposit`. | | `collateral_balance_not_found` | The `balance_id` in the Collateral file does not match any known balance. [Learn More](/file-reference/collateral/schema#ids) | Verify the `balance_id` is correct and that the referenced balance exists before submitting collateral. | | `collateral_balance_too_many_active_collaterals` | Too many active collateral records exist for this balance. The allowed limit has been exceeded. [Learn More](/file-reference/collateral/schema#ids) | Review the active collateral records for this balance and ensure only the permitted number are in `active` status. | | `collateral_immutable_field_changed` | An immutable field in the collateral record has changed from a prior submission. [Learn More](/file-reference/collateral/schema#details) | Restore the immutable field values to match prior submissions. Contact your Technical Account Manager if a correction is required. | # Exchanging files with Lead over SFTP Source: https://docs.lead.bank/file-reference/delivery/overview Understand how to exchange data with Lead via SFTP. > [!NOTE] > > This guide details how to exchange data with Lead via SFTP, including the steps for file submission, processing, integration testing, and go-live readiness. ## Connectivity for File Delivery Lead uses [SFTP with key-based authentication](/file-reference/sftp-setup) to ensure the secure transfer of all data. ## File Formats and Delimiters Files are typically submitted in CSV format. Use a pipe (|) delimiter to separate data elements, and do not use a comma (,) or semicolon (;) delimiter. Specific data schemas define the required fields, data types, and formatting for each file. To minimize file processing errors, we recommend using an open source CSV parser to confirm the CSV formatting is valid before submitting it to Lead. > [!WARNING] > > All header values are case-sensitive. Please ensure you are following the case definitions as described in each file schema. As an example, all [Customer File Schema](/file-reference/customer/customer-schema) headers are lower-case, meaning `client_customer_id` as a header value will pass validation, but `CLIENT_CUSTOMER_ID` will not. ## Data Patterns * **ID Semantics**: The `client_` prefix denotes a partner-generated unique ID for records being created or updated in Lead. To reference an existing record, use its ID without this prefix. Schema fields for such references may use semantic names (e.g., `replaced_by` expecting an existing card's ID) or names indicating the object type (like `account_id` referencing an account originally defined via `client_account_id`). * **Updating Data**: Records may be updated via file. Updating records via file submission means a complete overwrite. Ensure each submission for an existing client\_id contains the entire updated record. ## File Submission and Processing ### Data Requirements Depending on the nature of the file, files have differing expectations on what kind of data Lead expects. > [!WARNING] > > Unless the file type requires all entries daily, do not upload your full dataset on a daily basis. Instead, follow the submission pattern for data that corresponds to each file type in the table below. | **Submission Requirement** | **File Types** | | - | - | | New records and changes to existing records only | Customer, Customer Relationship, Applications, Accounts, Cards, Authorized Users, Collaterals | | New entries only (no updates or unchanged records) | Transactions, Sales Responses, ACH files | | Updates only (no new entries) | Transactions Update | | All entries daily | Balances (for accounts not in `closed` status), Non-posted Transactions (until posted) | ## All or Nothing Processing All files submitted to Lead follow an all-or-nothing paradigm at the file level. When you submit a file, Lead will attempt to process it in its entirety. If any schema or business validation errors are found within the rows of that file, the entire file will be rejected. Each file type’s data schema page and overview pages outlines a non-exhaustive list of which specific schema and business validations are run for that file type. > [!WARNING] > > We do not support partial file processing. ## Workflows Files submitted to Lead are processed in grouped workflows. Workflows are logical groups of files that are processed together based on their functional category. File processing is organized into the following workflow categories: | **Workflow** | **Files** | **File Naming Convention** | Ingestion Paradigm | | - | - | - | - | | Customer | Customer and Customer Relationship | `__.csv` | [Batch Submission](#batch-submission) | | Compliance\* | Applications, Accounts, Cards, Authorized Users\*\* | `__.csv` | [Daily Submission](#daily-submission) | | Financial | Balances, Transactions, Collaterals, Non-posted Transactions, Transaction Updates | `__.csv` | [Daily Submission](#daily-submission) | | Sales | Sales Request (Lead), Sales Response (Partner) | `__.csv` | [Daily Submission](#daily-submission) | | Documents | PDF, JPG, JPEG Documents referenced within file data schemas. | `___.` Suggested naming convention, but any string file name is sufficient for the Documents directory. | N/A | \* For partners onboarded prior to Q2, 2026, the Compliance workflow follows a once-per-day convention, mirroring the Financial workflow. Best practice is to upload all of the files in a given workflow, wait for a [Slack Alert](/file-reference/delivery/slack-alerts) with Lead's processing results for those files, then proceeding with either a version bump and resubmission of the workflow or an upload of your next workflow. Records in subsequent workflows can reference records created in preceding workflows — e.g., a newly created Balance record submitted in the Financial Workflow references an Account record submitted in the Compliance Workflow — so you may receive errors if the Financial files are submitted before the Compliance Workflow has completed processing. > [!TIP] > > **Consider Your Program Setup**\ > You might be configured for Lead to only expect a subset of files for a given workflow. For example, if your program does not use the Applications or Authorized Users file, then your compliance workflow will only consist of the Accounts and Cards files > [!NOTE] > > **A Note About Sales** > > If your program is a credit-based program (e.g. a credit card or a term loan product), Lead will perform a sales handshake regardless of whether your program has a balance sheet model of Originate-to-Sell or On-Sheet Lending. This workflow runs after the Financial workflows pass validations for a given day. At that point, Lead generates a Sales Request file and you submit a Sales Response file accordingly. Sales Request files only contain receivables designated as Originate-to-Sell (OTS) — if there are no OTS receivables on a given day, the file will be empty. ## Ingestion Paradigms All files within a workflow are grouped together under specific Ingestion Paradigms, which dictate how the files are validated, processed, and resubmitted. Different file types and program configurations follow different rules for submission frequency and processing logic. #### Daily Submission **Applies to:** * Financial Workflow * Sales Workflow * Compliance Workflow for partners onboarded prior to Q2, 2026 **How It Works:** * On any given day T, our system expects a file containing activity for day T-1. * The filename will reflect date T, but the data inside corresponds to activity from the previous day (T-1). * Activity is expected to cover the full calendar day: 12:00 a.m. to 11:59:59 p.m. CT on T-1. * Since the Central Time timezone can change between CST and CDT, we recommend having your code build the calendar day based on the "America/Chicago". When processing your files, Lead will parse the timestamp with the current "America/Chicago" timezone, and extract the date from the timestamp. We then check that dates included are from T-1 (i.e., the date before the file's date). Files following the Daily Submission paradigm follow a **sequential submission** rule: * You may only submit Day T+1’s file after Day T’s file has been successfully validated. * This rule applies even if the file for a given day contains headers only with no activity. > [!NOTE] > > [See guide](/guides/store/launch-a-deposit-program) to determine Day 0 so you can begin testing and uploading files. #### Batch Submission Once you submit a file with a `batch_id`, Lead will wait five minutes for other files to be delivered with the same `batch_id` and then begin processing the full batch. Under Batch Submission, files within a workflow are grouped together. Files with no errors or dependencies on erroneous files will be processed successfully. For example - an Accounts file submission within a Compliance workflow may return a success message, even when an error exists in a Cards file uploaded with the same `batch_id` because no changes to the Accounts file are required. Batch Submission will only return a cross-file validation failure when a file includes a reference to an object that Lead cannot find, either within the same batch, a previous batch, or an API submission. **Applies to:** * Compliance Workflow (Applications, Accounts, and Cards files) for programs onboarded from Q2 2026 onward. Once a workflow is processed successfully, no more submissions for the same Batch may be submitted. #### Strict Batch Submission **Applies to:** * Customer Workflow (Customer, Customer Relationship) * **If your program is configured to require the Customer Relationship file:** Both files must be submitted with the same batch ID before a batch will begin to process. * **If your program is configured to only require the Customer file:** Each file needs a unique batch ID. **How It Works:** Strict Batching allows multiple file submissions per day, distinct by a unique `batch_id`. In this semantic, the workflow is atomic: all files required for the workflow must pass validation together. Strict Batching differs from Batching in that, if either file has any failures, the entire batch will fail to process, requiring resubmission of the full batch. * **Batching:** All files in the workflow must be submitted with the same `batch_id` to trigger processing. * **Validation:** If *any* file in the batch fails validation, the **entire batch** is rejected. No data from the batch is persisted. > [!CAUTION] > > Ensure that the Batch ID is unique for each batch; re-used batch IDs will not be processed. ## Resubmitting Files If a file or workflow receives an Error alert, that indicates that Lead has not saved any information contained within the file. You must resubmit it for Lead to process the files. 1. Correct the errors based on the Slack alert. 2. Increment the `` in the filename, keeping the same date or batch ID designator from the file name. 3. Resubmit the corrected file to the appropriate SFTP folder. **Restrictions on Resubmitting Successful Files:** For **Daily** file submission workflows, *Lead is not able to accept multiple successful submissions for one day*. If a success alert is delivered for a day, subsequent submissions for the same date will not be processed. If, for any reason, a record was missed in a daily file's aggregation, and that file processes successfully, the missed record would need to be included in the subsequent day's file submission. ### Reminders > [!TIP] > > **File Schemas** > > Each file type you submit has a defined data schema outlining all fields, requirements, and data types. Please consult the specific schema documentation for each file (e.g., Accounts Data Schema, Transactions Data Schema). You should familiarize yourself deeply with the file schemas. > [!TIP] > > **Files in SFTP** > > Once we've provisioned your SFTP access, you may need to submit a first file before you can view the directory. > [!WARNING] > > **Escaped JSON** > > When a field requires JSON data within a CSV, the JSON string must be enclosed in double quotes, and any internal double quotes must be escaped by doubling them. Refer to the individual data schema pages for fields requiring this format. # Slack Alerts Source: https://docs.lead.bank/file-reference/delivery/slack-alerts Monitor your program. When onboarding to Lead, your team will be set up with a dedicated Slack channel for monitoring. These are the type of alerts you can expect to see: | **Alert Type** | **Description** | | - | - | | 🔴 Error | A required file or action failed and needs your attention. | | 🟡 Warning | Something looks off, but may not be blocking processing. | | 🟢 Success | The file successfully processed or action completed. | # Compliance Documents Source: https://docs.lead.bank/file-reference/documents/compliance-documents JSON reference for Documents in the applications and accounts files, covering document_id, type, consented_at, displayed_at, and version fields. ### Compliance Document Reference Schema | Key | Data Type | Requirement | Example | Guidance | | :- | :- | :- | :- | :- | | `document_id` | String | Required | `client_document_name.png` | Please use the file name of the Document delivered to Lead's `/documents` SFTP directory. | | `type` | Enum | Required | `partner_privacy_policy` | Please map all documents to one of the types below | | `displayed_at` | datetime | Conditionally Required | `2025-12-31T09:30:00Z` | Please refer to the [Compliance Document Types](#compliance-document-types) list to determine if this is required for the provided document `type`. | | `consented_at` | datetime [ISO8601](https://www.iso.org/iso-8601-date-and-time-format.html) | Conditionally Required | `2025-12-31T09:30:00Z` | Please refer to the [Compliance Document Types](#compliance-document-types) list to determine if this is required for the provided document `type`. | | version | string | Optional | `"v1"` | It is recommended to use this for static documents uploaded once and uploaded for many users. Uploads with a new version should have a different `document_id` as well. | ### Compliance Document Types | **Type** | **Description** | **Required Fields** | | - | - | - | | `aan` | Adverse Action Notice generated and sent/displayed to customer. | `displayed_at` | | `loan_agreement` | Loan agreement displayed to customer. | `displayed_at` | | `loc_agreement` | Line of Credit agreement displayed to customer. | `displayed_at` | | `truth_in_lending_document` | Truth in Lending disclosure displayed to customer. | `displayed_at` | | `ach_authorization` | ACH Payment Authorization displayed to customer. | `displayed_at` | | `notice_of_incompleteness` | Notice of Incompleteness displayed to customer. | `displayed_at` | | `credit_score_notice` | Credit score notice displayed to customer. | `displayed_at` | | `offer_summary` | Offer Summary displayed to customer. | `displayed_at` | | `personal_guarantee` | Personal Guaranty displayed to customer. | `displayed_at` | | `consumer_credit_auth` | Credit pull authorization obtained from customer. | `displayed_at` | | `partner_privacy_policy` | Partner's Privacy Policy displayed to customer. | `displayed_at` | | `lead_privacy_policy` | Lead's Privacy Policy displayed to customer. | `displayed_at` | | `terms_of_use` | Partner's Terms of Use displayed to customer. | `displayed_at` | | `esign_agreement` | eSign Agreement consented to by customer. | `consented_at` | | `credit_pull_consent` | Credit pull authorization obtained from customer. | `consented_at` | | `fcra_notice` | FCRA Notice displayed to customer. | `displayed_at` | | `tcpa_consent` | TCPA consent displayed to customer. | `displayed_at` | | `patriot_act_notice` | Patriot Act notice displayed to customer. | `displayed_at` | | `mla_notice` | Military Lending Act notice displayed to customer. | `displayed_at` | | `pre_approval_terms` | Pre-Approval Terms displayed to customer. | `displayed_at` | | `eft_authorization` | EFT Authorization displayed to customer. | `displayed_at` | | `prohibited_industry_certification` | Prohibited industry certification displayed to customer. | `displayed_at` | | `decision_maker_document` | Decision maker document displayed to customer. | `displayed_at` | | `bo_certification` | Business Owner Certification displayed to customer. | `displayed_at` | | `missed_payments_policy` | Missed Payments Policy displayed to customer. | `displayed_at` | | `consent_to_link_account` | Account link consent obtained from customer. | `consented_at` | | `consent_to_link_hsa` | HSA link consent obtained from customer. | `consented_at` | | `negative_option_consent` | Negative Option Consent obtained from customer. | `consented_at` | | `lead_funds_transfer_agreement` | Funds transfer agreement displayed to customer. | `displayed_at` | | `deposit_agreement` | Deposit agreement consented to by customer. | `consented_at` | | `cardholder_agreement` | Cardholder agreement consented to by customer. | `consented_at` | | `periodic_statement` | Periodic statement displayed to customer. | `displayed_at` | | `autopay_authorization` | Autopay authorization consented to by customer. | `consented_at` | # Document Delivery Over SFTP Source: https://docs.lead.bank/file-reference/documents/overview Details on SFTP document delivery. ## Introduction Throughout the API and File Delivery interfaces, you will see areas where Lead expects a **reference** to a Document you have collected as part of program operation. In each of these cases, Lead expects that a document is delivered into the `/documents` [SFTP directory](/file-reference/sftp-setup); the *references* inform Lead of how to retrieve the underlying documents from our SFTP directory. This page outlines how to reference documents in each interface that expects document references. ### Document Upload #### SFTP Documents that are referenced in Lead Interfaces should be uploaded via SFTP. To upload a document, upload a `PDF`, `JPG`, `JPEG`, `PNG`, or `HTML` file into the `/documents` directory of your SFTP Folder. ### Document References #### Entity API | Field | **Type** | **Required** | **Instruction** | | - | - | - | - | | `individual_details.identification_details.identification_documents[].client_document_id` | String | Optional - provided if a document upload rather than an approved eKYC workflow is used to support entity identification information. | Populate `client_document_id` with the filename of the file in the SFTP directory. | | `individual_details.identification_details.additional_documents[].client_document_id` | String | Optional - provided if a document upload rather than an approved eKYC workflow is used to support entity identification information. | Populate `client_document_id` with the filename of the file in the SFTP directory. | | `business_details.identification_details.identification_documents[].client_document_id` | String | Optional - provided if a document upload rather than an approved eKYC workflow is used to support entity identification information. | Populate `client_document_id` with the filename of the file in the SFTP directory. | | `business_details.identification_details.additional_documents[].client_document_id` | String | Optional - provided if a document upload rather than an approved eKYC workflow is used to support entity identification information. | Populate `client_document_id` with the filename of the file in the SFTP directory. | #### Customers File | Field | **Type** | **Required** | **Instruction** | | :- | :- | :- | :- | | `identification_documents[].client_document_id` | String | Optional - provided if a document upload rather than an approved eKYC workflow is used to support entity identification information. | Populate `client_document_id` with the filename of the file in the SFTP directory. | | `additional_documents[].client_document_id` | String | Optional - provided if a document upload rather than an approved eKYC workflow is used to support entity identification information. | Populate `client_document_id` with the filename of the file in the SFTP directory. | #### Applications File | Field | **Type** | **Required** | **Instruction** | | :- | :- | :- | :- | | `documents` | JSON List | Required | Each object in the JSON should conform to the [Compliance Document Reference Schema](/file-reference/documents/compliance-documents). For `document_id`, populate the File Name of the underlying file stored in the SFTP directory. | #### Accounts File | Field | **Type** | **Required** | **Instruction** | | :- | :- | :- | :- | | `documents` | JSON List | Required | Each object in the JSON should conform to the [Compliance Document Reference Schema](/file-reference/documents/compliance-documents). For `document_id`, populate the File Name of the underlying file stored in the SFTP directory. | # Nacha Files Source: https://docs.lead.bank/file-reference/nacha-files Legacy reference for ACH file processing via Nacha files, replaced by the ACH API. > [!WARNING] > > ***Legacy.*** File-based ACH origination is not available to new programs — use the [ACH API](/products/ach/overview). Existing Nacha-integrated programs: contact your Lead team about migrating. ## **Overview** You will transmit ACH files in Nacha format via [SFTP](/file-reference/sftp-setup). We validate all incoming files to ensure completeness and compliance with [standard Nacha formatting](https://achdevguide.nacha.org/ach-file-overview) before forwarding to the Federal Reserve for further processing. When Lead delivers a file to your SFTP server, you will receive a Slack notification. You will also receive a Slack alert if a file fails validation or contains formatting issues. ## **Folder Structure** All program related files will be dropped into folders on the SFTP server with the following access: * **Read/Write:** For all folders where you are the submitter * **Read Only:** For folders where Lead is the submitter | **File** | **Submitter** | **Folder Name** | **File Example** | | - | - | - | - | | ACH Outgoing | You | ach/outgoing | `20260115T171640Z_outgoing_ach_1768557400.ach` | | ACH Failed | Lead | ach/failed | `20260115T171640Z_outgoing_ach_1768557400.ach` | | ACH Incoming | Lead | ach/incoming | `20260115T171640Z_incoming_ach_return_noc_768557400.ach` `20260115T171640Z_incoming_ach_return_768557400.ach` `20260115T171640Z_incoming_ach_noc_768557400.ach` `20260115T171640Z_incoming_ach_forward_768557400.ach` | | ACH Processed | Lead | ach/processed | `20260115T171640Z_outgoing_ach_768557400.ach` | ## File Naming We utilize a consistent filename format that aims to: * Indicate the type of file * Indicate the content represented in the particular file * Prevent filename collisions for similar files #### **Example File Format** `20260115T171640Z_incoming_ach_forwards_1768497400.ach` | **20260115T171640Z** | **incoming\_ach\_forwards** | **1768497400** | | - | - | - | | Content Identifier | File Type | Epoch Time of File Generation | | This will correspond to the content of the file. For loan origination files, this will be a date. For ACH files, this will be a date and time. | This indicates the meaning and format of the file. | This serves to prevent similar files from colliding and preserves generation time ordering for similarly named files. | > [!TIP] > > File versions can be represented by either an epoch timestamp (not ISO 8601) or an incremental version label such as v1, v2, etc. Each subsequent submission must use a higher version value. #### Example Invalid File Name If the initial file version is invalid or changes are required, you must submit the updated version of the file — with an updated epoch time of version label, such as "v2". | **Original** | 20260115T171640Z\_incoming\_ach\_forwards\_**1768497400**.ach | | - | :- | | **Updated Resubmission** | 20260115T171640Z\_incoming\_ach\_forwards\_**1768642400**.ach *Notice the updated epoch timestamp* | ## File Header Guidelines Nacha file headers have some flexibility on the values of certain fields. The following table outlines what values to use/expect for certain fields for both outgoing and incoming files. > [!TIP] > > We do not require you to send a balanced Nacha file. | Field Name | Outgoing (You to Lead) | Incoming (Lead to You) | | - | - | - | | Immediate Origin | This field is not used by the Lead’s ACH system because Lead identifies partners another way. We use CompanyID on the batch header for posting to identify your account. Please specify as **9999999999**. Partners may in some cases need to specify this value and should work with Lead if this is needed. | **101019644** (Lead's Routing Number) | | Immediate Origin Name | Blank | Lead Bank | | Immediate Destination | 101019644 | 9999999999 Contact Lead if you need to set this to a specific value. | | File Creation Date | Determined at file generation time | Determined at file generation time | | File Creation Time | Determined at file generation time | Determined at file generation time | | File ID Modifier | Determined at file generation time | Determined at file generation time | | Reference Code | Blank | Blank | # ACH Cash Reconciliation Source: https://docs.lead.bank/file-reference/reports/ach-cash-reconciliation Field reference for Lead's ACH Settlement Cash Reconciliation report, used to reconcile transaction-level ACH detail to aggregated bank statement entries. ## Overview Because ACH settlements are processed in aggregated or batched form, we provide this report with transaction-level ACH details to help reconcile them with the aggregated settlements shown on your bank statement. | **Field Name** | YYYY-MM-DD\_CLIENTNAME-ach-cash-recon-report\_\[UNIQUE-POSTFIX].csv | | - | - | | **Delivered To** | bank-account-reports (along with other bank-account-reports) | | **Frequency** | Per calendar day for previous calendar day's settled ACH transactions Note: Because ACH only settles on business days, this report will have 0 data rows — only headers — during bank holidays. | | **Data Cutoff Time** | 12:00:00 a.m. CT to 11:59:59 p.m. CT | | **Delivery SLA** | By 6:00 a.m. for ACH transactions settled on the previous calendar day | > [!NOTE] > > Notification of Change (NOC) ACH entries will not be included in this report, as they do not have a monetary impact on the underlying account. ## Report Fields | **Field Name** | **Description** | **Example** | **Note** | | - | - | - | - | | Settlement Date | Date money settled/posted in account |
  • 2023-11-15
| | | Settlement Code | Fed AMI Transaction Code |
  • 5701
  • 5702
  • 5703
| This is the aggregated batch posting code shown in the description in the activity report. | | Settlement Type | For this `ach_id`, what type of settlement is performed. |
  • ORIGINATION
  • RETURN
  • DISHONORED\_RETURN
  • CONTESTED\_RETURN
| Since one `ach_id` might settle multiple times, we need a separate type to distinguish in the life cycle. Note: “Reversal” can be identified by the Statement Descriptor field and the Linked Reversal ID. | | Bank Account Id | Underlying `account_id` this ACH transaction was posted to. |
  • account\_2WxBDCONkqokrba1kD2WhYeXz2g
| Unique `account_id` on Lead’s platform. | | Bank Account Number | The root bank account number of the associated `account_id`, usually the program-level account number. |
  • 1XXXXX2854
| This will be the account numbers you can see on the online banking portal. | | Transaction Type | Money movement direction |
  • CREDIT
  • DEBIT
| | | Amount | Amount of the transaction, at dollar base unit |
  • \$1,230.45
| | | ACH ID | ID of the ACH object that was settled |
  • ach\_2XMfszvX8InZJio83Q7DtnfOLmN
| An `ach_id` can settle multiple times. See “settlement\_type” field above. | | Direction | ACH direction |
  • INCOMING
  • OUTGOING
| | | Destination Account Number | **INCOMING**: Account number used for payment attribution. This can be the account numbers on the Lead platform, including virtual account numbers. **OUTGOING**: Counterparty/receiver's account number. |
  • 21XXXXXXX24478
| This is where the virtual account number for incoming debit that you’ll use for reconciliation. | | Statement Descriptor | Entry description of the original ACH | | | | Company ID | **INCOMING**: Counterparty company id **OUTGOING**: Origination company id | | | | Company Name | Name associated with the company id | | | | Delivery Type | Intended delivery type for this ACH when created through API |
  • SAMEDAY
  • STANDARD
  • Empty
| Only available for API-created outgoing ACH. Empty for file-based outgoing ACH or incoming ACH. | | Routing Number | **INCOMING**: Lead’s receiving routing number **OUTGOING**: Receiver’s routing number | | | | Linked Reversal ACH ID | If a REVERSAL is issued against an original outgoing payment: For original payment, this field should show the `ach_id` of the corresponding REVERSAL `ach_id` For the reversal payment, this field should show the `ach_id` of the original payment. Note: For “return” `settlement_type`, the behavior of this field should match its parent `ach_id`. |
  • ach\_1XMfszvX8InZJio83Q7DtnfOoPM
| Similar concept in API – this will provide the linked `ach_id` if reversal is issued. You will use the “statement descriptor” field to identify which payment is the “reversal.” | ## Settlement Code Mapping | **Settlement Code** | **Incoming/Outgoing** **Credit/Debit** | **Settlement Time** | **Partner Description** | | - | - | - | - | | 5701 | ACH Debit Transaction Originated | 8:30 a.m. | 5701 ACH Outgoing Debit 830 ET | | 5702 | ACH Debit Transaction Received | 8:30 a.m. | 5702 ACH Incoming Debit 830 ET | | 5703 | ACH Credit Transaction Originated | 8:30 a.m. | 5703 ACH Outgoing Credit 830 ET | | 5704 | ACH Credit Transaction Received | 8:30 a.m. | 5704 ACH Incoming Credit 830 ET | | 5724 | Same Day ACH Debit Originated | 5:00 p.m. | 5724 ACH Outgoing Debit 5pm ET | | 5725 | Same Day ACH Debit Received | 5:00 p.m. | 5725 ACH Incoming Debit 5pm ET | | 5726 | Same Day ACH Credit Originated | 5:00 p.m. | 5726 ACH Outgoing Credit 5pm ET | | 5727 | Same Day ACH Credit Received | 5:00 p.m. | 5727 ACH Incoming Credit 5pm ET | | 5729 | Same Day ACH Debit Originated | 1:00 p.m. | 5729 ACH Outgoing Debit 1pm ET | | 5730 | Same Day ACH Debit Received | 1:00 p.m. | 5730 ACH Incoming Debit 1pm ET | | 5731 | Same Day ACH Credit Originated | 1:00 p.m. | 5731 ACH Outgoing Credit 1pm ET | | 5732 | Same Day ACH Credit Received | 1:00 p.m. | 5732 ACH Incoming Credit 1pm ET | | 5734 | Same Day ACH Debit Originated | 6:00 p.m. | 5734 ACH Outgoing Debit 6pm ET | | 5735 | Same Day ACH Debit Received | 6:00 p.m. | 5735 ACH Incoming Debit 6pm ET | | 5736 | Same Day ACH Credit Originated | 6:00 p.m. | 5736 ACH Outgoing Credit 6pm ET | | 5737 | Same Day ACH Credit Received | 6:00 p.m. | 5737 ACH Incoming Credit 6pm ET | # Daily Activity Source: https://docs.lead.bank/file-reference/reports/daily-activity Definition of fields provided in the Daily Activity report. ## Report Fields | **Field Name** | **Definition** | **Example** | | :- | :- | :- | | ACCOUNT\_NUMBER | Account number this activity is associated with. |
  • 1000123456
| | TRANSACTION\_DATE | Effective date of the transaction. In rare cases (positive pay late decisions) this can be prior to the posted\_date. |
  • 2026-09-12T00:00:00
| | POSTED\_DATE | Date the transaction is recorded on the account. This is when the account balance is actually impacted by this activity. |
  • 2026-09-12T00:00:00
| | DESCRIPTION | Description of the activity. For wire transactions, the reference number could be in the description. Note: Sweep descriptions can potentially contain account numbers |
  • 5736 ACH OUTGOING CREDIT 6PM ET 09/12 3167932382
  • internal\_transfer\_9lyFwCBNvIvBtSUpa956oIE4d92
  • TRANSFER FROM ALL IN CHECKING ACCOUNT 1000123456
| | DEBIT\_AMOUNT | If debit transaction, amount → |
  • 25
  • 24.6
  • 19.95
| | CREDIT\_AMOUNT | If credit transaction, amount → |
  • 25
  • 24.6
  • 19.95
| | TRANSACTION\_CODE | 1-3 digits. See [Transaction Codes](/file-reference/reports/daily-activity#transaction-codes) below. |
  • 39
  • 9
  • 875
| | CHECK\_NUMBER | Check number (if the activity is a check transaction). |
  • 12345
  • 0
| | COMPANY\_ID | The associated company ID for this transaction if this is a received ACH transaction. |
  • 9001843647
| | SEC\_CODE | The associated SEC code for this transaction if this is a received ACH transaction. |
  • CCD
  • PPD
| ## Transaction Codes The below transaction codes can be used for both debits and credits. > [!NOTE] > > “Non-Platform” transactions are initiated outside of Lead’s BaaS (banking-as-a-service) platform, such as through online banking or other external systems. > > "BaaS Platform" transactions are initiated through Lead's payment API integrations. | **Code** | **Description** | **Executed By** | | :- | :- | :- | | 9 | Deposit | Non-Platform | | 12 | ACH Return Item Fee | Non-Platform | | 14 | ACH Debit Origination | Non-Platform | | 16 | Internal Funds Transfer | Non-Platform | | 17 | Domestic Wire Incoming | Non-Platform | | 18 | Misc Credit | Non-Platform | | 19 | Online Banking Transfer | Non-Platform | | 20 | Misc Credit | Non-Platform | | 22 | Interest Credit | Non-Platform | | 26 | ACH Credit Received | Non-Platform | | 27 | ACH Debit Received | Non-Platform | | 28 | Return of ACH Credit Received | Non-Platform | | 29 | Return of ACH Debit Received | Non-Platform | | 30 | ACH Debit Reversal Origination | Non-Platform | | 31 | ACH Credit Reversal Origination | Non-Platform | | 32 | ACH Debit Reversal Received | Non-Platform | | 35 | ACH Credit Reversal Received | Non-Platform | | 37 | Miscellaneous | BaaS Platform | | 38 | Domestic Wire Origination | Non-Platform | | 39 | Online Banking Transfer | Non-Platform | | 47 | ACH Credit Origination | Non-Platform | | 50 | Check Chargeback | Non-Platform | | 51 | Check | Non-Platform | | 52 | Check | Non-Platform | | 53 | ACH Transfer Fee | Non-Platform | | 54 | Domestic Incoming Wire Return | Non-Platform | | 55 | Domestic Originated Wire Return | Non-Platform | | 60 | Return of ACH Debit Origination | Non-Platform | | 61 | Closing Withdrawal | Non-Platform | | 69 | Analysis Fee | Non-Platform | | 70 | Return of ACH Credit Origination | Non-Platform | | 75 | Transfer | Non-Platform | | 77 | ACH Return Fee | Non-Platform | | 110 | Stop Payment Fee - Online Banking | Non-Platform | | 119 | Paper Statement Fee | Non-Platform | | 120 | NSF Fee | Non-Platform | | 400 | General Ledger Credit | BaaS Platform | | 500 | General Ledger Debit | BaaS Platform | | 614 | ACH Onus Incoming Payment | Non-Platform | | 628 | ACH Onus Incoming Return Debit | Non-Platform | | 629 | ACH Onus Incoming Return Credit | Non-Platform | | 647 | ACH Onus Incoming Collection | Non-Platform | | 800 | Sweep | Non-Platform | | 822 | IntraFi Sweep In | Non-Platform | | 823 | IntraFi Sweep Out | Non-Platform | | 824 | IntraFi Interest Credit | Non-platform | | 900 | Finplat Multi-Leg Transactions | BaaS Platform | | 910 | Miscellaneous Fees | BaaS Platform | | 911 | Miscellaneous Interest | BaaS Platform | | 912 | Miscellaneous IntraFi Sweeps | BaaS Platform | | 913 | Miscellaneous Lead Generated | BaaS Platform | | 937 | Miscellaneous, Platform use | BaaS Platform | | 1014 | ACH Debit Origination | BaaS Platform | | 1015 | Return Item Credit | BaaS Platform | | 1016 | Internal Transfer | BaaS Platform | | 1017 | Domestic Wire Incoming | BaaS Platform | | 1026 | ACH Credit Received | BaaS Platform | | 1027 | ACH Debit Received | BaaS Platform | | 1028 | Outgoing ACH Credit Return | BaaS Platform | | 1029 | Outgoing ACH Debit Return | BaaS Platform | | 1030 | ACH Debit Reversal Origination | BaaS Platform | | 1031 | ACH Credit Reversal Origination | BaaS Platform | | 1032 | ACH Debit Reversal Received | BaaS Platform | | 1035 | ACH Credit Reversal Received | BaaS Platform | | 1038 | Domestic Wire Origination | BaaS Platform | | 1047 | ACH Credit Originated | BaaS Platform | | 1050 | Incoming Check Return | BaaS Platform | | 1051 | Incoming Check Forward | BaaS Platform | | 1052 | Check | BaaS Platform | | 1054 | Domestic Incoming Wire Return | BaaS Platform | | 1055 | Domestic Originated Wire Return | BaaS Platform | | 1060 | ACH Chargeback | BaaS Platform | | 1064 | International Wire Origination | Non-Platform | | 1070 | ACH Credit Back | BaaS Platform | | 1071 | International Wire Incoming | Non-Platform | | 1072 | International Incoming Wire Return | Non-Platform | | 1073 | International Originated Wire Return | Non-Platform | | 1074 | Outgoing Check Forward | BaaS Platform | | 1075 | Book Transfer | BaaS Platform | | 1250 | FedNow Incoming Credit | BaaS Platform | # Daily Balance Source: https://docs.lead.bank/file-reference/reports/daily-balance Definition of fields provided in the Daily Balance report. ## Report Fields | **Field Name** | **Definition** | **Example** | | - | - | - | | ACCOUNT\_NUMBER | Account number this activity is associated with. |
  • 1000123456
| | ACCOUNT\_NAME | Owner of the account. Name in our core system for the Account. |
  • PARTNERNAME
| | ACCOUNT\_TITLE | Short description of the account on our core system. Usually reflects the account’s usage. |
  • OPERATING ACCOUNT
| | AS\_OF\_DATE | Business Date of balance summary. |
  • 2024-09-12T00:00:00
| | BEGINNING\_BALANCE | Balance at the start of the `AS_OF_DATE` |
  • 123456
  • 123456.7
  • 123456.78
| | ENDING\_BALANCE | Balance at the close of the `AS_OF_DATE` |
  • 123456
  • 123456.7
  • 123456.78
| # Network Settlement Reports Source: https://docs.lead.bank/file-reference/reports/network-settlement-reports Lead's network settlement reports explained. > [!TIP] > > It's important to share the details in these reports with your issuer processor to confirm the expected formats — ensuring the reporting setup with each network is configured to Lead’s specifications. > [accordion] Visa > > The report Lead requires on a daily basis from Visa is the VSS-115 report. Typically, issuer processors will deliver a suite of reports, of which the VSS-115 report is a single one. Lead can accept any number of reports, as long as the one that contains VSS-115 data is specified according to the below requirements: > > | **VSS-115 Report** | **Description** | > | - | - | > | Folder | `/network-settlement/visa` `/network-settlement/interlink` (if Interlink is the secondary network) | > | File Format | VSS-115 | > | Filename Convention | `{processing_date}_vss_{timestamp}.txt` where processing\_date is in the format yyyy-mm-dd and represents the date for which the report was generated. If this convention cannot be met, then Lead requires at minimum the filename to contain the date of the report plus a unique identifier for the file format. Please share this convention with the Client Implementations team once finalized. | > | Frequency | Once per calendar day | > > #### Additional Details > > Lead also requires the relevant FTSRE ID in order to parse the correct data from the VSS-115 file. The Funds Transfer Settlement Reporting Entity (FTSRE) is the level at which Visa aggregates reports. > > For example, Issuer Processor A may have three different BIN programs, each at a different partner bank: > > **Issuer Processor A: FTSRE 100** > > * Lead Bank Debit/Prepaid BINs: FTSRE 101 > * FTSRE 201 (Debit/Prepaid BIN 1) > * FTSRE 202 (Debit/Prepaid BIN 2) > * Lead Bank Credit BINs: FTSRE 102 > * FTSRE 203 (Credit BIN 1) > * FTSRE 204 (Credit BIN 2) > * Bank partner B: FTSRE 103 > * Bank partner C: FTSRE 104 > > In the above example, FTSRE 100 will be the sum of FTSRE 101, FTSRE 102, and FTSRE 103. Then, FTSRE 101 is the sum of the FTSREs below it and so on and so forth. For this example, Lead is interested in FTSRE 101 for the debit/prepaid BINs, which represents all of the activity for a given drawdown related to those BINs. > > However, if one of the BINs is a credit BIN, then the FTSRE must be distinct from the debit/prepaid activity. In the example above, FTSRE 101 represents the debit/prepaid activity, and one set of network settlement accounting entries is run for that. Then, FTSRE 102 represents the credit activity, which triggers a separate set of network settlement accounting entries. > [accordion] Mastercard > > Due to Mastercard’s setup, there are two reports Lead requires in order to settle with the network: > > | **T140 Report** | **Description** | > | - | - | > | Folder | /network-settlement/mastercard | > | File format | T140 | > | Filename convention | `T140_{YYYY-MM-DD}_mastercard_{X}_{timestamp}.txt` X is the clearing cycle, from 1 to 6. | > | Frequency | Six times per calendar day | > > | **T461 (SWCHD363) Report** | **Description** | > | - | - | > | Folder | `/network-settlement/mastercard` | > | File Format | T461 (SWCHD363) | > | Filename Convention | `T461_{YYYY-MM-DD}_mastercard_{00X}_{timestamp}.txt` | > | Frequency | Two times per calendar day | > > #### Additional Details > > Since multiple files are required for Mastercard, Lead waits until all of these files are present before aggregating across them all to get the relevant data points we need. In addition to the presence of three different files required for Lead, there are two more nuances to call out for Mastercard. > > The first is the notion of Interbank Card Association number (ICA). The ICA is an identifier for which Mastercard uses to aggregate reporting as well as perform drawdowns. This means that multiple BINs can report on the same ICA, which means a drawdown on that ICA will cover all BINs. Similarly, reporting will roll up to that ICA as well. From Lead Bank’s perspective, ICAs can cover multiple BINs of the same type; credit and debit/prepaid BINs must live under separate ICAs. > > The second is the number of cycles per day that the BINs are configured for. Lead prefers all 6 cycles to be used, if possible. > > > [!NOTE] > > > > **Credit-Only Programs** > > > > Lead still requires receiving T461 files. It is acceptable in this case for these files to be empty, including without headers. > [accordion] Maestro > > The report Lead requires on a daily basis from Maestro is the SWCHD363 report. Typically, issuer processors will deliver a suite of reports, of which the SWCHD363 report is a single one. Lead can accept any number of reports, as long as the one that contains SWCHD363 data is specified according to the below requirements: > > | **SWCHD363 Report** | **Description** | > | - | - | > | Folder | `/network-settlement/maestro` | > | File Format | SWCHD363 | > | Filename Convention | `T461_{yyyy-mm-dd}_maestro_{00X}_reports_{timestamp}.txt` | > | Frequency | Once per calendar day | > > #### Additional Details > > Since Maestro is under the Mastercard umbrella, Mastercard will be generating this file. Note that this file is also part of the same suite of reports delivered when Mastercard is the primary BIN. > > > [!WARNING] > > > > **Exception Items** > > > > Can be included in this report where a transaction clears on settlement\_date T, but then is also reversed the same day. As a result, the gross spend of that transaction is included in the transaction amount while the gross reversal is included in the refund amount. This means that both transactions need to be reported to Lead in order to pass reconciliation. > [accordion] Interlink > > Since Visa owns Interlink, network settlement reporting follows the same patterns as Visa: > > | **VSS-115 Report** | **Description** | > | :- | :- | > | Folder | `/network-settlement/visa` `/network-settlement/interlink` (if Interlink is the secondary network) | > | File Format | VSS-115 | > | Filename Convention | `{processing_date}_vss_{timestamp}.txt` where processing\_date is in the format yyyy-mm-dd and represents the date for which the report was generated. If this convention cannot be met, then Lead requires at minimum the filename to contain the date of the report plus a unique identifier for the file format. Please share this convention with the Client Implementations team once finalized. | > | Frequency | Once per calendar day | > [accordion] Pulse > > The report Lead requires on a daily basis from Pulse is the PRC643 report. Typically, issuer processors will deliver a suite of reports, of which the PRC643 report is a single one. Lead can accept any number of reports, as long as the one that contains PRC643 data is specified according to the below requirements: > > | **PRC643 Report** | **Description** | > | - | - | > | Folder | `/network-settlement/pulse` | > | File Format | PRC643 | > | Filename Convention | `{YYYYMMDDXXXXXX}_{program_name}_PRC643.txt` | > | Frequency | Once per calendar day | > > #### Additional Details > > Pulse has one nuance that affects reconciliation and cashflows. While the PRC643 report aligns with a given settlement date T, the actual funds movements happen either the next business day (T+1BD) or two business days later (T+2BD) depending on the purpose of funds: > > | **PULSE Settlement Day(00:00:00 - 23:59:59 CT)** | **Funds Will Settle via Wire or Wire Drawdown on This Day** | **Fees, IPF & Disputes System Will Settle via ACH on This Day** | > | - | - | - | > | Monday | Tuesday | Wednesday | > | Tuesday | Wednesday | Thursday | > | Wednesday | Thursday | Friday | > | Thursday | Friday | Monday | > | Friday | Monday | Monday | > | Saturday | Monday | Monday | > | Sunday | Monday | Tuesday | > > As long as Lead receives the PRC643 file T+1 of the settlement date T, Lead manages this complexity behind the scenes, resulting in the following nonstandard behavior: > > * On T+1BD > * Lead transfers funds representing the net amount of transaction spend (gross spend - gross refunds) from the source of funds to the network settlement account > * Pulse requests via drawdown the same amount of funds > * On T+2BD > * Pulse settles via ACH the aggregate amount of net interchange, net disputes, and net fees to the network settlement account > * Lead transfers the respective funds to the corresponding destination account > > From a reporting standpoint, nothing changes from your perspective: You'll continue to report the settlement date for each transaction, which aligns with the settlement date that Pulse generates the PRC643 report for. > > > [!WARNING] > > > > The settlement date from Pulse’s perspective is not the date for which funds are transferred but rather the date for which transactions are cleared. # Daily Reporting Files Overview Source: https://docs.lead.bank/file-reference/reports/overview Overview of Lead's daily SFTP reporting files: Daily Balance, Daily Activity, and ACH Cash Reconciliation, including delivery times and holiday handling. Daily Balance and Activity Reports together give a daily overview of the activity within accounts. The balances and transactions contained in the reports will match the monthly bank statements you receive. > [!TIP] > > Reports are delivered to your SFTP folder: `bank-account-reports/` ## Report Summaries | **Report** | **Description** | Delivery Time | | - | - | - | | [Daily Balance](/file-reference/reports/daily-balance) | Details the opening and closing balance of account(s) at the business date (posting date) level. Multiple accounts can be included on this report. This report is comma delimited. | Daily by 7:00 a.m. CT | | [Daily Activity](/file-reference/reports/daily-activity) | Details each individual transaction that occurred on the account(s) within that business date (posting date). Multiple accounts can be included on this report. The report contains: transaction code, debit and credit amount, and other supplemental information for transactions when supported (such as Company ID for external ACH). The transactions for an account within this report can be aggregated to reconcile opening and closing balances supplied in the Daily Balance report. Business days with no activity will not generate a report for that day. This report is comma delimited. | Daily by 7:00 a.m. CT | | [ACH Cash Reconciliation](/file-reference/reports/ach-cash-reconciliation) | Because ACH settlements are processed in aggregated or batched form, we provide this report with transaction-level ACH details to help reconcile them with the aggregated settlements shown on your bank statement. Unlike the other two reports, Settlement Cash Reconciliation is pipe delimited. | Daily by 3:00 a.m. CT | ## Report Delivery Lead's platform does not perform updates or produce reports on weekends. Transactions from Saturday and Sunday are batched and processed with the next business day's update, appearing in that day's report with the next business day as the posted date. This means you'll receive one file on Monday showing all weekend and Monday transactions with a Monday posted date. > [!WARNING] > > Intra-day reports are not available. > [!NOTE] > > Lead's platform does not perform updates or produce reports on [bank holidays](https://www.frbservices.org/about/holiday-schedules). Transactions from these dates are processed with the next business day's update and reflected in that day's report. If you are using ACH services, you will receive an **ACH Settlement Cash Reconciliation** report each calendar day for the prior day's settled ACH transactions. Because ACH settlements occur only on business days, the report will contain no data rows (only headers) on bank holidays. This report includes ACH transactions settled between 12:00 a.m. CT and 11:59:59 p.m. CT. > [!NOTE] > > Notification of Change (NOC) ACH entries will not be included in this report, as they do not have a monetary impact on the underlying account. ## Report Naming All reports are in csv format. They can be found in the [SFTP file structure](/file-reference/sftp-setup) under **bank-account-reports**: * YYYY-MM-DD\_\[partnername]-daily-activity-report\_\[epoch].csv * YYYY-MM-DD\_\[partnername]-daily-balance-report\_\[epoch].csv * YYYY-MM-DD\_\[partnername]-ach-cash-recon-report\_\[UNIQUE-POSTFIX].csv # Platform Reconciliation Source: https://docs.lead.bank/file-reference/reports/platform-reconciliation Reconciliation for platform-issued account numbers. > [!NOTE] > > This guide details how reconciliation works for partners with platform-issued account numbers. ## Overview ACH transactions are processed in batches during scheduled settlement windows. Settlements occur at the underlying FBO account level, including transactions initiated or received by partners through platform account numbers via API or file. Within online banking, statements, and Lead-generated daily transaction files, you'll see bulk settlements rather than individual payment details. For platform account number reconciliation, utilize [webhooks and ACH events](/api-reference/endpoint/events/retrieve-an-event) (for real-time monitoring) combined with Lead-generated [ACH Cash Recon](/file-reference/reports/ach-cash-reconciliation) reports, to obtain transaction-level details. > [!TIP] > > While Lead-generated daily activity reports include transactions posted to an underlying account via online banking, ACH Cash Recon reports only include ACH entries associated with platform account numbers and will not include ACH transactions initiated or posted outside of the platform. ## Same Day vs. Next Day Settlement The [processing windows](/products/ach/timing) set expectations on settlement time for ACH outgoing, and also set approximate expectations on when settlements should happen for inbound. > [!CAUTION] > > Any outgoing Same Day ACH submitted after the same-day cutoff of 3:15 p.m. CT will settle at 7:30 a.m. CT the next business day. ## Recon For API Messages follow [ACH status](/products/ach/statuses) patterns. ### Incoming ACH Transitions ```mermaid theme={null} graph LR subgraph Manual Review under_review --> approved under_review --> rejected end approved --> posted scheduled -->|If required| under_review scheduled --> posted posted -.->|If return initiated| pending_return pending_return -.->|If return successful| returned pending_return -.->|If return not successful| posted classDef classy stroke:#555,fill:#F4F6F8,rx:12,ry:12,font-size:16px,font-weight:bold; classDef arrows stroke-width:2px; class scheduled,canceled,processing,submitted,posted,returned,under_review,rejected,approved,pending_return classy; ``` ### Outgoing ACH Transitions ```mermaid theme={null} graph LR subgraph Manual Review under_review --> approved under_review --> rejected approved --> canceled under_review --> canceled end scheduled -->|If required| under_review scheduled --> processing scheduled --> canceled approved --> processing processing --> submitted submitted --> posted posted -.->|If returned| returned classDef classy stroke:#555,fill:#F4F6F8,rx:12,ry:12,font-size:16px,font-weight:bold; class scheduled,canceled,processing,submitted,posted,returned,under_review,rejected,approved classy; ``` Except in rare validation or compliance-related circumstances where funds are moved to `under_review`, inbound payments will transition from `scheduled` to `posted` quickly, and webhooks sent for each status update may be helpful for different use cases. Outbound ACHs initiated via API or files go through the status changes detailed above. Lead sends webhooks containing queryable events for every status change in an inbound or outbound ACH. > [!TIP] > > Events that fire a status = `posted` and the event’s `created_at` date.timestamp is the source of truth for when funds are available at the platform account number level. It should **not** be expected that this time will coincide with batch settlements at the Fiserv level with any useful predictability. ## Using SFTP Reports & Online Banking For Reconciliation The posted events reported in webhooks will coincide with individual transactions detailed in the [ACH Cash Recon Report](/file-reference/reports/ach-cash-reconciliation), which is dropped in your [SFTP directory](/file-reference/sftp-setup) between 3:00 a.m. and 6:00 a.m. CT the following calendar day. At the online banking level, Lead posts ACH payments to your underlying account in batches, as part of a net settlement during settlement windows. There are four possible batches for each window, each with its own unique AMI code, grouped as: * incoming debits * incoming credits * outgoing debits * outgoing credits ### Example Steps **Outgoing API Credit Transaction** **1. First** On Feb 26 at 2:00 p.m. CT, you call POST ACH of \$100 for next day settlement and generate a record in status `scheduled`. * The API response will be a 200 and not a 202, as the creation of the payment record is asynchronous. * A webhook will notify of all status changes. * If a webhook for status `manual review`, Lead may ultimately reject or accept, and will send webhooks to notify of every status update in these and all cases. **2. Second** Three more next-day settlement ACHs are submitted: \$200, \$300, and \$400, which are all in `scheduled` status unless and until they complete. * Behind the scenes, these payments are submitted in batch at the next available Fed window, governed by an effective\_date we provide based on your selection of same-day or next-day processing. **3. Third** At 7:30 a.m. CT on Feb 27, Lead will receive a confirmation file from the Fed, informing us of settled payments. **4. Fourth** Between 7:30 and 8:00 a.m. on Feb 27, Lead updates each of next-day settlement submissions from Feb 27 to a `posted` status, triggering webhooks, allowing for immediate recon. > [!TIP] > > All files delivered to your SFTP folder on February 27 contain details only for February 26 settlements. As a result, none of the February 27 payments will appear in these files. In online banking, you will see a single aggregated settlement of \$1,000 representing the four payments, without individual transaction details. **5. Fifth** On Feb 28, the ACH Cash Recon report including Feb 27 settlements will show the breakdown that includes each transaction. Likewise the transactions will be included in the Feb 28 Daily Transactions file dropped by Lead, but as a \$1000 bulk settlement, just like what’s been visible in the Portal UI since the morning of Feb 27. ## Settlement Exceptions **Manual Adjustments** Lead’s Payment Operations team may need to perform a fully manual ACH adjustment. These individual “monetary adjustment” entries will appear as single line items in the Lead-generated daily transaction report. **Inbound ACH Payments** Entry-level validations may capture and handle issues, which can include: * If targeted account\_number does not exist on our platform, or a platform account\_number is used with a Fiserv routing number, Lead will turn these payments around as returns with reason “account not found,” so that partners will not expect to see activity in any report nor as a webhook/event. * A payment moves from `scheduled` to `under_review` on T, and remains under review until T+1; then moves to `posted` on T+1. This will produce the webhook and `created_at` date.time stamp for T+1 and will show in the ACH Cash Recon report on T+2 for T+1 transactions. * Example: Target account\_number is in `inactive` status, and the partner is prompted to reactivate the account\_number to receive the payment. # Sales Request Schema Source: https://docs.lead.bank/file-reference/sales/request-schema Field-level reference for the daily Sales Request file Lead delivers, listing the receivables to purchase and the settlement amount. > [!NOTE] > > **API successor in flight.** The daily receivables sale is moving from this file exchange to a Sale API — a daily sale object with webhooks. The daily cycle is unchanged; this schema is authoritative until the successor is Released. > [!NOTE] > > Sales Requests are a Lead-generated file with details on the sale of receivables. While Lead does not sell receivables on non-business days, an empty Sales Request file will still be posted to the SFTP on non-business days. > [!NOTE] > > Lead offers two balance sheet models: Originate-to-Sell (OTS) and On-Sheet Lending (OSL). Under OTS, Lead sells receivables to the partner after the applicable hold period. Under OSL, Lead retains receivables on its own balance sheet through the loan's terminal status rather than selling them. > > Sales Request files only contain receivables designated as OTS. If there are no OTS receivables on a given day, the file will be empty. > [!TIP] > > Ensure that the `settlement_amount` has been sent to the Operating Account prior to responding via Sales Response. | **Field** | **Description** | **Required** | **Data Type** | | - | - | - | - | | sale\_id | Lead-generated ID for sales of balances | Required | string | | balance\_id | The ID of the balance whose receivables are being sold this day. If there were multiple loans disbursed against the same balance\_id, Lead will display this as one entry aggregated by balance\_id. | Required | string | | start\_date | The date when interest accrual starts. This will be settlement\_date from the `Transaction` file. | Required | date `YYYY-MM-DD` | | sale\_date | The date of sale of receivables. | Required | date `YYYY-MM-DD` | | funded\_amount | Amount funded by Lead. | Optional | number amount in major currency units with up to the currency’s supported decimal precision; trailing zeros are removed | | outstanding\_principal | The outstanding principal of loan amount reflecting for customer activity on loan. | Required | number amount in major currency units with up to the currency’s supported decimal precision; trailing zeros are removed | | settled\_transactions\_amount | The sum value of transactions (in a settled state) that reduced a receivable's outstanding principal amount during the seasoning period. For example, any payments or credits that have been made against the receivable and brought down its principal amount would be included. | Required | number amount in major currency units with up to the currency’s supported decimal precision; trailing zeros are removed | | imputed\_interest\_accrued | The net imputed interest charged by Lead during the loan holding period. | Required | number decimal value with up to 6 fractional digits; trailing zeros are removed | | settlement\_amount | The net amount required to settle with Lead on the sale date for this loan. This is the amount that needs to be transferred prior to responding to Sales Response. | Required | number decimal value with up to 6 fractional digits; trailing zeros are removed | | currency | The [currency code](/file-reference/delivery/currencies) for the transaction. | Required | [ISO4217](https://www.iso.org/iso-4217-currency-codes.html) | | generated\_at | The day this file is generated. This should always be the date the file is sent to Lead Bank. | Required | datetime ISO8601 | | effective\_at | The timestamp of when the related object(s) were polled to collect the information for this record. This is always set to an end-of-day timestamp on the day before the file's date. E.g., if a Sales Request file is dated 2025-12-31, this timestamp will be set to `2025-12-30T23:59:59Z`. | Required | datetime ISO8601 | # Sales Response Schema Source: https://docs.lead.bank/file-reference/sales/response-schema Field-level reference for the Sales Response file you submit to confirm the day's receivables purchase. > [!NOTE] > > **API successor in flight.** The daily receivables sale is moving from this file exchange to a Sale API — a daily sale object with webhooks. The daily cycle is unchanged; this schema is authoritative until the successor is Released. > [!NOTE] > > This file is generated by you and outlines the acceptance or rejection of the Sales Request file. > [!NOTE] > > Lead offers two balance sheet models: Originate-to-Sell (OTS) and On-Sheet Lending (OSL). Under OTS, Lead sells receivables to the partner after the applicable hold period. Under OSL, Lead retains receivables on its own balance sheet through the loan's terminal status rather than selling them. > > Sales Response files only contain entries for receivables designated as OTS. If the corresponding Sales Request contains no OTS receivables, the Sales Response will also be empty. > [!TIP] > > Ensure that the `settlement_amount` has been sent to the Operating Account prior to responding via Sales Response. > [!TIP] > > For all optional fields where you do not plan to pass through data, please include the header and an empty value. ## Schema | **Field** | **Description** | **Required** | **Data Type** | | - | - | - | - | | sale\_id | Lead-generated ID for sales of balances | Required | string | | purchasing\_entity | The legal name of the entity purchasing this receivable | Optional | string | | response | enum `accepted` `rejected` | Required | enum `accepted` `rejected` | | reject\_reason | Description for rejection of the sale. | Required if `response` = `rejected` | string | | generated\_at | The day this file is generated. This should always be the date the file is sent to Lead Bank. | Required | datetime ISO8601 | | effective\_at | The timestamp of when the related object(s) were polled to collect the information for this record. | Required | datetime ISO8601 | ## Sandbox Behavior In the first few days of Sandbox testing where you first begin creating loans, all loans will be within the "hold period" (i.e., still owned by Lead), meaning there will be no loans to be sold from Lead to you. During this period, Lead's Sandbox environment generates empty Sales Request Files and posts them to your [SFTP](/file-reference/sftp-setup) folder, beginning on [Day 0.](/get-started/sandbox#what-to-test-before-go-live) This facilitates testing of the end-to-end process. You are expected to send empty Sales Response Files during this period, also beginning on Day 0. This process continues until the hold period of the first loan(s) that you created ends, and a true "sale" is ready to be made from Lead to you, meaning the Sales Request File is populated with a loan record. If the first loan(s) created is on Day 1, then this typically occurs on Day 4. For any subsequent days where the Sales Request is empty (e.g., no loans were created in preceding days), you should continue to send empty Sales Response Files to complete the end-to-end Sandbox testing workflow. For OSL programs, no receivables will ever be designated as OTS, so Sales Request and Sales Response files will always be empty in both Sandbox and Production. This is expected behavior. # SFTP Setup Source: https://docs.lead.bank/file-reference/sftp-setup Steps for setting up SFTP with Lead. **1. Generate Keypair** Use the following command: `ssh-keygen -t [rsa|ecdsa|ed25519]` The following keys are accepted: * `rsa` * `ecdsa` * `ed25519` Once generated, you'll have access to a public key (in a `.pub` file). Run `cat ` to view the public key to send to Lead. **Example Public Key** ```text theme={null} ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABgQDJOuq4BpCsr4KQyPd06oGNJyV5rWmpV7QjWAWz8imZIC27MypB37p9ahFUqlaT80qKIeoR8Zb/uamvdMxp9yKThjbvVKXUpPb0LmwGk3Dxnm0bdR21vrgujje3Y5kD3DJKOLNMuKGEzc6tU0F0l4BXE8PoW0VWRx+A0QWsVPhULzXuuEE51WqYE+Aru0UWEpJnC+HF2QcuWPfKfU6xiZ5Skma3DH5cLrGUKiv7jMyfEKBzPSmtO4cYvS6Mc1L6DbH33mBGu476r4ptzTqjP9T1MZdfubyCRLQTtPDIUSbJ0C0c8RFBwm3AePrbmZtbCymVlkaL8De9gRqTg2+cNox2oL30xOxStxGX/8t1Rs7L00jFgLAd18cyeyFSyCUJbRVlNuHzPW0DROwf7KO7kvHYSvisUYYT+oM7Ye0mLmrux7JBvuaR1uYOkC3ux+D9mt/LZH7iEJGlhEcTsJSQjftBtot1bvPicnpT599xym3GVCAx59YSO4qU6tu0D27u2o0= user@user-MW7DGQQ445 ``` **2. Send Public Key To Lead** Once your public key has been generated, send it to your Lead Implementation Manager as a plain text email. **3. Validate Lead Public Key (Host Key Generation)** Verify the fingerprint and add the public key to your ***known\_hosts*** file by following the below steps: 1. Generate a public key fingerprint by running the below command: > [tab] Prod > > ssh-keyscan [sftp.lead.bank](http://sftp.lead.bank) 2>&1 | ssh-keygen -lf - > [tab] Sandbox > > ssh-keyscan [sftp.sandbox.lead.bank](http://sftp.sandbox.lead.bank) 2>&1 | ssh-keygen -lf - > [!NOTE] > > The above command generates a public key fingerprint 2. Use the public key fingerprint and compare it with the fingerprint below: > [tab] Prod > > 2048 SHA256:PWqq5lPPd0zWCawxwSnqOkyy168esipmaPy2t3H1uFE [sftp.lead.bank](http://sftp.lead.bank) (RSA) > [tab] Sandbox > > 2048 SHA256:rCdk4LeHvxn5G3j7VDJvqH6oEMh844E7sHxoaxih2dE [sftp.sandbox.lead.bank](http://sftp.sandbox.lead.bank) (RSA) **4. Add Lead Public Key To Your Known Hosts file** After the fingerprint is verified, run the below command to add the public key to your ***known\_hosts*** file: > [tab] Prod > > ssh-keyscan [sftp.lead.bank](http://sftp.lead.bank) >> \~/.ssh/known\_hosts > [tab] Sandbox > > ssh-keyscan [sftp.sandbox.lead.bank](http://sftp.sandbox.lead.bank) >> \~/.ssh/known\_hosts **5. Connect To SFTP Server** Connect by running the following command: > [tab] Prod > > sftp -v -i \\\~/.ssh/your\\\_key [username@sftp.lead.bank](mailto:username@sftp.lead.bank) > [tab] Sandbox > > sftp -v -i \\\~/.ssh/your\\\_key [username@sftp.sandbox.lead.bank](mailto:username@sftp.sandbox.lead.bank) > > > [!TIP] > > > > **Tips** > > > > * Replace `~/.ssh/your_key` with the path to your key generated in step 1 > > * Replace `username` with the username provided by Lead ## Connectivity Details | **Environment** | **SFTP Server Hostname** | **Port** | | - | - | - | | Sandbox | [sftp.sandbox.lead.bank](http://sftp.sandbox.lead.bank) | 22 | | Production | [sftp.lead.bank](http://sftp.lead.bank) | 22 | > [!TIP] > > **Set-up Checks** > > * Static IP addresses are strongly encouraged for the [IP allowlist](/api-integrations/using-the-api/authentication#ip-allowlist). > * CSV files should use a pipe (|) delimiter. > * You may provide multiple SSH public keys for each environment. > * Lead supports RSA, ECDSA, and ED25519 keys. > * Both 2048 and 4096 bits are supported. > * It is strongly recommended to do periodic key rotation. > * Rotation of these keys can be processed upon request. ## Folder Structure All program related files will be dropped into folders on the SFTP server with the following access: * **Read/Write:** For all folders where you are the submitter * **Read Only:** For folders where Lead is the submitter > [!NOTE] > > We do not use the root directory of the SFTP server to store or handle files. > [!WARNING] > > **Missing Directories?** > > When your SFTP is initially set up, you may not see all directories. > > Create the required directories by uploading a file to the desired path. > [!NOTE] > > All dates in filenames must use the `YYYY-MM-DD` format (e.g., `2025-12-31`). | **File** | **Submitter** | **Folder Name** | **File Example** | | - | - | - | - | | Customer | You | customer | `2025-12-31_customer_v1.csv` | | Customer Relationship | You | customer-relationship | `2025-12-31_customer_relationship_v1.csv` | | Authorized Users | You | authorized-users | `2025-12-31_authorized_users_v1.csv` | | Applications | You | applications | `2025-12-31_applications_v1.csv` | | Accounts | You | accounts | `2025-12-31_accounts_v1.csv` | | Cards | You | cards | `2025-12-31_cards_v1.csv` | | Documents | You | documents | Refer to `Documents` row in `Customer` `Applications` `Accounts` `Balances` data schema | | Deposit Balances | You | balances/deposit | `2025-12-31_balances_v1.csv` | | Deposit Transactions | You | transactions/deposit | `2025-12-31_transactions_v1.csv` | | Credit Balances | You | balances/credit | `2025-12-31_balances_v1.csv` | | Credit Transactions | You | transactions/credit | `2025-12-31_transactions_v1.csv` | | Non-Posted Transactions | You | non-posted transactions/deposit | `2025-12-31_non_posted_transactions_v1.csv` | | Transactions Update | You | transactions-update/deposit | `2025-12-31_transactions_update_v1.csv` | | Collaterals | You | collaterals | `2025-12-31_collaterals_v1.csv` | | Network Settlement (Primary) | You or Issuing Processor | network-settlement/\ Example: *network-settlement/visa* | Format varies based on network. | | Network Settlement (Secondary) | You or Issuing Processor | network-settlement/\ Example: *network-settlement/maestro* | Format varies based on network. | | Sales Request | Lead | sales-request | `2025-12-31_sales_request_v1.csv` | | Sales Response | You | sales-response | `2025-12-31_sales_response_v1.csv` | | ACH Outgoing | You | ach/outgoing | `2025-12-31_outgoing_ach_v1.ach` | | ACH Failed | Lead | ach/failed | `2025-12-31_outgoing_ach_v1.ach` | | ACH Incoming | Lead | ach/incoming | `2025-12-31_incoming_ach_return_noc_v1.ach` `2025-12-31_incoming_ach_return_v1.ach` `2025-12-31_incoming_ach_noc_v1.ach` `2025-12-31_incoming_ach_forward_v1.ach` | | ACH Processed | Lead | ach/processed | `2025-12-31_outgoing_ach_v1.ach` | | Daily Activity Report | Lead | bank-account-reports | `2025-12-31_[partnername]-daily-activity-report_[epoch].csv` | | Daily Balance Report | Lead | bank-account-reports | `2025-12-31_[clientname]-daily-balance-report_[epoch].csv` | | ACH Cash Recon Report | Lead | bank-account-reports | `2025-12-31_[clientname]-ach-cash-recon-report_[UNIQUE-POSTFIX].csv` | ## File Naming We utilize a consistent filename format that aims to: * Indicate the type of file * Indicate the content represented in the particular file * Prevent filename collisions for similar files #### **Example File Format** `20260115T171640Z_incoming_ach_forwards_1768497400.ach` | **20260115T171640Z** | **incoming\_ach\_forwards** | **1768497400** | | - | - | - | | Content Identifier | File Type | Epoch Time of File Generation | | This will correspond to the content of the file. For loan origination files, this will be a date. For ACH files, this will be a date and time. | This indicates the meaning and format of the file. | This serves to prevent similar files from colliding and preserves generation time ordering for similarly named files. | > [!TIP] > > File versions can be represented by either an epoch timestamp (not ISO 8601) or an incremental version label such as v1, v2, etc. Each subsequent submission must use a higher version value. #### Example Invalid File Name If the initial file version is invalid or changes are required, you must submit the updated version of the file — with an updated epoch time of version label, such as "v2". | **Original** | 20260115T171640Z\_incoming\_ach\_forwards\_**1768497400**.ach | | - | :- | | **Updated Resubmission** | 20260115T171640Z\_incoming\_ach\_forwards\_**1768642400**.ach *Notice the updated epoch timestamp* | ## Common Pitfalls You may receive the below error if your **key permissions are too open**: > [!CAUTION] > > Permissions 0777 for '/Users/username/.ssh/id\_rsa' are too open. It is recommended that your private key files are NOT accessible by others. This private key will be ignored. This error indicates that your public key is read/writable by any system user rather than just the current user. You may resolve this error by running: `chmod 600 ~/.ssh/id_rsa` # Which Files Does My Program Use? Source: https://docs.lead.bank/file-reference/which-files One table mapping program types to the SFTP files you submit and the reports Lead delivers — everything not listed here is an API. Every Lead program shares one SFTP pipeline. Which files flow through it depends on what you're building. Find your program type below; everything not listed in your row is an API ([Integration Surfaces by Product](/core-concepts/platform/integration-surfaces-by-product)). All rows share the same mechanics: files due by **6:00 a.m. CT** the business day after the activity, empty files on days with nothing to report, and [Slack alerts](/file-reference/delivery/slack-alerts) confirming success or naming [validation errors](/file-reference/delivery/errors). | **Program type** | **Files you submit** | **Reports Lead delivers** | | :- | :- | :- | | Deposit program | Daily [Balances](/file-reference/balances-and-transactions/balances-schema), [Transactions](/file-reference/balances-and-transactions/transactions-schema), and [Non-Posted Transactions](/file-reference/balances-and-transactions/non-posted-transactions-schema) | [Daily Balance](/file-reference/reports/daily-balance) · [Daily Activity](/file-reference/reports/daily-activity) · [ACH Cash Reconciliation](/file-reference/reports/ach-cash-reconciliation) *(if you originate ACH)* | | Deposit + debit card | Deposit-program set, plus network settlement files from your issuer processor ([formats](/file-reference/reports/network-settlement-reports)) | Deposit-program set | | Credit / charge card (Originate-to-Sell) | Card-program set, plus the daily [Sales Response](/file-reference/sales/response-schema) confirming each day's receivables purchase; [Collateral](/file-reference/collateral/schema) if the product is secured | Card-program set, plus the daily [Sales Request](/file-reference/sales/request-schema) | | Credit / charge card (On-Sheet Lending) | Same as OTS — the sales exchange still runs daily, carrying no on-sheet receivables | Same as OTS | | Lending (Funding-based) | Daily Balances and Transactions (servicing), plus the daily Sales Response | Daily report set, plus the daily Sales Request | | Payments-only (ACH / wires / instant payments) | None — payments are fully API-based | Daily Balance · Daily Activity · ACH Cash Reconciliation *(if you originate ACH)* | | Checks | [X9](/file-reference/x9) image files | X9 files; [check settlement](/products/checks/settlement) detail | | Legacy file-integrated programs (pre-API onboarding) | Your program may additionally submit [Customer](/file-reference/customer/overview), [Account](/file-reference/account/overview), [Application](/file-reference/application/overview), [Cards](/file-reference/card/schema), and [Authorized Users](/file-reference/authorized-users/schema) files — see [Legacy file schemas](#) below. Your Lead team will coordinate your migration to the API equivalents. | Same as your product rows above | **Compliance documents** travel over SFTP for every program type ([document delivery](/file-reference/documents/overview)). # X9 File Requirements Source: https://docs.lead.bank/file-reference/x9 All check processing between you and Lead uses the X9.37 file standard. The sections below cover the file structure and the fields Lead uses for routing, matching, and funds movements. ## File Structure * Each X9 file contains one or more cash letters, each of which contains one or more bundles of check items. * Each check item includes the front image, back image, and structured MICR data. * Do not mix forwards and returns in the same X9 file. ## Key Fields The following fields are critical for correct processing: | **Field** | **Notes** | | :- | :- | | **Settlement Date** | Lead uses this date to determine when to move funds between the Fed GL and the Checks In Process GL. | | **Amount** | Integer value in cents. Lead uses this for daily limit checks and funds movements. | | **Routing Number** | Lead uses this to route incoming checks to the correct partner. For dedicated routing numbers, Lead forwards all items on the routing number to you. | | **OnUs Field (MICR)** | Contains the account number. Lead uses this for item matching on shared routing numbers. Lead works with each partner to configure the structure of this field. | | **ECE Institution Item Sequence Number** | A mandatory 15-digit field. Lead uses this to match incoming returns to the original outgoing entry. Populate it consistently on all outgoing X9 files. | | **Return Reason** | Populated on return items. Indicates why a check is being returned — for example, an account closed or fraud detected. | | **Cash Letter ID** | An eight-character alphanumeric identifier for the cash letter within the file. | | **BOFD Indicator** | Bank of First Deposit indicator. Mandatory field; valid values are Y, N, or U. | ## Return Matching Lead matches incoming returns to original outgoing entries using the **ECE Institution Item Sequence Number** and the submission date. Populate this field consistently on all outgoing X9 files to enable accurate return matching. # The Core Account Object Source: https://docs.lead.bank/products/core-account/core-account-object Field-level reference for the Core Account object, including account types and entity relationships. > [!NOTE] > > The Core Accounts API is in beta. Beta APIs can change without a version increment. Changes are announced in advance, and your Technical Account Manager works with you on them. See [Versioning and backwards compatibility](/core-concepts/platform/versioning-and-backwards-compatibility). A core account is a bank account on Lead's core. Lead creates one for each account your program needs during onboarding. You read them with `GET /v2/core_accounts` and `GET /v2/core_accounts/{id}`. ```json theme={null} { "id": "core_account_2xYv6Kn3Jp7QuS2lY5mAbC0dE4f", "name": "Partner FBO", "type": "attributed", "status": "active", "entities": { "account_holder_type": "lead", "account_holders": ["entity_lead_001"], "authorized_users": [] }, "created_at": "2026-03-02T14:00:00Z", "updated_at": "2026-03-02T14:00:00Z" } ``` ## Fields | Field | Type | Description | | :- | :- | :- | | `id` | string | Unique identifier, prefixed `core_account_`. | | `name` | string | Human-readable name set by Lead, for example "Consumer FBO" or "Operating DDA". Matches the account title you see in the Daily Balance report and online banking. | | `type` | enum | What the account is for: `attributed`, `direct`, or `shadow`. See [Account types](#account-types). | | `status` | enum | `active`, `inactive`, or `closed`. Lead manages all transitions. See [Core Account Statuses](/products/core-account/statuses). | | `entities` | object | Who holds the account. See [The entities block](#the-entities-block). | | `created_at`, `updated_at` | timestamp | RFC 3339, UTC. | ## Account types * `attributed`**.** An FBO whose funds are fully attributed to end customers. Each customer's share is a user balance beneath this account. Most consumer deposit programs have one of these. * `direct`**.** Everything else your program runs on: operating, settlement, revenue, and reserve DDAs, and any FBO that is not attributed at the customer level. Account numbers can attach directly to a direct account's balance, so payments can route to it. * `shadow`**.** A sweep or placement position, such as IntraFi ICS, that mirrors funds held elsewhere. You can read its balance. Nothing transacts against it directly and account numbers never attach. ## The entities block | Field | Type | Description | | :- | :- | :- | | `account_holder_type` | enum | `lead` if Lead holds the account, `partner` if your company does. | | `account_holders` | array | Entity IDs of the holders. | | `authorized_users` | array | Entity IDs of authorized users. | The entities referenced here are `lead` or `partner` entities that Lead sets up during onboarding. They are read only, so you cannot create or update them. Retrieve one with `GET /v2/entities/{id}` once Entity v2 is turned on for your program. Entity v0 does not return them, and `GET /v0/entities/{id}` returns `404`. See [Entity v2](/v2/products/entity/overview). ## List and retrieve `GET /v2/core_accounts` returns every core account visible to your program. Filters: * `type`. One of `attributed`, `direct`, `shadow`. * `limit`, `starting_after`, `ending_before`. Cursor pagination. Cursors are core account IDs. `GET /v2/core_accounts/{id}` returns one account. Returns `404` if the ID does not exist or belongs to another program. Neither endpoint triggers webhooks or business validations. Errors are the standard set on the [Errors](/api-reference/using-the-api/errors) page. ## Related [Core Account Overview](/products/core-account/overview) · [Core Account Statuses](/products/core-account/statuses) · [The Core Balance Object](/products/core-balance/core-balance-object) · [Account Numbers](/products/account-number/overview) # Core Accounts: The Bank Accounts Behind Your Program Source: https://docs.lead.bank/products/core-account/overview What a core account is, what the type field is for, who holds it, and how it relates to balances, transactions, and account numbers. > [!NOTE] > > The Core Accounts API is in beta. Beta APIs can change without a version increment. Changes are announced in advance, and your Technical Account Manager works with you on them. See [Versioning and backwards compatibility](/core-concepts/platform/versioning-and-backwards-compatibility). A core account is a real bank account on Lead's core. Lead opens one for each account your program needs during onboarding: the FBO that pools your customers' deposits, and the operating, settlement, revenue, and reserve accounts your program runs on. You do not create, change, or close them. You read them. Throughout this section, *account* means a core account. Your customers' accounts are user accounts and are documented under [Customers & Accounts](/products/entity/overview). ## Account types Every core account has a `type`: `attributed`, `direct`, or `shadow`. Use it to find the account you need. Filter on `direct` to find the accounts you can originate payments from, and on `attributed` to find the FBO your customer balances settle into. [The Core Account Object](/products/core-account/core-account-object) defines each type. ## Who holds a core account Each core account names the entities that hold it: whether Lead or your company is the account holder, plus any authorized user. [The Core Account Object](/products/core-account/core-account-object) documents the `entities` block. ## How core accounts relate to the rest of the model * **Core balance.** Each core account has one core balance today. The balance is where the money is: posted funds, holds, sweeps, overdraft, and interest. Read it with the [Core Balances API](/products/core-balance/overview). * **Core transactions.** Every ledger entry that changes the balance is a core transaction. You list them by balance, not by account. See [Core Transactions](/products/core-transaction/overview). * **Account numbers.** On a direct account, account numbers attach to the core balance and make it routable. See [Account Numbers](/products/account-number/overview). * **Payments.** ACH, wires, instant payments, and internal transfers reference an `account_number_id`. Lead resolves the core balance and core account behind it. ## What you can do List and retrieve your core accounts. Both operations are read only. ## What you cannot do * Create, update, activate, deactivate, or close a core account. Lead manages every transition. See [Core Account Statuses](/products/core-account/statuses). * Subscribe to webhooks today. Core accounts change rarely, so cache the list and refresh it daily or when your Lead team tells you an account has been added. See [Banking Infrastructure](/products/banking-infrastructure/overview#lead-manages-you-read) for what is planned. ## In this section * [The Core Account Object](/products/core-account/core-account-object) * [Core Account Statuses](/products/core-account/statuses) # Core Account Statuses Source: https://docs.lead.bank/products/core-account/statuses Lifecycle of a core account, who changes it, and how to observe a change. > [!NOTE] > > The Core Accounts API is in beta. Beta APIs can change without a version increment. Changes are announced in advance, and your Technical Account Manager works with you on them. See [Versioning and backwards compatibility](/core-concepts/platform/versioning-and-backwards-compatibility). Lead manages every core account status. You never call an endpoint to change one, and the status you read is whatever Lead has set. This page tells you what each status means and what to expect when one changes. ## Lifecycle ```mermaid theme={null} flowchart LR subgraph live [ ] direction TB active <--> inactive end active --> closed inactive --> closed style live fill:none,stroke:none ``` ## Statuses | **Status** | **Description** | **Notes** | | - | - | - | | `active` | The account is operating normally. | Its core balance can move, and account numbers on that balance can transact. | | `inactive` | Lead has paused the account. Funds stay on the ledger. | Account numbers on the balance cannot send or receive while the account is inactive. | | `closed` | Lead has closed the account on the core. Terminal. | The account stays readable so historical core transactions still resolve. | ## Transitions `active` and `inactive` move between each other. Either can move to `closed`. Nothing moves out of `closed`. Your Lead team will tell you before an account you depend on is deactivated or closed. Status changes are rare. ## Relationship to the core balance A core account and its core balance normally change status together. If you see them disagree, treat the balance as authoritative for whether money can move, and contact your Technical Account Manager. Account numbers keep their own status, so an account number can show `active` and still not transact while its account is inactive. If payments fail unexpectedly, check the core account and core balance status first. ## Webhooks Core accounts do not emit events today. Status changes are Lead-initiated and rare, so poll `GET /v2/core_accounts/{id}` at the cadence your use case needs. A daily refresh is enough for most programs. ## Related [The Core Account Object](/products/core-account/core-account-object) · [Core Balance Statuses](/products/core-balance/statuses) · [Account Number Statuses](/products/account-number/statuses) · [Webhooks & Events](/api-reference/using-the-api/webhooks) # The Core Balance Object Source: https://docs.lead.bank/products/core-balance/core-balance-object Field-level reference for the Core Balance object, including the amounts definitions and formulas, overdraft, and interest. > [!NOTE] > > The Core Balances API is in beta. Beta APIs can change without a version increment. Changes are announced in advance, and your Technical Account Manager works with you on them. See [Versioning and backwards compatibility](/core-concepts/platform/versioning-and-backwards-compatibility). A core balance is a balance position within a core account. It is where the money actually sits. Read them with `GET /v2/core_balances` and `GET /v2/core_balances/{id}`. ```json theme={null} { "id": "core_balance_2xYw9Lp4Kq8RvT3mZ6nBcD1eF7g", "core_account_id": "core_account_2xYv6Kn3Jp7QuS2lY5mAbC0dE4f", "name": "Partner FBO", "status": "active", "currency_code": "USD", "amounts": { "spendable": 2070115, "cash_available": 1070115, "posted": 1080115, "sweeps": 0, "holds": 10000 }, "overdraft": { "limit": 1000000, "used": 0, "unused": 1000000 }, "interest": { "rate": null, "accrued": 0 }, "created_at": "2026-03-02T14:00:00Z", "updated_at": "2026-09-25T15:50:50Z" } ``` ## Fields | Field | Type | Description | | :- | :- | :- | | `id` | string | Unique identifier, prefixed `core_balance_`. | | `core_account_id` | string | The parent core account. | | `name` | string | Human-readable name set by Lead. | | `status` | enum | `active`, `inactive`, or `closed`. Lead managed. See [Core Balance Statuses](/products/core-balance/statuses). | | `currency_code` | string | ISO 4217. | | `amounts` | object | The balance breakdown. See [The amounts block](#the-amounts-block). | | `overdraft` | object | Overdraft facility on this balance. See [The overdraft block](#the-overdraft-block). | | `interest` | object | Interest position. See [The interest block](#the-interest-block). | | `created_at`, `updated_at` | timestamp | RFC 3339, UTC. | All amounts are signed integers in minor units. `1500` is \$15.00. ## The amounts block Five figures, two of them derived. | Field | Description | | :- | :- | | `posted` | Everything that has fully posted to the ledger. This is the closing balance figure you see in the Daily Balance report. | | `holds` | Funds that are reserved for pending transactions. | | `sweeps` | Funds sitting in linked sweep balances (for example IntraFi) that can be drawn back on demand. | | `cash_available` | Actual cash net of holds. `posted` minus `holds`. | | `spendable` | What you can move right now. `cash_available` plus `overdraft.unused` plus `sweeps`. | > [!WARNING] > > `spendable` may include overdraft capacity. A balance with `cash_available` of zero can still show a positive `spendable` if the account has an overdraft limit. Do not present `spendable` as cash on hand. ## The overdraft block | Field | Description | | :- | :- | | `limit` | The maximum overdraft facility on this balance. Zero if none. | | `used` | Overdraft currently drawn. | | `unused` | Remaining capacity. `limit` minus `used`. This is the portion that flows into `spendable`. | ## The interest block | Field | Description | | :- | :- | | `rate` | Annualized rate as a decimal string with six places, for example `"1.000000"`. | | `accrued` | Interest accrued but not yet posted, in minor units. | ## List and retrieve `GET /v2/core_balances` returns every core balance visible to your program. Filters: * `core_account_id`. Balances under one core account. * `limit`, `starting_after`, `ending_before`. Cursor pagination. Cursors are core balance IDs. `GET /v2/core_balances/{id}` returns one balance. `404` if the ID does not exist or belongs to another program. Each request reads Lead's core directly, so the figures reflect the ledger at the time of the request. ## Related [Core Balance Overview](/products/core-balance/overview) · [Core Balance Statuses](/products/core-balance/statuses) · [The Core Account Object](/products/core-account/core-account-object) · [The Core Transaction Object](/products/core-transaction/core-transaction-object) · [Daily Balance report](/file-reference/reports/daily-balance) # Core Balances: Where Your Program's Money Sits Source: https://docs.lead.bank/products/core-balance/overview What a core balance is, which figure to use for what, and how it relates to the account, transactions, and account numbers. > [!NOTE] > > The Core Balances API is in beta. Beta APIs can change without a version increment. Changes are announced in advance, and your Technical Account Manager works with you on them. See [Versioning and backwards compatibility](/core-concepts/platform/versioning-and-backwards-compatibility). A core balance is the balance position within a core account. It is where the money actually is: posted funds, holds, sweeps, overdraft, and interest, with a derived spendable figure. Lead creates it with the account. You read it. ## Which figure to use * `spendable` to decide whether a payment can go out. It is the figure Lead's own authorization uses. * `cash_available` for anything customer facing, such as a treasury dashboard, because it shows real cash without borrowed or swept funds. * `posted` to reconcile against the Daily Balance report and against the sum of core transactions. > [!WARNING] > > `spendable` may include overdraft capacity. A balance with `cash_available` of zero can still show a positive `spendable` if the account has an overdraft limit. Do not present `spendable` as cash on hand. [The Core Balance Object](/products/core-balance/core-balance-object) defines each figure and the formulas behind the derived ones. ## How core balances relate to the rest of the model * **Core account.** `core_account_id` names the parent. A balance normally carries the same status as its account. See [Core Balance Statuses](/products/core-balance/statuses). * **Core transactions.** Every core transaction names the `core_balance_id` it affected. * **Account numbers.** On a `direct` account, account numbers attach to this balance, so an incoming payment to one of those numbers lands here. ## What you can do List and retrieve your core balances. Both operations are read only. Each request reads Lead's core directly, so the figures reflect the ledger at the time of the request. ## What you cannot do * Change a balance directly. Money moves only through payments and Lead's own core activity. * Subscribe to webhooks today. Poll the retrieve endpoint at the cadence your use case needs. See [Banking Infrastructure](/products/banking-infrastructure/overview#lead-manages-you-read) for what is planned. ## In this section * [The Core Balance Object](/products/core-balance/core-balance-object) * [Core Balance Statuses](/products/core-balance/statuses) # Core Balance Statuses Source: https://docs.lead.bank/products/core-balance/statuses A core balance shares its account's lifecycle; what an inactive balance means for account numbers; how to observe changes. > [!NOTE] > > The Core Balances API is in beta. Beta APIs can change without a version increment. Changes are announced in advance, and your Technical Account Manager works with you on them. See [Versioning and backwards compatibility](/core-concepts/platform/versioning-and-backwards-compatibility). Lead manages every core balance status. You never call an endpoint to change one. A core balance shares its lifecycle with the core account it belongs to, and the two normally change together. [Core Account Statuses](/products/core-account/statuses) describes that lifecycle in full; this page covers what is specific to the balance. ## Lifecycle ```mermaid theme={null} flowchart LR subgraph live [ ] direction TB active <--> inactive end active --> closed inactive --> closed style live fill:none,stroke:none ``` ## Statuses | **Status** | **Description** | **Notes** | | - | - | - | | `active` | The balance is operating normally. | Funds can move. Account numbers attached to the balance can transact. | | `inactive` | Lead has paused the balance. Funds stay on the ledger. | Account numbers attached to the balance cannot send or receive while it is inactive. | | `closed` | Lead has closed the balance on the core. Terminal. | The balance stays readable so historical core transactions still resolve. | ## What an inactive balance means for account numbers Account numbers keep their own status, so an account number can show `active` and still not transact while its account is inactive. If payments fail unexpectedly, check the core account and core balance status first. If the balance and its account disagree, treat the balance as authoritative for whether money can move, and contact your Technical Account Manager. ## Observing changes Core balances do not emit events today, for status changes or for amount changes. Poll `GET /v2/core_balances/{id}` at the cadence your use case needs. ## Related [The Core Balance Object](/products/core-balance/core-balance-object) · [Core Account Statuses](/products/core-account/statuses) · [Account Number Statuses](/products/account-number/statuses) # The Core Transaction Object Source: https://docs.lead.bank/products/core-transaction/core-transaction-object Field-level reference for the Core Transaction object, the type enum with lookups, the single posted state, and list filters. > [!NOTE] > > The Core Transactions API is in beta. Beta APIs can change without a version increment. Changes are announced in advance, and your Technical Account Manager works with you on them. See [Versioning and backwards compatibility](/core-concepts/platform/versioning-and-backwards-compatibility). A core transaction is a single ledger entry that changed a core balance. Lead creates them. You read them with `GET /v2/core_transactions` and `GET /v2/core_transactions/{id}`. ```json theme={null} { "id": "core_transaction_3JpKd8vN2wQxT5mRz7bYaL4cE9f", "core_balance_id": "core_balance_2xYw9Lp4Kq8RvT3mZ6nBcD1eF7g", "type": "ach", "description": "Incoming ach_3JpCw2kQ9rTb7yLm4XnVdE8oF1g NORTHWIND LLC PAYROLL", "amount": 248250, "currency_code": "USD", "created_at": "2026-09-25T15:02:14Z", "updated_at": "2026-09-25T15:02:14Z" } ``` ## Fields | Field | Type | Description | | :- | :- | :- | | `id` | string | Unique identifier, prefixed `core_transaction_`. | | `core_balance_id` | string | The core balance this entry affected. | | `type` | enum | The rail or mechanism that created the entry. See [The type enum](#the-type-enum). | | `description` | string, max 120 | Human-readable memo. Useful for eyeballing, not for matching. Use `type` and the core transaction ID fields on the payment object to match. | | `amount` | integer | Signed, minor units. Positive is a credit to the balance, negative is a debit. | | `currency_code` | string | ISO 4217. | | `created_at` | timestamp | When the entry posted and affected the balance. UTC. | | `updated_at` | timestamp | Usually equals `created_at`. | A core transaction has a single state, `posted`. It exists only once it has affected the balance. There is no pending state and no status field. Corrections are new, offsetting entries with their own IDs. ## The type enum When a value names a Lead platform object, the core transaction has a matching payment record you can retrieve. The rest are posted by Lead and have no payment object. | Value | Definition | Lead platform object | | :- | :- | :- | | `ach` | An ACH origination, return, or reversal. | [ACH](/products/ach/overview) | | `checks` | A check deposited, paid, or returned. | [Check](/products/checks/overview) | | `domestic_wires` | A domestic wire sent or received, or the return of one. | [Wire](/products/wire/wire-object) | | `international_wires` | An international wire sent or received, or the return of one. | [Wire](/products/wire/wire-object) | | `instant_payments` | An RTP or FedNow payment sent or received, or the return of one. | [Instant Payment](/products/instant-payments/the-instant-payment-object) | | `blockchain_payments` | A blockchain payment or its refund. | [Blockchain Payment](/products/blockchain-payments/overview) | | `internal_transfers` | A book transfer between two Lead accounts. | [Internal Transfer](/products/internal-transfer/internal-transfer-object) | | `fundings` | A loan disbursement. | [Funding](/v2/products/fundings/funding-object) | | `receivable_sales` | The settlement of a receivable sale. | [Receivable Sale](/v2/products/receivable-sales/receivable-sale-object) | | `interest` | Interest accrued, credited, or adjusted on the balance. | None. Posted by Lead. | | `fees` | A fee Lead charged to the balance, or a refund of one. | None. Posted by Lead. | | `sweeps` | Funds moved into or out of a sweep position. | None. Posted by Lead. | | `lead_generated` | An entry Lead creates outside of a program's own activity: transfers Lead initiates to operate a program's funds flow (including digital asset settlement), network settlement entries, charge-offs, withholding, corrections, and manual adjustments. | None. Posted by Lead. | | `legacy_banking` | Activity from Lead's banking systems outside the platform: card, cash, and ATM activity and clearing movements. Does not produce a platform object. Lead is discontinuing these products; this value will be deprecated once they are retired. | None. Posted by Lead. | ## List and retrieve `GET /v2/core_transactions` lists entries for one balance. Filters: * `core_balance_id` (required). The balance to list. * `type`. One of the enum values. An unknown value returns `400 parameters_invalid`. * `created_at[after]`, `created_at[on_or_after]`, `created_at[before]`, `created_at[on_or_before]`. Standard time window. * `limit`, `starting_after`, `ending_before`. Cursor pagination. Cursors are core transaction IDs. `GET /v2/core_transactions/{id}` returns one entry. `404` if not found or not yours. ## Related [Core Transaction Overview](/products/core-transaction/overview) · [The Core Balance Object](/products/core-balance/core-balance-object) · [The ACH Object](/products/ach/ach-object) · [The Wire Object](/products/wire/wire-object) · [Daily Activity report](/file-reference/reports/daily-activity) # Core Transactions: Your Program's Ledger Entries Source: https://docs.lead.bank/products/core-transaction/overview What a core transaction is, how to tie one to the payment that caused it, timing, and how to read them today. > [!NOTE] > > The Core Transactions API is in beta. Beta APIs can change without a version increment. Changes are announced in advance, and your Technical Account Manager works with you on them. See [Versioning and backwards compatibility](/core-concepts/platform/versioning-and-backwards-compatibility). A core transaction is a single ledger entry that changed a core balance. Lead creates them: when a payment posts, when interest or a fee is applied, when funds sweep. You read them. There is nothing to create and nothing to reverse. Corrections are new, offsetting entries with their own IDs. A core transaction has one state, `posted`. It exists only once it has affected the balance. There is no pending state and no status field. ## Types at a glance `type` names the rail or mechanism that created the entry. ACH, checks, wires, instant payments, blockchain payments, internal transfers, fundings, and receivable sales each have a matching payment object on the Lead platform. Interest, fees, sweeps, Lead-generated entries, and legacy banking activity are posted by Lead and have no payment object. [The Core Transaction Object](/products/core-transaction/core-transaction-object#the-type-enum) lists every value. ## From a payment to its ledger entries, and back The join works in both directions. * **Payment to ledger.** Once a payment posts, the payment object carries the IDs of the core transactions it produced, in a shape that fits the rail. * **Ledger to payment.** Read `type`, then call that rail's list endpoint with `core_transaction_id={id}`. One core transaction can map to many payments, for example one settlement entry covering a batch of ACH entries. A core transaction can exist before the object it links to is visible on its own endpoint. This is expected. If your workflow needs both, wait for the payment object's posted webhook rather than polling the core transaction list. ## Reading core transactions List entries for one balance, filtered by `type` and a `created_at` window, or retrieve one by ID. Core transactions do not emit webhooks today, so poll the list with a `created_at` window at whatever cadence your reconciliation runs. A suite of core transaction webhooks is planned; see [Banking Infrastructure](/products/banking-infrastructure/overview#lead-manages-you-read). ## In this section * [The Core Transaction Object](/products/core-transaction/core-transaction-object) # Upcoming Changes Source: https://docs.lead.bank/upcoming-changes Advance notice of planned Lead platform, API, and reporting changes that may require partner awareness, testing, or action before effective dates. > [!WARNING] > > Upcoming changes are not yet live in production unless explicitly noted. Check back frequently for the latest status. We will continue to update details throughout the change lifecycle: > > 🟡 **Announced →** 🟢 **Sandbox Available →** 🟠 **Enforcement Soon →** ✅ **Released** > > Timelines may change as implementation details are finalized. ## Active Changes | **Status** | Important Dates | **Change** | | - | - | - | | 🟢 Sandbox Available | Required Action by November 12, 2026 | [ACH Status Lifecycle Expansion](/upcoming-changes#ach-status-lifecycle-expansion) | | ✅ **Released** | Required Action by October 6, 2026 | [New Balances and Transactions File Alert](/upcoming-changes#new-balances-and-transactions-file-alert) | | 🟡 Announced | Required Action by January 20, 2027 | [Daily Report V2 Migration and New Transaction Codes](/upcoming-changes#daily-report-v2-migration-and-new-transaction-codes) | | ⏸️ Delayed | Required Action by January 20, 2027 | [Updated Transaction Codes for System Activity](/upcoming-changes#updated-transaction-codes-for-system-activity) | | 🟢 Sandbox Available | Required Action by November 12, 2026 | [OAuth Access Token Caching](/upcoming-changes#oauth-access-token-caching) | | ✅ **Released** | Required Action by September 30, 2026 | [Instant Payments Return API Updates](/upcoming-changes#instant-payments-return-api-updates) | | 🟠 Enforcement Soon | Rolling Out October 6 - November 10, 2026 | [Account Validation During New Balance Creation](/upcoming-changes#account-validation-during-new-balance-creation) | | 🟡 Announced | Recommended Review by November 12, 2026 | [Earlier ACH Posting](/upcoming-changes#earlier-ach-posting) | | ⏸️ Delayed | Required Migration - Date to be announced | [Wires API V2 Migration](/upcoming-changes#wires-api-v2-migration) | | 🟡 Announced | Required Migration by March 31, 2027 | [Receivable Sales and Receivables APIs](#receivable-sales-and-receivables-apis) | | 🟡 Announced | Migration Deadline TBD | [Entity and Applications APIs v2](/upcoming-changes#entity-and-applications-apis-v2) | > [accordion] Status Descriptions > > | Status | Description | > | :- | :- | > | 🟡 Announced | Change has been communicated and is planned, but is not yet available for testing. | > | 🟢 Sandbox Available | Change is available for testing in sandbox but is not yet live in production. | > | 🟠 Enforcement Soon | Production date is approaching and any required implementation work should be completed. | > | ✅ Released | Change is now live in production and has been added to the Changelog. | > | ⏸️ Delayed | Previously announced timelines have changed. | *** **Required Action by November 12, 2026** ## ACH Status Lifecycle Expansion **Status:** 🟢 Sandbox Available\ **Action Required:** Yes (Deadline will be enforced)\ **Sandbox Available:** July 14, 2026\ **Effective Date:**  November 12, 2026 We're expanding visibility into the ACH lifecycle by surfacing previously hidden events and introducing support for dishonored and contested returns. Historically, certain ACH events — such as auto-returns and manual review holds — were handled internally and were not visible to partners. This update brings ACH behavior in line with other payment rails by exposing the complete lifecycle through statuses and webhooks. ### **What's Changing** #### **Previously Hidden Events Are Now Visible** The following events will now be surfaced through statuses and webhooks: * ACH entries held for manual review * ACH entries automatically returned by Lead This introduces a new visible status: * `under_review` #### **Expanded Return Lifecycle** We're adding support for the full ACH return lifecycle, including dishonored and contested returns. New statuses include: * `pending_dishonored_return` * `return_dishonored` * `pending_contested_return` * `return_contested` New webhooks include: * `ach.under_review` * `ach.rejected` * `ach.return_dishonored` * `ach.return_contested` #### **ACH Entries May Receive Additional Status Updates** In certain scenarios, ACH entries that previously appeared terminal may continue transitioning through additional states. Examples include: ```text theme={null} posted → pending_return → posted ``` and ```text theme={null} rejected → pending_return_dishonored → return_dishonored ``` #### **Recommended testing process** **For previously hidden events:** you can simulate the new behavior by using `/v1/simulate/ach/incoming_ach` to initiate an incoming transaction on an `account_number_id` you have set to `inactive` status **For dishonored and contested transactions:** we have updated the list of return codes to include the R6x and R7x series return codes to indicate dishonored and contested returns respectively.  Please see the [Updated ACH Status Lifecycle Documentation](/products/ach/statuses) for expanded details. ### **What You Need To Do** Before the effective date: 1. Ensure your `ach.posted webhook` handler is idempotent for a given ACH entry. 2. Update status handling to support: * `under_review` * `return_dishonored` * `return_contested` * `pending_dishonored_return` * `pending_contested_return` 3. Do not assume rejected or returned are always terminal states. 4. Test your integration against the updated ACH lifecycle in sandbox. ### **Why This Matters** Partners that do not update their integrations may experience: * Duplicate processing from repeated webhook events * Missed or incorrect status transitions * Incomplete visibility into ACH return and dispute scenarios * Incorrect reconciliation or customer notifications ### **Additional Resources** * [Updated ACH Status Lifecycle Documentation](/products/ach/statuses) * [Returns, Reversals, & Exceptions Documentation](/products/ach/exceptions) *** **Required Action by October 6, 2026** ## New Balances and Transactions File Alert **Status:** ✅ **Released**\ **Action Required:** Yes, only if you use Slack alerts to drive file-processing workflows \ **Sandbox Available:** N/A\ **Effective Date:**  October 6, 2026 We’re adding a new Slack alert to indicate when the next day’s Balance and Transactions files can be submitted. The alert provides a definitive signal for submission timing, complementing the existing success alert, which confirms only that a file processed correctly.This is particularly helpful when a program is behind and the previous day’s files have not yet finished processing. This is an additive change to the existing file alert workflow. ### **Why We're Making This Change** The existing successful-processing alert confirms that a file was received and validated, but it is not intended to indicate readiness to submit the next file. The new alert closes that gap by providing a dedicated signal for when the next day's files can be submitted. ### **What's Changing** Lead is adding a new Slack alert related to Balance and Transactions files. * The existing alert confirming that files were submitted and validated successfully will continue to be sent. * The new alert will indicate when the next day's files can be submitted. * The new alert is intended to distinguish successful file validation from readiness to submit the next day’s files. ### **What You Need To Do** No action is required if you do not use Slack alerts to drive file-processing workflows. If you process Slack alerts programmatically: 1. Update your alert-handling logic to consume the new alert. 2. Use the alert to trigger any corresponding action, such as submitting the next day’s files. 3. Test the updated workflow before the alert is enabled for your program. ### **What Happens if You Don't Act** Your existing file-submission process will continue to work, but any automation that relies on Slack alerts will not receive or act on this new readiness signal unless it is updated to consume the alert. Those workflows may need to continue relying on existing error messages or manual checks to determine when to submit the next day’s files. ### **Who This Affects** This update applies to everyone with a deposit, debit, and/or prepaid program. ### Timeline | **Milestone** | **Date** | | - | - | | Announcement | September 4, 2026 | | Effective Date | October 6, 2026 | *** **Required Action by January 20, 2027** ## Daily Report V2 Migration and New Transaction Codes **Status:** 🟡 Announced\ **Action Required:** Yes (review downstream accounting, reconciliation, and reporting logic) \ **Sandbox Available:** N/A (V2 sample files available by December 1, 2026)\ **Effective Date:**  Transaction codes: January 20, 2027 // V2 files begin: No later than January 20, 2027 // Current (V1) files end: March 20, 2027 We're changing the daily activity and balance reports Lead sends you over SFTP. This notice covers every change that affects your reconciliation process: 1. **New transaction codes (January 20, 2027).** Entries that post under code 37 today move to 910 (fees), 911 (interest), 912 (IntraFi sweeps), 913 (Lead-generated), and 937 (platform-initiated GL-to-DDA transactions). The 937 change was [previously announced](https://docs.lead.bank/upcoming-changes#updated-transaction-codes-for-system-activity) for December 3, 2026 and is delayed to January 20. API internal transfers initiated by Lead move from 1075 to 1016. 2. **New V2 activity and balance files (no later than January 20, 2027).** V2 files use a [transaction type](https://docs.lead.bank/products/core-transaction/core-transaction-object#the-type-enum) instead of a numeric code and take the end-of-day balance from the ledger at 10:00 pm CT. They no longer wait on a separate end-of-day process, so they arrive on time and each day's balance ties to that day's activity. 3. **New columns are not breaking changes (V2 and later).** Consistent with our API versioning policy, new columns in files are non-breaking changes and may be added without an Upcoming Changes notice. Your parser should identify columns by header name rather than position. 4. **Current (V1) files end March 20, 2027.** Move to the V2 files or the [Core Accounts](https://docs.lead.bank/products/core-account/overview), [Core Balances](https://docs.lead.bank/products/core-balance/overview), and [Core Transactions](https://docs.lead.bank/products/core-transaction/overview) APIs. With the Core APIs, you can read balances and transactions at whatever cadence your reconciliation runs, instead of waiting for a daily file. #### Why We're Making This Change Today, several kinds of activity share code 37, and the balance report waits on a separate end-of-day process that can hold your reports. With these changes, the transaction codes, V2 files, and Core APIs use the same transaction types and identifiers, and V2 balances come directly from the ledger. Moving the December 3 date lets all changes that may affect your internal processes take effect on the same day. #### What's Changing ##### New Transaction Codes Starting January 20, 2027, in your current activity report: | Code | Description | Core Transaction type | What it covers | | :- | :- | :- | :- | | 910 | Miscellaneous Fees | `fees` | Fee entries (previously 37) | | 911 | Miscellaneous Interest | `interest` | Interest entries (previously 37) | | 912 | Miscellaneous IntraFi Sweeps | `sweeps` | IntraFi sweep entries (previously 37) | | 913 | Miscellaneous Lead Generated | `lead_generated` | Manual Lead entries, such as network settlement adjustments (previously 37) | | 937 | Miscellaneous, Platform use | `lead_generated` | Platform-initiated GL-to-DDA transactions (previously 37). See [Updated Transaction Codes for System Activity](https://docs.lead.bank/upcoming-changes#updated-transaction-codes-for-system-activity). | | 1016 | Internal Transfer | `internal_transfers` | Internal transfers you create through the API (previously 1075) | | 1075 | Book Transfer | `lead_generated` | Transfers Lead initiates on your behalf only | Code 37 remains for a small number of true miscellaneous entries. Activity posted before January 20, 2027 keeps its original code. Core Transactions API integrations don't need changes. ##### V2 Activity and Balance Files V2 files arrive in a new SFTP folder, and Lead will notify you when they begin landing. Your current files stay in their existing folder until March 20, 2027. * **Type and ID:** Each entry has a `type` and a unique `transaction_id`, both matching the Core Transactions API. * **10:00 pm CT cutoff:** Transactions after 10:00 pm CT, including daily interest posted shortly after midnight, appear on the next day's file with the prior day's `posted_date`. Online banking shows the live ledger, so it may differ from the file at the cutoff. * **Source of truth:** While both files are delivered, V2 is authoritative. Report any difference not on the expected-differences list to your Technical Account Manager. The V2 schema, sample files, code-to-type mapping table, and expected-differences list will be published by December 1, 2026. * **Breaking changes:** Renaming or removing a column, changing a column's type, format, or meaning, or changing the file name or cadence. These are considered breaking changes and are announced ahead of the change on Lead’s [Upcoming Changes page](https://docs.lead.bank/upcoming-changes). New columns are not considered breaking, and are posted to the Changelog once they ship. Until March 20, 2027, Lead will correct data errors in the current files but won't add new fields. #### What You Need To Do Before January 20, 2027: * If you'll still read your current activity report on January 20, add the new codes to any logic that uses codes 37 or 1075. * If you prepared for the 937 change on December 3, keep recognizing code 37 for those entries until January 20. Before March 20, 2027: * Choose the V2 files or the Core APIs. * For V2, read the new folder, parse columns by header name, use `type` instead of the code, and test with the December 1 sample files and mapping table. If a third party reads your files on your behalf, share this notice with them. For migration help, contact your Technical Account Manager. #### What Happens if You Don't Act * From January 20, 2027, logic that only recognizes code 37 or 1075 may miscategorize or drop the new entries. * After March 20, 2027, current files stop, and integrations that read them stop receiving data. * V2 integrations that read columns by position may fail when columns are added. #### Who This Affects Partners that receive daily activity or balance reports over SFTP, and third parties that read these files for them. Partners that don't use these reports are not affected. #### Timeline | Milestone | Date | | :- | :- | | Announcement | October 20, 2026 | | V2 schema, sample files, mapping table, and expected-differences list published | By December 1, 2026 | | New transaction codes, including 37 to 937, take effect | January 20, 2027 | | V2 files begin | No later than January 20, 2027 | | Current (V1) files end | March 20, 2027 | #### Additional Resources * [Core Transactions Overview](https://docs.lead.bank/products/core-transaction/overview) * [Updated Transaction Codes for System Activity](https://docs.lead.bank/upcoming-changes#updated-transaction-codes-for-system-activity) * [Daily Activity Report field definitions](https://docs.lead.bank/file-reference/reports/daily-activity) *** **Required Action by January 20, 2027** ## Updated Transaction Codes for System Activity **Status:** ⏸️ Delayed\ **Action Required:** Yes (review downstream accounting, reconciliation, and reporting logic) \ **Sandbox Available:** N/A\ **Effective Date:**  January 20, 2027 (previously December 3, 2026) Timeline update: This change was previously scheduled for December 3, 2026. It now takes effect on January 20, 2027 as part of [Daily Report V2 Migration and New Transaction Codes](https://docs.lead.bank/upcoming-changes#daily-report-v2-migration-and-new-transaction-codes), so all transaction code changes take effect on the same day. The details below are otherwise unchanged. We’re updating the transaction codes used for certain Lead-originated transactions to streamline downstream accounting processes. Transactions initiated by Lead between a GL and DDA will use tran code `937` instead of `37` in the Daily Activity Report. No line items will be added or removed. Only the transaction code for affected entries will change. If your program includes a card program and/or receivable sales, then your reports will be affected. More specifically, Network Settlement and the Sales process generate these transactions. ### **Why We're Making This Change** This change standardizes the classification of Lead-originated transactions between a GL and DDA, which supports more consistent downstream accounting processes. ### **What's Changing** The new tran code applies when both conditions are true: * The transaction was initiated by Lead. * The transaction occurred between a GL and DDA. For these transactions, the code will change from `37` to `937`. The Daily Activity Report will continue to include the same line items. This update changes the applicable transaction code only. Below is a list of accounting entries today that Lead generates that will be affected - if any of your entries include this in the memo description, then it will have its tran code updated to from `37` to `937`: * `{ProgramName} Interchange Fee Income {FileDate}-{CardNetwork}` * `{ProgramName} Network Fee {FileDate}-{CardNetwork}` * `{ProgramName} Receivables Funding {FileDate}-{CardNetwork}` * `{ProgramName} Interchange Expense {FileDate}` * `{ProgramName} Network Fee Expense {FileDate}` * `{ProgramName} Interchange Payout {FileDate}` * `{ProgramName} Network Fee Charge {FileDate}` * `{ProgramName} Payment Principal {FileDate}` * `{ProgramName} Receivables Interest Accrual {FileDate}` * `{ProgramName} Receivables Purchase Principal {FileDate}` * `{ProgramName} Loan Purchase Net Suspense {FileDate}` * `{ProgramName} Canceled Disbursement {FileDate}` * `{ProgramName} Disbursement Funding {FileDate}` * `{ProgramName} Down Payment Funding {FileDate}` * `{ProgramName} Held Disbursements {FileDate}` * `{ProgramName} New Disbursements {FileDate}` ### **What You Need To Do** Before the effective date: 1. Review accounting, reconciliation, and reporting workflows that identify affected entries by tran code. 2. Update those workflows to recognize 937 instead of 37 for Lead-originated GL-to-DDA transactions. 3. Test downstream processing against the updated code before the change takes effect. If you already updated your workflows for December 3, 2026, continue to recognize code 37 for these entries until January 20, 2027. ### **What Happens if You Don't Act** If your downstream processes rely on tran code 37 to identify these entries, they may not correctly recognize or classify affected transactions after the change. This may lead to inaccurate accounting, reconciliation, or reporting results until the logic is updated. ### **Who This Affects** All Lead partners. ### Timeline | **Milestone** | **Date** | | - | - | | Announcement | September 4, 2026 | | Timeline update | October 20, 2026 | | Effective Date | January 20, 2027 (previously December 3, 2026) | *** **Required Action by November 12, 2026** ## **OAuth Access Token Caching** **Status:** 🟢 Sandbox Available\ **Action Required:** Yes (Deadline will be enforced)\ **Sandbox Available:** October 1, 2026\ **Effective Date:** November 12, 2026 We're updating how OAuth access tokens are issued and managed to improve platform performance and reduce unnecessary authentication traffic. Today, some integrations request a new access token before every API call. Going forward, access tokens will be cached for up to 23 hours and should be reused until they expire. ### **Why We're Making This Change** OAuth access tokens are designed to be reused for their full validity period. Requesting a new token for every API call creates unnecessary authentication traffic and increases platform overhead. This change aligns Lead's authentication model with standard OAuth practices and improves the efficiency and reliability of the platform. ### **What's Changing** Access tokens issued through the Token Exchange API will: * Remain valid for approximately 23 hours * Be reused during that validity period * Continue to include an `expires_in` field that indicates when the token should be refreshed Integrations should use the existing token until it expires rather than requesting a new token for every API request. ### **What You Need To Do** Before the effective date: 1. Review your authentication implementation. 2. Ensure access tokens are cached and reused until expiration. 3. Use the `expires_in` field to determine when a token should be refreshed. 4. Update any integrations that request a new access token before every API call. ### **Why This Matters** Integrations that do not properly cache access tokens may experience: * Authentication failures * Unexpected authorization errors * Reduced application performance * Future limitations related to excessive token generation ### **Recommended Error Handling** If an API request fails due to an expired or invalid token: 1. Evict the cached token. 2. Request a new access token. 3. Retry the request once. ### Timeline | **Milestone** | **Date** | | - | - | | Announcement | June 10, 2026 | | Sandbox Available | October 1, 2026 | | Effective Date | November 12, 2026 | *** **Required Action by September 30, 2026** ## **Instant Payments Return API Updates** **Status:** ✅ **Released**\ **Action Required:** Yes (Deadline will be enforced)\ **Sandbox Available:** Available Now\ **Effective Date:** September 30, 2026 We are actively adding support for RTP as a payment rail. In preparation, we are updating portions of the Instant Payments API to align return request functionality across FedNow and RTP. These changes affect return-related fields and endpoints and introduce updated validation requirements for return reasons and supporting information. ### **Why We're Making This Change** As we expand support for RTP and continue to align behavior across instant payment networks, we're standardizing how return requests and return responses are handled. These changes simplify the API, remove unsupported return scenarios, and ensure consistent behavior across instant payment rails. ### **What's Changing** #### **Reduced Maximum Length for** `additional_information` The `additional_information` field will be limited to **105 characters** for the following endpoints: * `/return` * `/request_return` * `/simulate/incoming_return` * `/simulate/incoming_return_request` Requests exceeding this limit will fail validation. #### **Updated Return Request Reason Values** The following reason values will no longer be supported on: * `/request_return` * `/simulate/incoming_return_request` Removed values: * `narrative` * `service_not_rendered` The following values will no longer be supported on: * `return_requests.reason` Removed values: * `narrative` * `per_agent_request` * `service_not_rendered` #### **Changes to Return Request Rejections** The `/reject_return_request `endpoint will no longer support: * `additional_information` * `narrative` as a rejection reason The `/simulate/incoming_return_request_rejection` endpoint will no longer support * `additional_information` * `narrative` and `per_agent_request` as rejection reasons The `return_requests.resolution.rejection_reason` field will no longer support: * `narrative` and `per_agent_request` Requests containing these values will fail validation. ### **What You Need To Do** Before August 31, 2026: 1. Review any integrations that deal with returns, return requests, or return request responses. 2. Ensure additional\_information values do not exceed 105 characters. 3. Remove any usage of unsupported reason values. ### **Why This Matters** Partners that do not update their integrations may experience: * Validation errors * Failed return requests * Failed return request responses * Operational delays when processing return-related workflows While current return volumes are low, we recommend validating your implementation before the effective date to avoid disruptions. ### Timeline | **Milestone** | **Date** | | - | - | | Announcement | June 10, 2026 | | Sandbox Available | June 30, 2026 | | Effective Date | September 30, 2026 | *** **Rolling Out October 6 - November 10, 2026** ## Account Validation During New Balance Creation **Status:** 🟠 Enforcement Soon\ **Action Required:** Yes (Deadline will be enforced)\ **Sandbox Available:** September 22, 2026\ **Effective Date:** October 6 - November 10, 2026 We're introducing additional validation to ensure every new Balance record contained in a Balance file submitted to Lead is associated with a valid parent Account. Balances created via API already have this enforced and no action is required. Today, Lead does not enforce that the account\_id referenced on a new Balance ties back to a recognized and valid Account. This update closes that gap and improves our ability to accurately associate Balances and Transaction activity with the correct Account and Entity. ### **Why We're Making This Change** Every Balance should be traceable to a valid Account. This change improves data integrity, financial attribution, and operational consistency by ensuring Balance records reference Accounts that exist, belong to your program, and are configured appropriately. ### **What's Changing** Starting October 6, 2026, Lead will validate the account\_id referenced by each new Balance record submitted through Balance files. The following validations will be enforced: #### Account existence and ownership The referenced `account_id` must: * Exist within Lead’s system * Belong to your program Failures will return: ```text theme={null} account_not_found ``` #### **Account Status** The referenced Account must be in a permitted status: * active * inactive Accounts in other statuses (such as closed) will be rejected. Failures will return: ```text theme={null} account_status_invalid ``` #### **Account Capability Validation** When applicable, the Balance type must be supported by the Account's capabilities. Examples: * `credit` Balances require: * `credit_with_underwriting` * or `credit_without_underwriting` * `deposit` Balances require: * `deposit` Failures will return: ```text theme={null} account_capability_missing ``` This validation applies only to Accounts that include a capabilities array (i.e., were created via the Accounts API). ### **What You Need To Do** Before October 6, 2026: 1. Ensure all referenced Accounts have been submitted to and processed by Lead before submitting Balance files. 2. Verify referenced Accounts are in a permitted status. 3. Where capability validation applies, ensure the Account supports the Balance type being created. 4. Review Balance file generation processes for any assumptions that may result in invalid `account_id` references. If Lead identifies existing Balance records that require remediation, we will proactively contact affected partners during Q3 2026. ### **What Happens If You Don't Act** Starting October 6, 2026: * Invalid new Balance records will be rejected. * Balance files containing invalid new records will fail processing. * Downstream transaction and reporting workflows may be delayed until corrected files are submitted. ### Timeline | **Milestone** | **Date** | | - | - | | Announcement | June 10, 2026 | | Sandbox Available | September 22, 2026 | | Effective Date | Wave 1: October 6, 2026 Wave 2: November 10, 2026 | *** **Recommended Review by November 12, 2026** ## **Earlier ACH Posting** **Status:** 🟡 Announced\ **Action Required:** Recommended (partners are recommended to review their time-dependent processes; no enforced deadline)\ **Sandbox Available:** N/A \ **Effective Date:** November 12, 2026 We're moving ACH posting earlier across all settlement windows so you receive money-movement information sooner. Instead of waiting for each Federal Reserve settlement window, we'll post entries as soon as we receive the Fed's advice file for that window. The largest change is in the morning, where entries will post roughly 4 hours earlier than today. ### **What's Changing** Today, ACH entries post to your accounts at approximately the time of their Federal Reserve settlement window — for example, entries settling in the 8:30 a.m. ET (7:30 a.m. CT) morning window post at approximately 8:30 a.m. ET. Starting November 12, 2026, we'll post entries as soon as we receive the Fed's advice file for each window instead of waiting for the window itself. In practice this means: * This applies across all settlement windows, not just the morning window. * Both incoming and outgoing entries — credits and debits — post earlier. * Balances reflect ACH activity earlier in the day, with the largest change in the morning window (roughly 4 hours earlier than today). * Your `ach.posted` webhooks (and any downstream events you consume) fire earlier by the same amount. * The order and content of events do not change. Only the time of day moves. * Exact posting time may vary day to day depending on when we receive the Fed's advice file for each window. Treat the new timing as approximate, not a fixed schedule. There is no change to entry content, event schemas, or APIs. No integration work is required to receive this benefit. ### **Why This Matters** Earlier posting gives you and your customers faster visibility into money movement and faster access to incoming funds. The extra runway each morning gives your teams and systems more time to run fraud and risk review, make funds availability decisions, send customer notifications, and complete reconciliation before the business day starts. If your integration is event-driven, you receive the benefit automatically. If any of your processes assume ACH posts at fixed window times (at or after 8:30 a.m., 1:00 p.m., or 6:00 p.m. ET) — morning reconciliation jobs, batch sweeps, fraud and risk queues, or time-keyed customer notifications — we recommend reviewing them before the effective date. Note that debits post earlier too, so morning available balances may be lower, as well as higher, than they are today. ### Timeline | **Milestone** | **Date** | | - | - | | Announcement | August 13, 2026 | | Effective Date | November 12, 2026 | *** **Required Migration - Date to be announced** ## Wires API V2 Migration **Status:** ⏸️ Delayed\ **Action Required:** Yes (Deadline will be enforced)\ **Sandbox Available:** TBD\ **Effective Date:** TBD We're introducing Wires API V2 to support the upcoming Fedwire ISO 20022 mandate while also providing a foundation for future wire enhancements. This release updates how wire address information is submitted and introduces several improvements, including the ability to distinguish domestic vs. international, updated wire statuses, and future readiness for international wire expansion. ### **Why We're Making This Change** The Federal Reserve plans to introduce additional requirements for Fedwire, including changes to address formatting and message validation. While the release originally planned for November 2026 has been delayed, these requirements are still expected to take effect at a later date. We are moving forward with Wires V2 because the release includes improvements that are valuable independent of the Fedwire timeline and provides the foundation for future wire enhancements. Migrating now will also ensure partners are prepared for the future Fedwire requirements without requiring another breaking API migration later. ### **What's Changing** #### **Structured Address Support** Wire addresses will move from fully unstructured address lines to a hybrid format that includes required structured fields. Examples of new required data include: * Town / City * Country Additional address requirements are documented in the [V2 Create-a-Wire API reference](/api-reference/endpoint/wire/create-a-wire-v2) and [V2 Migration Guide](/products/wire/v2-migration). #### **New Wire Attributes** Wires API V2 also introduces: * A new `corridor_type` field to indicate whether a wire is domestic or international * The consolidation of routing numbers into `local_routing_identifier` * Additional infrastructure to support future international wire enhancements ### **What You Need To Do** Before the migration deadline: 1. Update your Wires API integration to use the V2 specification. 2. Review any integrations that consume wire statuses. 3. Validate your implementation in sandbox once testing becomes available. ### **What Happens If You Don't Act** After the migration deadline: * Lead no longer supports V1 integrations. * Lead rejects wires that use unsupported address formats. ### **Timeline** | **Milestone** | **Date** | | :- | :- | | Announcement | June 10, 2026 | | Sandbox Available | TBD | | Migration Deadline | TBD | | ISO 20022 Enforcement | November 2027 | ### **Additional Resources** * [Wires API V2 Reference](/api-reference/endpoint/wire/create-a-wire-v2) * [Wires API V2 Migration Guide](/products/wire/v2-migration) *** **Required Migration by March 31, 2027** ## Receivable Sales and Receivables APIs **Status:** 🟡 Announced\ **Action Required:** Yes (Migration required; switchover date coordinated with Lead)\ **Sandbox Available:** Second half of Q4 2026 (Planned)\ **Effective Date:** March 31, 2027 We're migrating the receivable sales process from Sales Request/Response files to an API-native experience. With the new Receivable Sales and Receivables APIs, you can purchase loan and credit card receivables independent of any other workflow. Today, completing a Receivable Sale depends on your Balance and Transaction files processing successfully. Reconciliation discrepancies can block file processing and hold up a Receivable Sale. The new APIs remove that dependency. ### **Why We're Making This Change** Tying Receivable Sales to file processing means a reconciliation discrepancy can block an otherwise valid Receivable Sale. Moving to an API-native model decouples the two, streamlines the sales process, and gives you a simpler, more reliable way to complete purchases and inspect what's being sold. ### **What's Changing** * Lead generates a Receivable Sale daily, which triggers a webhook for you to process. On a scheduled daily basis, Lead debits your account for the purchase amount. * You can inspect any Receivable Sale through the Receivables API to confirm what's being sold before it settles. * Your Receivable Sale obligations are no longer tied to successful Balance and Transaction file processing. Reconciliation discrepancies that previously blocked file processing will not affect your ability to complete a Receivable Sale. * Receivable Sale objects communicate the aggregate amount for purchase across all receivables. * Receivable objects communicate the individual receivables that comprise a Sale (for example, term loans or credit card settlements). For a given day, Lead represents the total network settlement as a single aggregate receivable rather than listing out the individual transactions that comprise it. Imputed interest will be calculated on the principal amount Lead has extended as credit, rather than being adjusted for payments or refunds you report during the hold period. This keeps the calculation consistent regardless of your file processing status. ### **What You Need To Do** Before your switchover date: 1. Migrate your integration to the Receivable Sales and Receivables APIs. 2. Coordinate a switchover date with Lead. 3. Test the full Receivable Sale and Receivable flow in sandbox once it becomes available (targeted for the second half of Q4 2026). New programs will integrate against the API directly. ### **What Happens If You Don't Act** The file-based Sales Request/Response process is being retired for in-scope programs. Partners that do not migrate by their coordinated switchover date risk disruption to their receivable sales process. ### **Related Work** In addition to these APIs, we're also building out a full suite of APIs. This includes Balance and Transaction APIs. Lead will compute balances so partners do not need to report these. Lead will attribute any Transactions it processes (eg. ACH transactions processed via Lead) to their corresponding Balances automatically. The Transaction APIs are primarily how you'll report transactions that occur outside Lead's systems (e.g. card transactions). This is a meaningfully lighter reporting integration than today's files; while partners are not required to migrate to both these APIs and the Receivable Sales and Receivables APIs at the same time, we want to highlight that there is an opportunity to migrate all integration touch-points from file to API. We'll share more details in a separate announcement. ### **Timeline** | **Milestone** | **Date** | | :- | :- | | Announcement | August 20, 2026 | | Sandbox Available | Second half of Q4 2026 (Planned) | | Migration Deadline | March 31, 2027 | *** **Migration Deadline TBD** ## Entity and Applications APIs v2 **Status:** 🟡 Announced\ **Action Required:** Not yet (a migration deadline will be announced here)\ **Sandbox Available:** December 2026 (planned beta)\ **Effective Date:** TBD We're releasing Entity v2 and Applications v2 as part of the unified object model. Both are in preview now, with a planned beta release in December 2026. Preview APIs are not yet available in sandbox or production and can change before beta, so use the v2 pages to plan an integration, not to build one. Once released in beta, they will be available to all partners in sandbox, and in production for select programs. ### **Why We're Making This Change** Today the Entity API cannot show who holds your core accounts, because Lead and your company are not visible entities. Eligibility comes back as `role_details`, an array you have to search, with failing checks nested two levels down. Document references on entities and applications are filenames for files sent over SFTP, not files linked through the API. v2 fixes these together, along with the v2 error and idempotency rules, so you migrate once. ### **What's Changing** **Entity v2** * New read-only `lead` and `partner` entity types. They hold your core accounts, and you read them with `GET /v2/entities/{id}`. * `intended_roles` becomes `intended_eligibility`, with the same values and the same all-or-nothing check. v2 ignores `intended_roles` if you send it and returns no error, so rename the field before you switch, or Lead does not check the types you list. * On beneficial owners and control persons, `relationship_established_at` becomes `relationship_established_date`. In `credit_details`, `credit_report_non_score_value` becomes `no_credit_score_reason`, with the same values. * `role_details` becomes `eligibility`, an object keyed by relationship type with all four keys always present. Each entry has a `status` of `eligible` or `ineligible` and a `failed_checks` array with the check, the `entity_id` that failed, and a `reason`. * Check names move from PascalCase to snake\_case, like `CheckKYCStatus` to `check_kyc_status`. v2 adds `check_individual_entity` and `check_minor_account_holder_enabled`. * `client_customer_id` is response only. Lead ignores it if you send it on a request, so it no longer prevents duplicate entities the way v0's `409` did. It is still returned on entities created through Customer files. `GET /v2/entities?client_customer_id=` returns a list of matching entities, empty when nothing matches, instead of one entity or a `404`. * Each document entry takes either a `file_id` from the Files API, in place of `client_document_id`, or a `type` when you do not have a file. When you link a file, Lead takes the type from the file and checks that the file exists. Documents you sent on v0 appear in read-only `legacy_*` arrays. * Changing an entity's documents no longer needs a new `kyc_details`. Name, date of birth, and tax ID changes still do. **Applications v2** * `details.product_name` moves to the top level as `product_name`, and `details.credit` is renamed `details.underwriting`, with `currency` renamed `currency_code`. v2 ignores the old names. A `POST` that uses them fails because `product_name` and `details.underwriting` are required, and a `PATCH` that uses them returns `200` without changing the application. * Document entries reference a `file_id` from the Files API in place of `document_id`, and Lead checks that the file exists, belongs to your program, and has a compliance document type. The document type is declared on the file when you upload it, so entries no longer carry `type`. `displayed_at` and `consented_at` become a single `timestamp`. Documents you sent on v0 appear in a read-only `legacy_documents` array. * Lead no longer rejects a duplicate application with a `409`. Reuse the same `Idempotency-Key` when you retry a `POST`, so a retry does not create a second application. * `GET /v2/applications?client_application_id=` returns a list, `{ objects, has_more }`. No match returns `200` with an empty `objects`, not a `404`. * `entities.account_holder_type` is response only. Lead derives it from the account holders and ignores it if you send it. * Lead checks that every entity exists on every status, not only on `approved`. * Applications you reported in an Application file before a decision can be `submitted` or `under_review`. Both are read only, and those applications have no `decision`. * `PATCH` does not accept `null`, so you cannot clear a field once it is set. **Both** * IDs do not change. Entities and applications you created on v0 are readable and updatable on v2. * v2 returns errors in the shape on [Errors](/api-reference/using-the-api/errors-v2), and authentication failures return `403` instead of `401`. * Every `POST` and `PATCH` requires an `Idempotency-Key` header. Lead caches only successful responses, so you can retry a failed request with the same key. See [Idempotency](/api-reference/using-the-api/idempotency-v2). * v2 ignores request fields it does not recognize, including v0 field names, and returns no error. Rename v0 fields before you switch. ### **What You Need To Do** Nothing yet. v0 keeps working unchanged until its sunset date, which will be announced here with sandbox time before you have to move. To plan your migration, start with the [Entity v2 overview](/v2/products/entity/overview) and the [Applications v2 overview](/v2/products/applications/overview). ### Timeline | **Milestone** | **Date** | | - | - | | Announcement (preview docs) | October 2026 | | Sandbox Available (Beta) | December 2026 (planned) | | Production (Beta, select programs) | December 2026 (planned) | | v0 Sunset | TBD | ### **Additional Resources** * [Entity v2](/v2/products/entity/overview) · [The Entity Object](/v2/products/entity/entity-object) · [Entity Eligibility](/v2/products/entity/eligibility) * [Applications v2](/v2/products/applications/overview) · [The Application Object](/v2/products/applications/application-object) · [Application Statuses](/v2/products/applications/statuses) # API Overview, OAuth Authentication, and IP Allowlist Source: https://docs.lead.bank/api-reference/using-the-api/authentication Authenticate to Lead's REST APIs with OAuth2, choose the right access token scopes, and configure your IP allowlist for production traffic. > [!WARNING] > > **Upcoming Change** > > OAuth access tokens will be cached for up to 23 hours and must be reused until expiration. Partners requesting a new token before every API call will need to update their authentication implementation before enforcement begins. > > 👉 [View Details](/upcoming-changes#oauth-access-token-caching) ## Introduction Lead's APIs are [REST](https://en.wikipedia.org/wiki/Representational_state_transfer)-based, accept and return JSON-encoded payloads, and use standard HTTP response codes, authentication, and verbs. ## Authentication Lead uses [OAuth2](https://oauth.net/2/) for Authentication. When we onboard your program, you will be set up with a `client_id` and a `client_secret`. These credentials can be used to retrieve an `access_token` which you will use to authenticate further requests. > [!TIP] > > By default, access tokens have a 24 hour expiry, and will need to be replaced before they expire. See the `expires_in` passed in the token response to track the TTL (time-to-live). They can also be limited to certain API scopes which can help you with access control while preventing unauthorized requests. ### Steps **1. Get Access Token** Use your `client_id` and `client_secret` to get an `access_token` with the [Authentication API](/api-reference/endpoint/oauth/get-an-access-token). **2. Authenticate Requests** Use the `access_token` in the `'authorization: Bearer '` header to authenticate further API requests. ### Available scopes Pass one or more of the following values in the `scope` parameter of the [token request](/api-reference/endpoint/oauth/get-an-access-token) (space-delimited) to provision an access token. Request the least-privileged scope appropriate to the operation. A token presented to an endpoint that requires a scope it was not provisioned for returns `403`. Requesting a scope your program is not provisioned for in the token request itself also returns `403` with code `insufficient_scope`. | Scope | Resource | Access | | :- | :- | :- | | `account/read` | Accounts | Read | | `account/read_write` | Accounts | Read/write | | `account_number/read` | Account Numbers | Read | | `account_number/read_write` | Account Numbers | Read/write | | `ach/read` | ACH | Read | | `ach/read_write` | ACH | Read/write | | `application/read` | Applications | Read | | `application/read_write` | Applications | Read/write | | `blockchain_payment/read` | Blockchain Payments | Read | | `blockchain_payment/read_write` | Blockchain Payments | Read/write | | `card/read` | Cards | Read | | `card/read_write` | Cards | Read/write | | `card_network_settlement/read_write` | Receivables | Sandbox simulation of card network settlements | | `core_account/read` | Core Accounts | Read | | `core_balance/read` | Core Balances | Read | | `core_transaction/read` | Core Transactions | Read | | `entity/read` | Entities | Read | | `entity/read_write` | Entities | Read/write | | `event/read` | Webhook Events | Read | | `file/read` | Files | Read | | `file/read_write` | Files | Read/write | | `funding/read` | Funding | Read | | `funding/read_write` | Funding | Read/write | | `instant_payment/read` | Instant Payments | Read | | `instant_payment/read_write` | Instant Payments | Read/write | | `internal_transfer/read` | Internal Transfers | Read | | `internal_transfer/read_write` | Internal Transfers | Read/write | | `lending/read` | Lending | Read | | `lending/read_write` | Lending | Read/write | | `receivable/read` | Receivables | Read | | `receivable_sale/read` | Receivable Sales | Read | | `subledger_balance/read` | Subledger Balances | Read | | `subledger_balance/read_write` | Subledger Balances | Read/write | | `user_account/read` | User Accounts | Read | | `user_account/read_write` | User Accounts | Read/write | | `user_credit_balance/read` | User Credit Balances | Read | | `user_credit_balance/read_write` | User Credit Balances | Read/write | | `user_credit_transaction/read` | User Credit Transactions | Read | | `user_credit_transaction/read_write` | User Credit Transactions | Read/write | | `wire/read` | Wires | Read | | `wire/read_write` | Wires | Read/write | > [!NOTE] > > There is no separate `originator/*` scope for the `/v0/originators` endpoints. If you're unsure which scope a specific endpoint requires, contact your Technical Account Manager. ## IP Allowlist An IP allowlist restricts API access to a predefined set of approved IPv4 addresses or subnets. Requests originating from addresses outside the allowlist are rejected. This provides an additional layer of protection by ensuring that only trusted networks can access the API. ### Configuration Each API partner can be configured with a set of allowed IP subnets. When a request is received, the API server validates the request’s source IP address against the configured allowlist: * If the source IP address falls within an allowed subnet, the API processes the request. * If the source IP address doesn't match any allowed subnet, the API rejects the request with status code `403`. The error code depends on the API version: ```http v2 theme={null} HTTP/1.1 403 Forbidden { "code": "source_ip_not_permitted", "message": "This request came from an IP address that isn't on your program's allowlist. Send from an allowlisted IP, or contact Lead to update the list." } ``` ```json v1 theme={null} { "status": 403, "code": "source_ip_not_allowed", "title": "Requests from this IP address are not permitted for this program.", "invalid_parameters": [ { "parameter": "source_ip", "reason": "source IP not allowed for program" } ] } ``` For the full list of error codes, see [Errors for v2](/api-reference/using-the-api/errors-v2) or [Errors for v1](/api-reference/using-the-api/errors). ### Setup To utilize Lead’s IP allowlist feature: **1. Provide Lead With Your IP Subnets** Give them to your Technical Account Manager. **2. Specify Each Subnet** Use [CIDR notation](https://en.wikipedia.org/wiki/Classless_Inter-Domain_Routing). **Configuration limits:** * Maximum subnets: 30 * Supported IP version: IPv4 only * Supported CIDR prefix lengths: /20 to /32 * Broader ranges such as /16 or /8 are not supported. ### Unsupported IP Addresses The following IP address types cannot be included in the IP allowlist. **IPv6 addresses** * Only IPv4 addresses are supported. **Private IP ranges** * `10.0.0.0/8` * `172.16.0.0/12` * `192.168.0.0/16` **Loopback addresses** * `127.0.0.0/8` **Link-local addresses** * `169.254.0.0/16` **Invalid formats** * Any address not in valid IPv4 format (`x.x.x.x`, where each octet is between 0 and 255). # Instant Payments at Lead Source: https://docs.lead.bank/products/instant-payments/overview Send and receive Instant Payments via FedNow and RTP > [!WARNING] > > RTP support is coming to the Instant Payments API in November 2026. Existing integrations will send and receive over both FedNow and RTP with no code changes. Lead will select the rail for each payment behind the scenes and expose it in a new `payment_rail` field. Lead offers Instant Payments as a single interface over two underlying rails: FedNow and RTP. FedNow and RTP (Real-Time Payments) are operated by the Federal Reserve and The Clearing House, respectively. Both are U.S. domestic, credit-push, 24/7/365 networks that support payments up to \$10 million per transaction that settle in seconds. Receivers on both networks must make funds available to the creditor immediately. Neither network supports payment reversals. Instead, return requests are used to attempt recovery of payments sent erroneously. # Payment Identifiers Source: https://docs.lead.bank/products/instant-payments/payment-identifiers Reference end_to_end_id, transaction_id, and uetr identifiers used to track FedNow and RTP instant payments and returns across the Lead network. The `instant_payment` object has an `id` of the form `instant_payment_xyz123` that references it internally within the Lead network. Additionally, Lead exposes three identifiers that identify a payment message within its payment network. None of these identifiers are configurable through the `instant_payments` API. Instead, Lead sets them automatically for outgoing payments and the counterparty sets them for incoming payments. 1. `end_to_end_id` is the mandatory "trace id" for instant payments that must pass through from debtor to creditor unchanged. Use it to reference a payment with the end customer or a counterparty. `end_to_end_id` is a max of 35 characters and is expected to be unique. 2. `transaction_id` is an optional identifier assigned by the debtor or initiating party that may also be used to reference a specific payment on the network. `transaction_id` is a max of 35 characters and is expected to be unique. 3. `uetr` is an optional identifier assigned by the debtor or initiating party that may also be used to reference a specific payment on the network. `uetr` is a UUIDv4 that is expected to be globally unique. ## Payments Payments will include two or three payment identifiers which depend on the underlying rail and the party initiating the payment. Outgoing payments from Lead will always have all three identifiers populated. FedNow and RTP require usage of `end_to_end_id` because it is the primary identifier to track a payment with a counterparty or an end customer. FedNow also mandates use of either `transaction_id` or `uetr`, but RTP mandates `transaction_id` and leaves `uetr` as optional. | Instant Payment ID | Required by FedNow? | Required by RTP? | Network Message ID | Validation | | - | - | - | - | - | | `end_to_end_id` | Yes | Yes | `EndToEndId` | Max 35 characters | | `transaction_id` | Yes if `uetr` is null | Yes | `TxId` | Max 35 characters | | `uetr` | Yes if `transaction_id` is null | No | `UETR` | UUID V4 | ## Returns Payments and returns both utilize their own `instant_payment` object. Returns are identified with a non-null `instant_payment.related_objects.original_payment_id`. FedNow returns do not have any of their own `instant_payment.payment_identifiers`. To reference a FedNow return, use the `end_to_end_id` of the original payment. RTP returns, however, support the same set of identifiers that the original payment supports. To reference an RTP return, simply look at the `end_to_end_id` of the return itself. | Instant Payment ID | Required by FedNow? | Required by RTP? | | :- | :- | :- | | `end_to_end_id` | Unsupported | Yes | | `transaction_id` | Unsupported | Yes | | `uetr` | Unsupported | No | # Receiving Instant Payments Source: https://docs.lead.bank/products/instant-payments/receiving-instant-payments Receive Instant Payments and Return Requests There are two requirements for receiving instant payments. All users of instant payments must implement the first requirement. However, we recommend implementing both because receiving return requests, particularly in cases of fraud, promote network health and safety. 1. **Receiving Payments:** Handle the receipt of incoming instant payments. 2. **Receiving Return Requests:** Handle the receipt of incoming return requests related to instant payments previously received. ## Receiving Payments Receiving an incoming instant payment creates a new `instant_payment` object with an incoming direction. ### Statuses Incoming `instant_payment` objects have three potential statuses during their lifecycle, all of which trigger a webhook. | **Instant Payment Status** | **Description** | **Webhook** | | - | - | - | | `under_review` | Lead is manually reviewing the incoming instant payment. | Yes | | `posted` | Lead posted the incoming instant payment to your account. | Yes | | `rejected` | Lead rejected the incoming instant payment. | Yes | ```mermaid theme={null} graph TD subgraph Incoming instant_payment F(["START"]) H(["rejected"]) I(["under_review"]) J(["posted"]) F --> J F -- "Lead manual review"--> I I -- "Manual review failure" --> H I -- "Manual review success" --> J F -- "Lead validation failure" --> H end subgraph State Key direction LR X([Start]) Y([Pending]) Z([Terminal]) end linkStyle 0 stroke:#155724,stroke-width:2px; classDef startStyle fill:#d4edda,stroke:#155724,stroke-width:3px; classDef progressStyle fill:#e1f5fe,stroke:#03a9f4,stroke-width:3px; classDef terminalStyle fill:#eceff1,stroke:#455a64,stroke-width:3px; class F,A,X startStyle; class I,Y progressStyle; class C,D,H,J,Z terminalStyle; ``` ### Events For incoming instant payments, the only event you must handle is `posted`. Upon this event, you are required to notify your customers that the transferred funds are now available. You have the option to also act on the `under_review` and `rejected` events if you choose. | **Event** | **Description** | **Your Action** | | :- | :- | :- | | `.under_review` | Lead is manually reviewing the incoming instant payment. | (Optional) Inform your customer that incoming funds are pending. | | `.posted` | Lead posted the incoming instant payment to your account. | (Mandatory) Inform your customer of available funds. | | `.rejected` | Lead rejected the incoming instant payment. | (Optional) Look at the rejection hash to investigate why rejection occurred. | ### Endpoints Incoming instant payments require no further action on your part. However, if the original incoming payment was defective (e.g., fraud, duplicate, or technical error), a return may be requested. ## Receiving Return Requests The counterparty financial institution will send a `return_request` if they want a payment they previously sent to be returned. The `return_request` is structured as a sub-object of the original `instant_payment`.  > [!TIP] > > A single `instant_payment` may eventually have multiple `return_request` sub-objects. However, only one incoming `return_request` will require a response at any given time. ### Statuses The lifecycle of a `return_request` sub-object begins after the original `instant_payment` reaches posted status. The only incoming `return_request` status that triggers an event is `response_needed`. | Return Request Status | Description | Webhook | | :- | :- | :- | | `response_needed` | You received an incoming return request that requires a response from you. | Yes | | `accepted` | You accepted the incoming return request by initiating an outgoing return. | No | | `rejected` | You rejected the incoming return request and provided a reason why. | No | ```mermaid theme={null} graph TD subgraph 2: Incoming return_request A(["response_needed"]) C(["accepted"]) D(["rejected"]) A -- "You return" --> C A -- "You reject" --> D end subgraph 1: Incoming instant_payment F(["START"]) H(["rejected"]) I(["under_review"]) J(["posted"]) F --> J F -- "Lead manual review"--> I I -- "Manual review failure" --> H I -- "Manual review success" --> J F -- "Lead validation failure" --> H end subgraph State Key direction LR X([Start]) Y([Pending]) Z([Terminal]) end linkStyle 2 stroke:#155724,stroke-width:2px; classDef startStyle fill:#d4edda,stroke:#155724,stroke-width:3px; classDef progressStyle fill:#e1f5fe,stroke:#03a9f4,stroke-width:3px; classDef terminalStyle fill:#eceff1,stroke:#455a64,stroke-width:3px; class F,A,X startStyle; class I,Y progressStyle; class C,D,H,J,Z terminalStyle; ``` ### Events The `return_request_response_needed` event indicates that a new return request has been received which requires your response and a potential return of funds as soon as possible. Listening to this event and taking action is required. | **Event** | **Description** | **Your Action** | | :- | :- | :- | | return\_request\_response\_needed | You received an incoming return request that requires a response from you. | (Mandatory) Begin your review process and respond as soon as possible, or, at the latest, by the 10th business day. | ### Endpoints The rejection endpoint is below. Accepting a return request is combined with the return endpoint itself which is covered in the [returns and rejections](/products/instant-payments/rejections-and-returns) section. > [!WARNING] > > For incoming return requests, you are required to investigate and respond by accepting or rejecting the request as soon as possible or, at the latest, by the 10th business day. If this deadline is not met, Lead will automatically reject the return request on your behalf to maintain our compliance with network requirements. | **Endpoint** | **Description** | | :- | :- | | `POST /instant_payments/{id}/reject_return_request` | Reject the active return request associated with an instant payment. | # Returns & Rejections Source: https://docs.lead.bank/products/instant-payments/rejections-and-returns Return Instant Payments and handle common exceptions # Returns Returning payments is important because instant payments are push-only from debtor to creditor and irrevocable. Returning an instant payment creates a new `instant_payment` object with an `outgoing` direction. Additionally, the active `return_request` sub-object of the original payment, if one exists, moves into `accepted` status automatically. This section includes the subset of statuses and events that relate to returns only. > [!NOTE] > > Returns are a type of outgoing instant payments, which are covered extensively on the [Sending](/products/instant-payments/sending-instant-payments) page. ### Endpoints You can initiate returns regardless of whether or not an active return request exists. > [!WARNING] > > For incoming return requests, you are required to investigate and respond by accepting or rejecting the request as soon as possible or, at the latest, by the 10th business day. If this deadline is not met, Lead will automatically reject the return request on your behalf to maintain our compliance with network requirements. | **Endpoint** | **Description** | | :- | :- | | `POST /instant_payments/{id}/return` | Return an instant payment that was previously received. If there is an outstanding return request, calling this endpoint will also accept the return request. | ### Statuses Outgoing returns, once initiated, will transition through four possible statuses. If an active return request is present, it will move to the `accepted` status after Lead validates the outgoing return. > [!WARNING] > > The status of a return request is not the authoritative source of payment success. Accepting a return request represents an intention to send a return but is not a guarantee of it. | **Instant Payment Status** | **Description** | **Webhook** | | :- | :- | :- | | `created` | Lead created the outgoing return. | No | | `under_review` | Lead is manually reviewing the outgoing return before sending it to the network. | Yes | | `posted` | Lead posted the outgoing return to your account. | Yes | | `rejected` | Lead, the counterparty, or the network rejected the outgoing return. | Yes | | **Return Request Status** | **Description** | **Webhook** | | :- | :- | :- | | `accepted` | You accepted the incoming return request by initiating an outgoing return. | No | ```mermaid theme={null} graph TD subgraph 2: Outgoing instant_payment return A(["created"]) B(["under_review"]) C(["rejected"]) E(["posted"]) A --> E A -- "Lead manual review" --> B A -- "Lead validation failure or network or counterparty rejection" --> C B -- "Manual review success" --> E B -- "Manual review failure" --> C end subgraph 1: Incoming return_request D(["response_needed"]) F(["accepted"]) G(["rejected"]) D -- "You accept" --> F D -- "You reject" --> G end subgraph State Key direction LR T([Start]) U([Pending]) V([Terminal]) end linkStyle 2 stroke:#155724,stroke-width:2px; classDef startStyle fill:#d4edda,stroke:#155724,stroke-width:3px; classDef progressStyle fill:#e1f5fe,stroke:#03a9f4,stroke-width:3px; classDef terminalStyle fill:#eceff1,stroke:#455a64,stroke-width:3px; classDef invisible fill:none,stroke:none class A,D,T startStyle; class B,U progressStyle; class C,E,F,G,V terminalStyle; class Z invisible; ``` ### Events Tracking the outgoing return requires listening to a broad set of events. These events cover exceptions and notifications when the funds returned are now available to the receiving party. | **Event** | **Description** | **Your Action** | | :- | :- | :- | | `.under_review` | The outgoing return is pending manual review from Lead before it will be sent to the network. | (Optional) Notify your customer that the return has not yet been submitted to the network. | | `.rejected` | The outgoing return has been rejected by Lead, the counterparty, or the network. | (Optional) Notify your customer that the return has been rejected. | | `.posted` | The outgoing return has been posted to the Lead account. | (Optional) Notify your customer that the funds for the return have left their account. | | `.counterparty_status_updated` | The counterparty status of the outgoing return has been updated. | (Optional) If the counterparty\_status is posted, notify your end customer that the return was successfully received by the recipient. | # Rejections Rejections surface on the `instant_payment` object's `rejection` hash, which carries `rejected_by`, `reason`, and `details`. Unless a case says otherwise, handle the `.rejected` webhook and read those fields. ## Outgoing payment rejected by Lead or the network The payment never reached the counterparty. `rejected_by` is `lead` or `network`. Follow up with Lead if the reason is unclear. ## Outgoing payment rejected by the counterparty Lead submitted the payment to the network and the counterparty rejected it. `rejected_by` is `counterparty`. Retry if appropriate. ## Outgoing payment posted but subsequently rejected by counterparty The outgoing payment reached `posted` status and completed its lifecycle, but `counterparty_status` changed to `rejected` afterward. Listen for `.counterparty_status_updated` rather than `.rejected` to inspect the rejection reason. Expect the counterparty to send the funds back as a separate return, which arrives as its own incoming `instant_payment` with a `.posted` webhook. Reconcile it against the original through `related_objects.original_payment_id`. ## Incoming payment rejected by account number controls Lead rejected an incoming payment, most often because of your configured [account number controls](/api-integrations/account-number/controls), which govern who may send to an account number. If the rejections are unexpected, update the controls. ## Incoming payment accepted but subsequently rejected Account number controls are the only way to refuse an incoming payment before it posts. If you want to implement other rejection criteria, simply return the payment after it posts with `POST /instant_payments/{id}/return`, which creates a new outgoing return payment. # Sandbox Testing Source: https://docs.lead.bank/products/instant-payments/sandbox-testing Test your Instant Payments integration Instant payments in sandbox use the same endpoints as production. Unlike ACH and wire transfers, instant payment statuses advance automatically in sandbox — you do not need to call a simulation endpoint to move an outgoing payment from `created` to `posted`. A few practical notes when testing: * **Routing numbers.** Lead does not publish a fixed list of designated sandbox routing numbers for instant payments. Any well-formed routing number can be used in the `creditor_agent.routing_number` (outgoing) or `debtor_agent.routing_number` (simulated incoming) field. The values shown in code examples (such as `987654321`) are illustrative, not reserved test values. * **Availability checks.** Call `POST /instant_payments/check_availability` first to confirm the routing number is reachable on the network before sending. * **Simulating an inbound payment.** Use `POST /v1/simulate/instant_payments/incoming` and supply your own `debtor_agent.routing_number`. The value is not validated against a real network. * **Simulating a return.** Use `POST /v1/simulate/instant_payments/{instant_payment_id}/incoming_return` against an existing posted outgoing payment. If you need a specific routing number to exercise a particular code path in sandbox, contact your Technical Account Manager. # Sending Instant Payments Source: https://docs.lead.bank/products/instant-payments/sending-instant-payments Send Instant Payments and Return Requests There are two requirements for sending instant payments. We recommend implementing both of these functions because instant payments, once sent, cannot be reversed. 1. **Sending Payments:** Send outgoing instant payments.  2. **Sending Return Requests:** Send outgoing return requests to recover funds sent erroneously in previous outgoing instant payments. > [!WARNING] > > If your customers are victims of fraud or send payments erroneously, return requests are the only recourse to recover their funds. ## Sending Payments Sending an instant payment creates a new `instant_payment` object with an outgoing direction. ### Endpoints You can check if the recipient's financial institution is available on the instant payment network and, if available, send instant payments to them. Once sent, outgoing instant payments can also be canceled. However, the cancellation window is very short and only possible if Lead has not yet submitted the payment to the network. This limited opportunity may occur during normal system processing or periods of manual review. | **Endpoint** | **Description** | | :- | :- | | `POST /instant_payments/check_availability` | Check the availability of a financial institution to accept instant payments. | | `POST /instant_payments` | Send an outgoing instant payment. | | `POST /instant_payments/{id}/cancel` | Attempt to cancel an outgoing instant payment. | ### Statuses Outgoing instant payments can transition through five potential statuses. Unlike returns, outgoing instant payments can terminate in the `canceled` status. The `counterparty_status` lifecycle only begins after the `instant_payment` object has reached a `posted` status. The purpose of this lifecycle is to precisely describe if/when the outgoing payment reaches the creditor. | **Instant Payment Status** | **Description** | **Webhook** | | :- | :- | :- | | `created` | Lead created the outgoing instant payment. | No | | `under_review` | Lead is manually reviewing the outgoing instant payment before sending it to the network. | Yes | | `canceled` | You canceled the outgoing instant payment. | No | | `posted` | Lead posted the outgoing instant payment to your account. | Yes | | `rejected` | Lead, the counterparty, or the network rejected the outgoing instant payment. | Yes | | **Counterparty Status** | **Description** | **Webhook** | | :- | :- | :- | | `under_review` | The counterparty is manually reviewing your payment before posting it to the creditor's account. | Yes | | `posted` | The outgoing instant payment posted to the creditor's account. | Yes | | `rejected` | The counterparty rejected your payment before it reached the creditor's account. | Yes | ```mermaid theme={null} graph TD subgraph Outgoing instant_payment A(["created"]) B(["under_review"]) C(["rejected"]) J(["canceled"]) E(["posted"]) A --> E A -- "Lead manual review" --> B A -- "Lead validation failure or network or counterparty rejection" --> C B -- "Manual review success" --> E B -- "Manual review failure" --> C A -- "You canceled" --> J B -- "You canceled" --> J end subgraph State Key direction LR T([Start]) U([Pending]) V([Terminal]) end linkStyle 0 stroke:#155724,stroke-width:2px; classDef startStyle fill:#d4edda,stroke:#155724,stroke-width:3px; classDef progressStyle fill:#e1f5fe,stroke:#03a9f4,stroke-width:3px; classDef terminalStyle fill:#eceff1,stroke:#455a64,stroke-width:3px; classDef invisible fill:none,stroke:none class A,D,W,T startStyle; class B,X,U progressStyle; class C,E,F,G,J,Y,Z,V terminalStyle; ``` ### Events You can follow the status of an outgoing payment event throughout its entire lifecycle - from initiation at Lead to subsequent events at the counterparty financial institution. | **Event** | **Description** | **Partner Action** | | :- | :- | :- | | `.under_review` | The outgoing instant payment is pending manual review from Lead before it will be sent to the network. | (Optional) Notify your customer that the instant payment has not yet been submitted to the network. | | `.rejected` | The outgoing instant payment has been rejected by Lead, the counterparty, or the network. | (Optional) Notify your customer that the instant payment has been rejected. | | `.posted` | The outgoing instant payment has been posted to the Lead account. | (Optional) Notify your customer that the funds for the instant payment have left their account. | | `.counterparty_status_updated` | The counterparty status of the outgoing instant payment has been updated. | (Optional) If the counterparty\_status is posted, notify your end customer that the instant payment was successfully posted to the creditor. | ## Sending Return Requests Sending a return request creates a new `return_request` sub-object within the existing outgoing `instant_payment`. ### Endpoints You can create a return request if you previously sent an instant payment and need to recover it. | **Endpoint** | **Description** | | :- | :- | | `POST /instant_payments/id/request_return` | Send an outgoing return request to the counterparty for a previously posted outgoing instant payment. | ### Statuses Outgoing return requests transition through three possible statuses from when the counterparty receives them through when they are ultimately resolved. | **Outgoing Status** | **Description** | **Webhook** | | :- | :- | :- | | `pending` | The outgoing return request is pending a response from the counterparty. | No | | `accepted` | The outgoing return request was accepted by the counterparty. | Yes | | `rejected` | The outgoing return request was rejected by the counterparty. | Yes | ```mermaid theme={null} graph TD subgraph 2: Outgoing return_request D(["pending"]) F(["accepted"]) G(["rejected"]) D -- "Counterparty accepted" --> F D -- "Counterparty rejected" --> G end subgraph 1: Outgoing instant_payment A(["created"]) B(["under_review"]) C(["rejected"]) J(["canceled"]) E(["posted"]) A --> E A -- "Lead manual review" --> B A -- "Lead validation failure or network or counterparty rejection" --> C B -- "Manual review success" --> E B -- "Manual review failure" --> C A -- "You canceled" --> J B -- "You canceled" --> J end subgraph State Key direction LR T([Start]) U([Pending]) V([Terminal]) end linkStyle 0 stroke:#155724,stroke-width:2px; classDef startStyle fill:#d4edda,stroke:#155724,stroke-width:3px; classDef progressStyle fill:#e1f5fe,stroke:#03a9f4,stroke-width:3px; classDef terminalStyle fill:#eceff1,stroke:#455a64,stroke-width:3px; classDef brownStyle fill:#efebe9,stroke:#5d4037,stroke-width:2px; classDef invisible fill:none,stroke:none class A,D,W,T startStyle; class B,X,U progressStyle; class C,E,F,G,J,Y,Z,V terminalStyle; class H,I brownStyle; ``` ### Events Tracking an outgoing return request involves listening to a single event that is triggered upon each status change. | **Event** | **Description** | **Your Action** | | :- | :- | :- | | `.return_request_status_updated` | The status of the outgoing return request has been updated. | (Optional) Notify your customer that the outgoing return request has been accepted or rejected. | # Statuses Source: https://docs.lead.bank/products/instant-payments/statuses View the status, counterparty status, and return request status for incoming and outgoing Instant Payments Use `status` to understand the Lead-side lifecycle of an instant payment, `counterparty_status` to understand the counterparty-side lifecycle for outgoing payments after the payment reaches `posted`, and the return\_request status to understand the lifecycle of a return request that references the given instant payment. ## Status | **Status** | **Description** | Direction | | :- | :- | - | | `created` | Lead created the outgoing instant payment. | Outgoing only | | `under_review` | Lead is manually reviewing the instant payment. | Incoming and outgoing | | `canceled` | You canceled the outgoing instant payment. | Outgoing only | | `posted` | Lead posted the instant payment to your account. | Incoming and outgoing | | `rejected` | Lead, the counterparty, or the network rejected the instant payment. | Incoming and outgoing | ## Counterparty Status | **Counterparty Status** | **Description** | **Direction** | | :- | :- | :- | | `under_review` | The counterparty is manually reviewing your outgoing payment before posting it to the creditor's account. | Outgoing only | | `posted` | The instant payment posted to the creditor's account. | Incoming and outgoing | | `rejected` | The counterparty rejected your outgoing payment before it reached the creditor's account. | Outgoing only | ## Return Request Status | Return Request Status | Description | Direction | | :- | :- | :- | | `response_needed` | The incoming return request requires a response from you. | Incoming only | | `pending` | The outgoing return request is pending a response from the counterparty. | Outgoing only | | `accepted` | The return request was accepted and a return is expected. | Incoming and outgoing | | `rejected` | The return request was rejected. | Incoming and outgoing | # Incoming Payments ```mermaid theme={null} graph TD subgraph 2: Incoming return_request status A(["response_needed"]) C(["accepted"]) D(["rejected"]) A -- "You return" --> C A -- "You reject" --> D end subgraph 1: Incoming status F(["START"]) H(["rejected"]) I(["under_review"]) J(["posted"]) F --> J F -- "Lead manual review"--> I I -- "Manual review failure" --> H I -- "Manual review success" --> J F -- "Lead validation failure" --> H end subgraph State Key direction LR X([Start]) Y([Pending]) Z([Terminal]) end linkStyle 3 stroke:#155724,stroke-width:2px; classDef startStyle fill:#d4edda,stroke:#155724,stroke-width:3px; classDef progressStyle fill:#e1f5fe,stroke:#03a9f4,stroke-width:3px; classDef terminalStyle fill:#eceff1,stroke:#455a64,stroke-width:3px; class F,A,X startStyle; class I,Y progressStyle; class C,D,H,J,Z,O terminalStyle; ``` # Outgoing Payments ```mermaid theme={null} graph LR subgraph 1: Outgoing status A(["created"]) B(["under_review"]) C(["rejected"]) J(["canceled"]) E(["posted"]) A --> E A -- "Lead manual review" --> B A -- "Lead validation failure or network or counterparty rejection" --> C B -- "Manual review success" --> E B -- "Manual review failure" --> C A -- "You canceled" --> J B -- "You canceled" --> J end E -.- D E -.- L subgraph 3: Outgoing return_request status D(["pending"]) F(["accepted"]) G(["rejected"]) D -- "Counterparty accepted" --> F D -- "Counterparty rejected" --> G end subgraph 2: Outgoing counterparty_status L(["START"]) M(["under_review"]) N(["rejected"]) O(["posted"]) L -- "Counterparty manual review" --> M M -- "Manual review failure" --> N M -- "Manual review success" --> O L -- "Counterparty rejected" --> N L -- "Counterparty accepted" --> O end subgraph State Key direction LR T([Start]) U([Pending]) V([Terminal]) end linkStyle 0 stroke:#155724,stroke-width:2px; classDef startStyle fill:#d4edda,stroke:#155724,stroke-width:3px; classDef progressStyle fill:#e1f5fe,stroke:#03a9f4,stroke-width:3px; classDef terminalStyle fill:#eceff1,stroke:#455a64,stroke-width:3px; classDef brownStyle fill:#efebe9,stroke:#5d4037,stroke-width:2px; classDef invisible fill:none,stroke:none class A,D,W,T,L startStyle; class B,X,U,M progressStyle; class C,E,F,G,J,Y,Z,V,N,O terminalStyle; class H,I brownStyle; ``` # The Instant Payment Object Source: https://docs.lead.bank/products/instant-payments/the-instant-payment-object Send and receive Instant Payments via FedNow and RTP The `instant_payment` object describes both incoming and outgoing payments and is organized into three sections: payment details, related messages, and return requests. ## Payment Details ```json theme={null} { "id": "instant_payment_xyz123", "account_id": "account_xyz123", "account_number_id": "account_number_xyz123", "created_at": "ISO-8601", "updated_at": "ISO-8601", "direction": "enum(incoming|outgoing)", "payment_rail": "enum(fednow|rtp)", "status": "enum(created|under_review|canceled|rejected|posted)", "counterparty_status": "enum(under_review|rejected|posted)", "amount": 5000, "currency_code": "USD", "description": "Payment for invoice 12345", "ultimate_debtor": { "name": "Alex Smith", "account number": "1234567890" }, "debtor": { "name": "Alex Smith", "account number": "1234567890" }, "initiating_party": { "name": "Alex Smith", "account number": "1234567890" }, "debtor_agent": { "routing_number": "987654321" }, "instructing_agent": { "routing_number": "987654321" }, "instructed_agent": { "routing_number": "987654321" }, "creditor_agent": { "routing_number": "987654321" }, "creditor": { "name": "Alex Smith", "account_number": "0987654321" }, "ultimate_creditor": { "name": "Alex Smith", "account_number": "0987654321" }, "payment_identifiers": { "end_to_end_id": "string", "uetr": "string", "transaction_id": "string" }, "return": { "reason": "enum", "details": "string" }, "rejection": { "rejected_by": "enum(lead|network|counterparty)", "reason": "enum", "details": "string" }, ``` ## Related Objects ```json theme={null} "related_objects": { "original_payment_id": "instant_payment_xyz123", "return_payment_ids": ["instant_payment_xyz123"] }, ``` ## Return Requests ```json theme={null} "return_requests": [{ "created_at": "ISO-8601", "deadline": "ISO-8601", "status": "enum(response_needed|pending|rejected|accepted)", "reason": "enum", "details": "string", "resolution": { "resolved_at": "ISO-8601", "resolved_by": "enum(client|lead|network|counterparty)", "rejection_reason": "enum", "rejection_details": "string" } }] ``` # Timing & Availability Source: https://docs.lead.bank/products/instant-payments/timing-and-availability Sending and receiving payments Instant payments are fast and always available. They settle in seconds 24/7/365 and are not subject to business-day or cutoff constraints. # Validations & Best Practices Source: https://docs.lead.bank/products/instant-payments/validations Best practices to reduce instant payment validation exceptions. Lead does not queue instant payments. Instead, synchronous validation failures result in no creation of an `instant_payment` object and an HTTP error response, and asynchronous validation failures result in a `.rejected` webhook and a populated `rejection` hash with additional details. The table below contains a list of validations that Lead performs. We run validations synchronously and asynchronously. | Lead Validation | Best Practice | Direction | | - | - | - | | `parameters_invalid` | Ensure all request parameters are provided and adhere to Lead's rules. | Outgoing | | `non_sufficient_funds` | Check if there are sufficient funds before requesting an outgoing payment. | Outgoing | | `account_number_incorrect` | Check if the sender's account is active before attempting to send an outgoing payment. | Outgoing | | `limit_exceeded` | Request outgoing daily and 30-day payment limits that are consistent with the payment demand you expect. As your business grows, request that Lead increases your limits. | Outgoing | | `routing_number_format_incorrect` | Check if the creditor's routing number is accurate before submitting an instant payment. | Outgoing | | `restricted_by_account_number_controls` | Use account number controls to constraint payment activity within known bounds. Ensure valid payments are not blocked by these restrictions. | Outgoing and incoming | | `participant_not_on_network` | Call the `/check_availability` endpoint to verify that a creditor is enabled for instant payments before creating an outgoing instant payment. | Outgoing | | `participant_signed_off` | This may occur if a counterparty is offline during maintenance or downtime. There is nothing you can do to avoid this error. | Outgoing | | `creditor_name_mismatch` | Ensure your customers and the parties they transact with are aware that creditor names must be accurate. | Incoming | | `regulatory` | Business-to-business payments of \$3,000 or greater must include a debtor address. Ensure your customers' partner banks include it when sending instant payments. | Incoming | # Simulate Advance Wire Source: https://docs.lead.bank/api-reference/endpoint/simulation/simulate-advance-wire-v2 https://docs.lead.bank/openapi.json POST /v2/simulate/wires/{id}/advance Advance a Wire in Sandbox. > [!NOTE] > > See [Errors](/api-reference/using-the-api/errors-v2) for the common errors every v2 endpoint can return. # Simulate Incoming Wire Return Request Acceptance Source: https://docs.lead.bank/api-reference/endpoint/simulation/simulate-incoming-wire-return-request-acceptance-v2 https://docs.lead.bank/openapi.json POST /v2/simulate/wires/{id}/incoming_return_request_acceptance Simulate an incoming wire return request acceptance. > [!NOTE] > > See [Errors](/api-reference/using-the-api/errors-v2) for the common errors every v2 endpoint can return. # Simulate Incoming Wire Return Request Rejection Source: https://docs.lead.bank/api-reference/endpoint/simulation/simulate-incoming-wire-return-request-rejection-v2 https://docs.lead.bank/openapi.json POST /v2/simulate/wires/{id}/incoming_return_request_rejection Simulate an incoming wire return request rejection. > [!NOTE] > > See [Errors](/api-reference/using-the-api/errors-v2) for the common errors every v2 endpoint can return. # Simulate Incoming Wire Return Request Source: https://docs.lead.bank/api-reference/endpoint/simulation/simulate-incoming-wire-return-request-v2 https://docs.lead.bank/openapi.json POST /v2/simulate/wires/{id}/incoming_return_request Simulate an incoming wire return request. > [!NOTE] > > See [Errors](/api-reference/using-the-api/errors-v2) for the common errors every v2 endpoint can return. # Simulate Incoming Wire Return Source: https://docs.lead.bank/api-reference/endpoint/simulation/simulate-incoming-wire-return-v2 https://docs.lead.bank/openapi.json POST /v2/simulate/wires/{id}/incoming_return Simulates an incoming return wire against an outgoing wire in sandbox. Automatically advances to posted on creation. > [!NOTE] > > See [Errors](/api-reference/using-the-api/errors-v2) for the common errors every v2 endpoint can return. # Simulate Incoming Wire Source: https://docs.lead.bank/api-reference/endpoint/simulation/simulate-incoming-wire-v2 https://docs.lead.bank/openapi.json POST /v2/simulate/wires/incoming Simulates an incoming wire against a creditor account in sandbox. Automatically advances to posted on creation; no call to advance required. > [!NOTE] > > See [Errors](/api-reference/using-the-api/errors-v2) for the common errors every v2 endpoint can return. # Cancel a Wire Source: https://docs.lead.bank/api-reference/endpoint/wire/cancel-a-wire-v2 https://docs.lead.bank/openapi.json POST /v2/wires/{id}/cancel Cancel a wire object. > [!NOTE] > > See [Errors](/api-reference/using-the-api/errors-v2) for the common errors every v2 endpoint can return. # Create a Wire Source: https://docs.lead.bank/api-reference/endpoint/wire/create-a-wire-v2 https://docs.lead.bank/openapi.json POST /v2/wires Create a new outgoing wire > [!NOTE] > > See [Errors](/api-reference/using-the-api/errors-v2) for the common errors every v2 endpoint can return. # List all Wires Source: https://docs.lead.bank/api-reference/endpoint/wire/list-all-wires-v2 https://docs.lead.bank/openapi.json GET /v2/wires List all wire objects. > [!NOTE] > > See [Errors](/api-reference/using-the-api/errors-v2) for the common errors every v2 endpoint can return. # Reject a Return Request for a Wire Source: https://docs.lead.bank/api-reference/endpoint/wire/reject-return-request-for-wire-v2 https://docs.lead.bank/openapi.json POST /v2/wires/{id}/reject_return_request Reject the currently active incoming return request associated with the wire. > [!NOTE] > > See [Errors](/api-reference/using-the-api/errors-v2) for the common errors every v2 endpoint can return. # Request Return for a Wire Source: https://docs.lead.bank/api-reference/endpoint/wire/request-return-for-wire-v2 https://docs.lead.bank/openapi.json POST /v2/wires/{id}/request_return Create a return request for a previously sent outgoing wire. > [!NOTE] > > See [Errors](/api-reference/using-the-api/errors-v2) for the common errors every v2 endpoint can return. # Retrieve a Wire Source: https://docs.lead.bank/api-reference/endpoint/wire/retrieve-a-wire-v2 https://docs.lead.bank/openapi.json GET /v2/wires/{id} Retrieve a wire object. > [!NOTE] > > See [Errors](/api-reference/using-the-api/errors-v2) for the common errors every v2 endpoint can return. # Return a Wire Source: https://docs.lead.bank/api-reference/endpoint/wire/return-a-wire-v2 https://docs.lead.bank/openapi.json POST /v2/wires/{id}/return Initiate a return against an incoming wire. > [!NOTE] > > See [Errors](/api-reference/using-the-api/errors-v2) for the common errors every v2 endpoint can return. # Update a Wire Source: https://docs.lead.bank/api-reference/endpoint/wire/update-a-wire-v2 https://docs.lead.bank/openapi.json PATCH /v2/wires/{id} Update a wire. > [!NOTE] > > See [Errors](/api-reference/using-the-api/errors-v2) for the common errors every v2 endpoint can return.