Embedded Sub-Accounts

Use this pattern when your platform needs to give each downstream customer their own ledger context, wallet set, and receiving details under your master integration.

✅ Before you start

Complete these steps before you build the embedded account flow:

Authenticate with your master platform credentials.
Confirm you are implementing an Atlas platform flow rather than a direct own-funds flow.
Decide what customer identity and compliance data you will collect before onboarding.
Prepare to store the returned sub-account ID and wallet IDs because you will reuse them throughout the flow.

📚 Use this page with the recipe

This guide explains when to use embedded sub-accounts and the minimum workflow. For the implementation sequence, use the recipe:

Embedded Sub-Accounts Recipe →

🧭 Implementation Context

🏦 Atlas for Fintech (Licensed)	🏢 Atlas for Platforms (Non-Licensed)
Compliance: You own the KYB process. You pass us metadata, but you maintain the legal relationship with the end-user.	Compliance: Verto handles the KYB process via our Onboarding API. The end-user must be vetted by Verto before the sub-account activates.
Account Identity: `OWNED_BY_FINTECH`.	Account Identity: `PARTNER_REFERRED`.

1️⃣ Step 1: Provision the Sub-Account

The embedded sub-account workflow is:

Create the sub-account for the downstream customer.
Wait for onboarding and approval before enabling operational actions.
Create wallets in that customer context.
Issue account details if the customer needs to receive funds.
Use the same context for statements, beneficiaries, payouts, and balance views.

What makes this use case different?

Unlike the product guides, this workflow is specifically for platforms that need to:

isolate ledger activity per customer
show customer-specific balances in an embedded UI
issue receiving details in the correct downstream context
keep later payout and reconciliation actions tied to the same sub-account

Where to go deeper

Use the product guides when you need implementation detail for a specific step:

Troubleshooting

Issue	What to check
Sub-account cannot receive or transact	Confirm the customer has completed the required compliance review and the sub-account is operationally active.
Wallet or account is created for the wrong customer	Check whether the `X-Sub-Account-Id` header matches the intended downstream customer.
Embedded UI shows incomplete bank details	Display the exact fields returned for the corridor, including any required payment reference.
Balance or statement data looks incorrect	Re-fetch the statement in the same sub-account context and compare it with receive and payout webhook activity.

Next steps


Create Wallets for a Sub-Account → Provision the first downstream wallet in the correct customer context.	Login as a Sub-Account and Run a Scoped Action → Use a customer-specific token for embedded sessions and scoped actions.