When platform engineers first ask me about sub-account provisioning, the question is usually framed around complexity: "How hard is it to give each of our merchants their own account?" The honest answer is that the API call itself is about four lines of code. Everything upstream of that call — the banking relationships, the KYC pipeline, the ledger infrastructure, the compliance hooks — is where the real engineering lives. This article walks through all of it.
What a Sub-Account Actually Is
A sub-account — sometimes called a virtual account or merchant wallet — is a segregated financial account associated with a specific merchant on your platform, held inside a larger pooled deposit structure at a sponsor bank. Each sub-account has a unique account number and routing number, meaning merchants can receive ACH deposits and push payments just like they would from a standalone bank account.
The key distinction from a simple ledger balance is that the routing and account numbers are real — they work with the ACH network and can receive external bank transfers, direct deposits from payroll processors, and third-party ACH pushes. From a merchant's perspective, the sub-account functions identically to a business checking account. From the platform's perspective, it is an API-managed record with real banking rails underneath.
The pooled structure at the sponsor bank is what makes this possible without requiring each merchant to open their own bank account. The sponsor bank holds a master FBO (For Benefit Of) account; sub-accounts are segregated units within that FBO. FDIC pass-through insurance applies per beneficial owner, meaning each merchant's balance is insured up to $250,000 independently — not as a share of the pooled balance.
The Provisioning Flow: What Happens Between API Call and Live Account
When a platform calls the Mainstreetspine provisioning endpoint with a merchant's business information, the following sequence runs — largely invisible to the calling application:
- Identity collection: The API accepts the merchant's legal business name, EIN (or SSN for sole proprietors), business address, and beneficial owner information for entities with 25%+ ownership stakes. This data format follows FinCEN's CDD Rule (Customer Due Diligence).
- KYB verification: The business entity is checked against state formation records and the IRS TIN matching database. Response time is typically under 8 seconds for entities that appear in standard business registries.
- KYC for beneficial owners: Individual owners are checked via automated identity verification — name, SSN, date of birth, and address matched against bureau data. OFAC and other watchlist screening runs concurrently.
- Account provisioning: On KYC/KYB pass, a sub-account record is created in the Mainstreetspine ledger and a unique routing + account number pair is assigned from the sponsor bank's FBO account structure.
- Webhook notification: The platform receives a
merchant.account.provisionedwebhook with the account details, typically within 45-90 seconds of the initial API call for merchants that pass straight-through processing.
For merchants that trigger manual review — typically because the business entity cannot be automatically matched, or because OFAC screening returns a potential hit — the account is held in pending status while the compliance team reviews. In our data, approximately 91% of provisioning requests complete straight-through without manual review. The remaining 9% require additional documentation, which we request via the platform's merchant-facing UI using a configurable document collection flow.
KYC Requirements at the API Level
The minimum data required to initiate a provisioning request is deliberately kept small to reduce onboarding friction:
| Business Type | Required Fields | Typical Verification Time |
|---|---|---|
| Sole Proprietor / DBA | Name, SSN last 4, address, DOB | Under 60 seconds |
| LLC (single-member) | Business name, EIN, state of formation, owner SSN last 4 | Under 90 seconds |
| LLC or Corp (multi-member) | Business name, EIN, state of formation, beneficial owners (25%+) with SSN last 4 each | Under 3 minutes |
| Any entity (OFAC hit or name mismatch) | Government-issued ID + EIN confirmation letter required | 1-3 business days (manual review) |
We strongly recommend collecting EIN at your platform's existing merchant onboarding, even if you are not yet live with sub-accounts. Retrofitting KYC data collection to an established merchant base is one of the most friction-intensive steps in any embedded finance launch.
The Ledger: How Money Moves and Gets Recorded
Every financial event against a sub-account — inbound ACH, outbound transfer, fee debit, interest credit — generates a double-entry ledger record. The credit side records the increase to the merchant's sub-account balance; the debit side records the corresponding decrease in the FBO master account's available balance, or vice versa for outbound transactions.
This structure matters for two reasons. First, it makes real-time balance calculation deterministic — the current balance is always the sum of all posted entries, with no batch-close or end-of-day reconciliation required. Merchants see accurate available balances without the 24-hour delay that legacy batch systems produce. Second, it gives platforms an immutable audit trail from day one. Every entry has a timestamp, a transaction reference, and a counterparty. Regulatory requests — SAR responses, subpoenas, dispute arbitration — are answered from the same ledger that powers the merchant UI, not a separate reporting database.
What Platform Engineers Need to Handle (and What We Handle)
There is a common misconception that using an embedded finance provider means the platform bears no compliance responsibility. This is not accurate. Here is the actual division:
We own: sponsor bank relationship, FDIC deposit insurance structure, KYC/KYB verification pipeline, OFAC and watchlist screening, ongoing transaction monitoring, SAR filing, BSA annual report filing to FinCEN, card network compliance (if using virtual cards).
The platform owns: collecting required KYC data from merchants during onboarding, presenting account disclosures and terms at the point of account opening, maintaining records of merchant consent to financial product terms, and not knowingly onboarding merchants whose business type is excluded from the program (see program exclusions in the API documentation for the current list).
This division is contractual and explicit. We provide the compliance stack as infrastructure; the platform is responsible for the merchant-facing disclosures and data collection that feed that stack. Neither party can delegate the other's responsibilities.
Edge Cases Worth Planning For
A few implementation details that frequently come up in integration reviews:
Merchant account closure: When a merchant churns from your platform, their sub-account must be formally closed through the API, not just deactivated in your UI. Outstanding balances must be disbursed to the merchant's linked external account before closure. We provide a 30-day closure workflow with configurable notification triggers.
Frozen accounts: If a merchant's account is frozen due to a compliance hold, the platform's admin API will surface the hold reason (encoded, not plain-text for compliance reasons) and the expected resolution path. Platforms cannot unfreeze accounts themselves — this is by design, as the freeze decision involves our compliance team and the sponsor bank.
Multi-location merchants: A restaurant group operating 8 locations should typically have one sub-account per legal entity, not per location. The API supports parent-child merchant structures for consolidated reporting across entities while maintaining per-entity account segregation for compliance purposes.
Sub-account provisioning sounds like infrastructure plumbing, and in execution it largely is. But the merchant experience sitting on top of that plumbing — instant account creation, real-time balance visibility, same-day payout access — is what actually drives the platform retention metrics. Getting the engineering details right is the prerequisite for getting those outcomes.
