> ## 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 a balance, Account Numbers to receive money, and a movement 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 differ in what Fintoc tracks and whether each user needs Know Your Customer (KYC). Start with the pattern that requires the fewest per-user resources 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 balance.
* 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.

Use this pattern when you track each user's wallet balance in your database.

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

* Structure: **many** `Account` objects, all under your `Entity`. Each `Account` has its own balance and root Account Number.
* Per-user balance: Fintoc tracks each user's balance at the `Account` level. You can view the balance 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. Create an `Account` by sending `POST /v2/accounts` with your `Entity`'s ID. The new `Account` includes a root Account Number.
2. On `transfer.inbound.succeeded`, use `data.account_id` to identify the user.
3. Use `data.account_id` as the source of funds for withdrawals.

Use this pattern when you want Fintoc to track wallet balances per user. This pattern works in Mexico and Chile.

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

* Structure: **many** `Entity` objects (one per client). Each `Entity` has one or more `Account` objects and root Account Numbers.
* Per-user balance: Fintoc tracks each user's balance at the `Account` level.
* KYC: required per `Entity`. You run KYC through the API without using the dashboard.

```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 through the API. Follow [Onboard an Entity by API](/guides/transfers/manage-accounts/onboard-an-entity-by-api) to create the `Entity`, upload company and shareholder documents, and submit the onboarding.
2. Wait for the `entity.onboarding.approved` webhook or poll the onboarding status to confirm approval.
3. Create one or more `Account` objects under the `Entity` by sending `POST /v2/accounts` with the `Entity`'s `entity_id`. Each `Account` has its own balance and root Account Number. A client `Entity` can hold more than one sub-account, as in Pattern B. Outbound transfers show the client's legal name on the Comprobante Electrónico de Pago, the Mexican payment receipt.

Use this pattern when receipts must show the client's legal name. For example, a food delivery platform can pay each restaurant under the restaurant's Mexican tax ID (RFC). This pattern supports onboarding Mexican `Entity` objects through the API without 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           | ❌         | ❌         | ✅         |