> For the complete documentation index, see [llms.txt](https://docs.xyb.co/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.xyb.co/xyb-platform-1/accounts/getting-started-with-accounts/planning-your-account-structure-and-setup.md). # Planning Your Account Structure & Setup Before you create your first customer account, it’s important to **design your account setup**. This ensures the service fits your product, compliance needs, and financial architecture, whether you’re using all of XYB or integrating your own systems. *** ### Why Planning Matters XYB Accounts is not just a database of users. It's a **configurable engine** that manages how funds, identities, and financial behavior are structured in your platform. Without planning, you might: * Create accounts that don’t align with your ledger * Miss critical metadata needed for compliance or reporting * End up with wallets that don’t match how your customers operate *** ### Key Questions to Ask Before You Begin | Category | Questions to Consider | | ------------------------- | ----------------------------------------------------------------------------- | | **Product Intent** | What is this account used for? (Retail, savings, FX, crypto?) | | **Structure** | How many wallets per account? Multi-currency? Default currency? | | **Compliance** | What data is required? (jurisdiction, KYC, entity linkage?) | | **Lifecycle** | What should happen when an account is suspended, reopened, or closed? | | **Integrations** | Are you using your own ledger? Own payments stack? Or XYB’s? | | **Statements & Balances** | Do you need daily statements? Global balance views? Kafka push notifications? | *** ### Components You Need to Think Through #### 1. **Product Configuration** Every account in XYB is tied to a **product configuration**. This config defines: * Wallet currencies and codes * Ledger and banking providers * Visibility rules * Default attributes * Jurisdiction and compliance controls Example: A "Premium Retail Account" product might include: * EUR + USD wallets * TCC for banking coordinates * Statement push enabled * Four-Eye policy for state changes *** #### 2. **Ledger Strategy** You can: * Use **XYB Ledger** (built-in) * Use **Thought Machine** or **other third-party ledgers** * Skip ledger linkage entirely if you just need metadata + identity Make sure your **ledger and wallet codes** are planned to match how your accounting or transaction processing works. *** #### 3. **Wallet Strategy** Accounts in XYB can hold multiple wallets, and you define: * Which currencies are supported * Which wallet is the "default" * Whether a wallet should be auto-created on account creation * How wallets sync with ledger balances Tip: Plan for both **current** and **future currencies:** wallet creation can be additive later, but metadata compatibility matters. *** #### 4. **Banking Coordinates** You can attach banking details like: * IBAN * BIC * Routing codes * Account numbers These are often provided by a third-party like **CurrencyCloud**, or generated internally based on rules. Plan for: * Which fields are needed per region (IBAN vs routing code) * How many coordinates per account * Which tags or external references you’ll need *** #### 5. **Entity & Jurisdiction Mapping** Every account must belong to an **owning entity,** a customer, business, or organization. The system allows for: * Multiple accounts per entity * Mandates to define ownership * Jurisdiction-specific fields for compliance Make sure your **Entity Service** is integrated (XYB provides one), or align your internal customer model. *** #### 6. **Four-Eye Workflows (Optional)** For extra control, you can enforce: * Approval steps for suspending/finalizing accounts * Policy-based conditions (e.g., certain account types require approval) You can configure this later, but it’s best to know upfront if you want **compliance controls baked in**. *** ### Planning Summary | Setup Area | Required? | Configured Via | Notes | | ------------------- | --------- | ---------------------------- | ------------------------------------------------ | | Product Config | Yes | Product Factory / Config API | Core definition of behavior and wallets | | Ledger Provider | Optional | Product config + Strategy | Can be XYB, TM, or none | | Wallets | Yes | Config + Account creation | Defines currencies + linkage to ledger | | Banking Coordinates | Optional | Config or Manual | Based on payments integration needs | | Entities | Yes | Entity Service | Each account must belong to an entity | | Four-Eye Policies | Optional | FourEye Policy Service | Enforced via Kafka + internal approval workflows | *** --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.xyb.co/xyb-platform-1/accounts/getting-started-with-accounts/planning-your-account-structure-and-setup.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.