> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fintoc.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Wallet for end users

## What you'll build

Build a system where each of your end users has their own balance, Account Numbers to receive money, and a movements history.

## When to use it

Reach for this pattern when your product holds a balance per end user:

* Neobanks and fintech apps.
* B2B platforms holding client funds.
* Marketplaces or gig platforms where sellers accumulate earnings before cashing out.

## Three patterns: pick one

You can model a user wallet on Fintoc in three ways. The patterns are ordered by how much Fintoc tracks for you and whether each user needs Know Your Customer (KYC). Start with the pattern that needs the least per-user setup and still fits your requirements.

### Pattern A: one Account Number per user (virtual Account Numbers)

* Structure: **one** Fintoc `Account` (yours) with **many** Account Numbers, one per user.
* Per-user balance: you track it in your own database. Fintoc holds the aggregate.
* KYC: none per user. Only your root `Entity` is onboarded.

```mermaid theme={null}
flowchart LR
    S1[Sender for user 1] -->|Incoming transfer| C1[Account Number 1]
    S2[Sender for user 2] -->|Incoming transfer| C2[Account Number 2]
    C1 --> A[Your Account<br/>single total balance]
    C2 --> A
    A -.webhook.-> DB[(Your DB<br/>balance_user1 += amount)]
```

Set up:

1. Use your root `Account`.
2. Create one Account Number per user with `metadata.user_id`.
3. On `transfer.inbound.succeeded`, credit the user's balance in your database.
4. For withdrawals, create an outbound `Transfer` from your root `Account` and debit the user's balance in your database.

Good for: wallets where you track each user's balance in your database.

### Pattern B: one Account per user under your Entity (sub-accounts)

* Structure: **many** `Account` objects, all under your `Entity`. Each has its own balance and its own root Account Number.
* Per-user balance: Fintoc tracks it at the `Account` level. Visible in the Dashboard and statements.
* KYC: none per user.

```mermaid theme={null}
flowchart LR
    S1[Sender for user 1] -->|Incoming transfer| C1[Account Number 1]
    S2[Sender for user 2] -->|Incoming transfer| C2[Account Number 2]
    C1 --> A1[Account: user 1<br/>own balance]
    C2 --> A2[Account: user 2<br/>own balance]
    A1 -.webhook.-> You[(Your backend)]
    A2 -.webhook.-> You
```

Set up:

1. `POST /v2/accounts` with your `Entity`'s ID. The `Account` is created with a root Account Number.
2. On `transfer.inbound.succeeded`, use `data.account_id` to identify the user.
3. Withdrawals use that `account_id` as the source of funds.

Good for: wallets where you want Fintoc to ledger balances per user. Works in Mexico and Chile.

### Pattern C: one Account per user under their own Entity

* Structure: **many** `Entity` objects (one per client), each with one or more `Account` objects and root Account Numbers.
* Per-user balance: Fintoc tracks it at the `Account` level.
* KYC: required per `Entity`, and you run it by API. No Dashboard step.

```mermaid theme={null}
flowchart LR
    P[Your platform] -->|Create + onboard by API| E1[Client A Entity]
    P -->|Create + onboard by API| E2[Client B Entity]
    E1 -->|on entity.onboarding.approved| A1[One or more Accounts<br/>under Client A]
    E2 -->|on entity.onboarding.approved| A2[One or more Accounts<br/>under Client B]
    A1 -->|"Mexican payment receipt: Client A name"| O1[Client A bank]
    A2 -->|"Mexican payment receipt: Client B name"| O2[Client B bank]
```

Set up:

1. Create the client's `Entity` and run its KYC review by API. The [Onboard an Entity by API](/docs/transfers/manage-accounts/onboard-an-entity-by-api) guide walks the full sequence: create the `Entity`, upload company and shareholder documents, then submit.
2. Wait for the `entity.onboarding.approved` webhook, or poll the onboarding, to confirm the `Entity` is approved.
3. Create one or more `Account` objects under that `Entity` with `POST /v2/accounts` and the `Entity`'s `entity_id`. Each `Account` has its own balance and root Account Number. A single client `Entity` can hold several sub-accounts, as in Pattern B. Outbound transfers from each `Account` show the client's legal name on the Comprobante Electrónico de Pago, the Mexican payment receipt.

Good for flows where receipts must show the client's legal name, such as a food delivery platform that pays each restaurant under that restaurant's Mexican tax ID (RFC). Use this pattern when you onboard Mexican `Entity` objects at scale without manual Dashboard steps. For other countries, create the `Entity` from the Dashboard.

## Choosing between them

This table compares the three wallet patterns:

| Capability                          | Pattern A | Pattern B | Pattern C |
| ----------------------------------- | --------- | --------- | --------- |
| Per-user balance ledgered by Fintoc | ❌         | ✅         | ✅         |
| Unique Account Number per user      | ✅         | ✅         | ✅         |
| KYC per user                        | ❌         | ❌         | ✅         |
| Receipts show user's name           | ❌         | ❌         | ✅         |